npm package: @0day-network/zerocode-cli
Description: ZeroCode CLI for building and publishing modular Web3 components
Author: 0day Network
Latest version: 1.0.23

# ZeroCode CLI

A comprehensive Node.js/TypeScript CLI for bundling React components and publishing them to the URT protocol.

## Features

- **Component Bundling**: Single-file ESM bundles with tree-shaking and minification
- **Manifest Generation**: Automatic generation of prepublish and publish manifests
- **Offchain Storage**: Integration with p2p-0storage for decentralized content storage
- **Onchain Publishing**: Direct integration with URT protocol smart contracts
- **Development Mode**: File watching with automatic rebuilds
- **Wallet Management**: Built-in wallet generation and management

## Installation

### Global Installation (Development Mode)

For development with the local CLI from source:

```bash
# From the zerocode-cli directory
cd packages/zerocode-cli
npm install
npm run build
npm link

# Now you can use 'zc' globally
zc --help
```

To unlink later:

```bash
npm unlink -g zerocode-cli
```

### Production Installation

```bash
npm install -g zerocode-cli
zc --help
```

## Development Setup (Local/From Source)

### Prerequisites

Make sure you have the following services running locally:

- **p2p-0storage**: Running on `http://localhost:4000`
- **Local blockchain**: Anvil, Hardhat, or testnet
- **Core protocol**: Deployed URT contracts

### Step-by-Step Setup

1. **Clone and setup the CLI** (development mode)

   ```bash
   # From the monorepo root
   cd packages/zerocode-cli
   npm install
   npm run build

   # Link for global access (optional)
   npm link
   ```

2. **Initialize a new project**

   ```bash
   # Create a new directory for your components
   mkdir my-zerocode-project
   cd my-zerocode-project

   # Option 1: Using global CLI (if npm linked)
   zc init --dev --git --ui

   # Option 2: Direct CLI execution (from source)
   npx tsx ../../packages/zerocode-cli/bin/cli.ts init --dev --git --ui

   # Option 3: Basic init without flags
   zc init
   ```

   Available flags:

   - `--dev`: Generate package.json with local CLI references for monorepo development
   - `--git`: Initialize git repository and create initial commit
   - `--ui`: Generate additional UI components (input, textarea, select, etc.)
   - `--force`: Overwrite existing configuration files

3. **Configure environment variables**

   ```bash
   # Edit the generated .env file
   nano .env
   ```

   Set the required variables:

   ```env
   # Generate a new wallet or use existing one
   PRIVATE_KEY=0x1234567890abcdef...

   # Deploy a URT contract (see step 4) and set its address
   URT_ADDRESS=0xYourURTContractAddress

   # Local services
   P2P_URL=http://localhost:8787
   CHAIN_ID=31337  # For local Anvil
   RPC_URL=http://localhost:8545

   # Registry address from core deployment
   REGISTRY_ADDRESS=0xRegistryContractAddress

   # Model IDs are pre-configured with defaults
   ```

4. **Deploy URT contract** (if needed)

   ```bash
   # From the core directory
   cd ../../core
   npm install
   npm run build

   # Start local blockchain (if not already running)
   npx hardhat node
   # or
   anvil

   # Deploy contracts (in another terminal)
   npx hardhat run scripts/00_deploy_local.ts --network localhost

   # Copy the URT address from deployment output to your .env
   ```

5. **Start p2p-0storage** (if not already running)

   ```bash
   # From the p2p-0storage directory
   cd ../../p2p-0storage
   npm install
   npm start
   # Should be running on http://localhost:8787
   ```

6. **Configure the CLI project**

   ```bash
   # Back to your project directory
   cd my-zerocode-project

   # Update zerocode.yaml with your addresses
   nano zerocode.yaml
   ```

   Update the publisher and registry addresses:

   ```yaml
   publisher: "0xYourSignerAddress" # Address derived from PRIVATE_KEY
   registry: "0xYourRegistryAddress" # From core deployment
   ```

7. **Check system health**

   ```bash
   npx tsx ../../packages/zerocode-cli/bin/cli.ts health
   ```

   This command will verify:

   - Configuration files are valid
   - Environment variables are set
   - URT authentication is working
   - p2p-0storage is reachable
   - Model IDs are configured

8. **Build components**

   ```bash
   # Build all components
   npx tsx ../../packages/zerocode-cli/bin/cli.ts build --all

   # Or build specific component
   npx tsx ../../packages/zerocode-cli/bin/cli.ts build --component Hero
   ```

9. **Validate manifests**

   ```bash
   npx tsx ../../packages/zerocode-cli/bin/cli.ts validate --all
   ```

10. **Development workflow**

    ```bash
    # Start development mode (auto-rebuild on changes)
    npx tsx ../../packages/zerocode-cli/bin/cli.ts dev

    # In another terminal, test commit (offchain)
    npx tsx ../../packages/zerocode-cli/bin/cli.ts commit --all

    # Test publish (onchain) - requires funded wallet
    npx tsx ../../packages/zerocode-cli/bin/cli.ts publish --all
    ```

### Development Tips

- **Hot reload**: Use `zc dev` to automatically rebuild on file changes
- **Check wallet**: Use `zc whoami` to verify configuration
- **Health check**: Use `zc health` to diagnose issues
- **Mock mode**: CLI falls back to mocks if services are unavailable
- **Local testing**: All operations work with local blockchain and p2p-0storage

### Troubleshooting

**CLI not found**: Use full path `npx tsx ../../packages/zerocode-cli/bin/cli.ts` instead of `zc`

**URT authentication failed**: Verify `URT_ADDRESS` and `PRIVATE_KEY` match deployed contract

**P2P-0storage unreachable**: Make sure p2p-0storage is running on port 8787

**Transaction failed**: Ensure your wallet has sufficient ETH for gas

**Build errors**: Check that your React components follow the expected structure

## Production Setup (Published CLI)

For production use, install the CLI from npm:

```bash
npm install -g zerocode-cli
zc init
# Follow the same steps as development mode
```

## Commands

### `zc init`

Initialize a new zerocode project with example components and configuration.

Options:

- `-f, --force`: Overwrite existing configuration

### `zc build`

Bundle components into single-file ESM modules and generate manifests.

Options:

- `-c, --component <name>`: Build specific component
- `-a, --all`: Build all components

### `zc validate`

Validate component manifests against JSON schemas.

Options:

- `-c, --component <name>`: Validate specific component
- `-a, --all`: Validate all components

### `zc commit`

Commit components to offchain storage (p2p-0storage).

Options:

- `-c, --component <name>`: Commit specific component
- `-a, --all`: Commit all components

### `zc publish`

Publish components onchain to URT protocol contracts.

Options:

- `-c, --component <name>`: Publish specific component
- `-a, --all`: Publish all components

### `zc dev`

Start development mode with file watching and automatic rebuilds.

Options:

- `-c, --component <name>`: Watch specific component (default: all)

### `zc whoami`

Display current wallet address, URT configuration, and authentication status.

### `zc login`

Configure wallet for onchain operations.

Options:

- `--new`: Generate a new wallet
- `--key <privateKey>`: Use existing private key

### `zc health`

Check system health and configuration status. Verifies:

- Configuration files
- Environment variables
- URT authentication
- p2p-0storage connectivity
- Model IDs setup

## Configuration

The CLI is configured via `zerocode.yaml`:

```yaml
name: "zerocode-modules"
publisher: "0xYourAddress"
chainId: 8453 # Base mainnet
rpcUrl: "https://mainnet.base.org"
registry: "0xRegistryAddress"

storage:
  driver: "p2p-0storage"
  baseUrl: "http://localhost:8787"

build:
  outdir: "./dist"
  format: "esm"
  target: "es2022"
  minify: true
  external:
    - react
    - react-dom

resolveAliases:
  "@/components": "./src/components"
  "@/lib": "./src/lib"

components:
  - name: "Hero"
    entry: "./src/components/Hero/index.tsx"
    version: "0.1.0"
    description: "Hero section component"
    # ... component configuration
```

## Environment Variables

Create a `.env` file with:

```env
# ===== AUTHENTICATION =====
# Private key for your URT (Universal Responsibility Token)
PRIVATE_KEY=your_private_key_here

# Your URT contract address (each module is published from its own URT)
URT_ADDRESS=0xYourURTContract

# ===== P2P STORAGE =====
# P2P-0storage API endpoint for offchain storage
P2P_URL=http://localhost:8787

# Optional: IPFS API if p2p-0storage uses IPFS backend
IPFS_API_URL=http://127.0.0.1:5001

# ===== BLOCKCHAIN =====
# Chain ID (8453 = Base mainnet, 84532 = Base Sepolia)
CHAIN_ID=8453

# RPC endpoint for blockchain interactions
RPC_URL=https://mainnet.base.org

# URT Registry contract address (from core protocol deployment)
REGISTRY_ADDRESS=0xRegistryContract
```

### URT Authentication

The CLI uses **URT-based authentication** for all operations:

1. **Each module is published from its own URT contract**
2. **The URT uses EIP-1271 (`isValidSignature`) for authentication**
3. **P2P-0storage requires URT signatures for all operations**
4. **Onchain publishing is done via URT's `callContract` function**

Make sure your `PRIVATE_KEY` corresponds to the admin of the `URT_ADDRESS` contract.

## Project Structure

After initialization:

```
your-project/
├── zerocode.yaml          # CLI configuration
├── .env                   # Environment variables
├── src/
│   └── components/
│       ├── Hero/
│       │   ├── index.tsx
│       │   └── props.schema.ts
│       └── Button/
│           └── index.tsx
└── dist/                  # Build output
    ├── Hero/
    │   ├── index.js
    │   ├── build.manifest.json
    │   ├── publish.manifest.json
    │   ├── commit.result.json
    │   └── publish.result.json
    └── Button/
        └── ...
```

## Development

### Building from source

```bash
npm run build
```

### Running in development

```bash
npm run dev
```

## Integration

The CLI integrates with:

- **p2p-0storage**: For offchain content storage with URT authentication
- **URT Core Contracts**: For URT-based onchain module registration via `callContract`
- **URT Protocol**: Each module is published from its own URT using EIP-1271 signatures
- **Zerocode App**: Optional hooks for UI integration

### URT Protocol Integration

1. **Authentication**: All operations use URT's `isValidSignature` (EIP-1271)
2. **Publishing**: Modules are published via URT's `callContract` function
3. **Verification**: P2P-0storage verifies signatures against URT contracts
4. **Ownership**: Each module belongs to a specific URT, enabling decentralized governance

## License

MIT