npm package: @nexstem/node-cli
Description: CLI tool for packing and pushing operator registry nodes to the registry
Author: Nexstem
Latest version: 1.0.3
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Node CLI

CLI tool for managing operator registry nodes. This tool helps you create, validate, and push operators to the registry.

## Installation

```bash
cd tools/node-cli
npm install
npm run build   # compile the TypeScript sources to dist/
```

> Tip: rerun `npm run build` whenever you change the CLI source before invoking `node-cli`.

## Usage

### Init - Create Operator Structure

Creates a folder structure template for a new operator:

```bash
node-cli init <operator-name> [options]
```

**Options:**
- `-d, --dir <directory>` - Target directory (default: current directory)

**Example:**
```bash
node-cli init myoperator
# Creates: ./myoperator/
#   - lib/
#   - meta.json
```

During initialization the CLI will prompt you for key metadata (name, version, description, authors, tags, OS, architecture, entrypoint). Defaults are provided so you can hit enter to accept them.

### Validate - Validate Operator

Validates the meta.json and folder structure:

```bash
node-cli validate <operator-path>
```

**Example:**
```bash
node-cli validate operator_registry_nodes/myoperator
# or
node-cli validate ./myoperator
```

**Checks:**
- Folder structure (lib/ directory exists)
- meta.json exists and is valid JSON
- All required fields in meta.json
- Data type specifications
- Parameter definitions
- Signal definitions
- Entrypoint library exists

### Push - Push to Registry

Validates, packages, and pushes operator to registry:

```bash
node-cli push <operator-path> [options]
```

**Options:**
- `-r, --registry <url>` - Registry URL (or set `OPERATOR_REGISTRY_URL` env var)
- `-t, --token <token>` - Authentication token (or set `OPERATOR_REGISTRY_TOKEN` env var)

**Example:**
```bash
node-cli push operator_registry_nodes/myoperator --registry https://registry.example.com/api/operators --token your-token
```

**Process:**
1. Validates the operator (same as `validate` command)
2. Creates a tar.gz archive: `{operator-name}-{version}.tar.gz`
3. Uploads to registry via POST request
4. Cleans up temporary archive

## Environment Variables

- `OPERATOR_REGISTRY_URL` - Default registry URL
- `OPERATOR_REGISTRY_TOKEN` - Default authentication token

## Operator Structure

```
operator_registry_nodes/
└── myoperator/
    ├── lib/
    │   └── libmyoperator.dylib  # Your shared library
    └── meta.json                 # Operator metadata
```

## Meta.json Validation

The validator checks:

### Required Fields
- `name` - Must be lowercase, start with letter, alphanumeric + underscores
- `version` - Semantic versioning (e.g., "1.0.0")
- `description` - Human-readable description
- `authors` - Non-empty array
- `created_at` - YYYY-MM-DD format
- `tags` - Array of strings
- `os` - One of: darwin, linux, windows
- `arch` - One of: arm64, x64, x86
- `entrypoint` - Library filename (must match OS)
- `input_types` - Array of data type definitions
- `output_types` - Array of data type definitions
- `parameters` - Array of parameter definitions
- `signals` - Array of signal definitions

### Data Types
- `"any"` - Accepts any data type
- `number` - Requires `subtype`: integer, double, or float
- `string` - Text values
- `boolean` - True/false
- `array` - Requires `items` field
- `object` - Requires `properties` array
- `enum` - Requires `subtype`, `options`, and optionally `number_subtype`

### Parameters
- Must have `name` and `type`
- `required` - Boolean (default: false)
- `depends_on` - Conditional requirement
  - `parameter` - Name of parameter to depend on
  - `equals` - Value must equal
  - `in` - Value must be in array

### Signals
- Must have `name` and `description`
- `parameters` - Array of signal parameters
- `standard` - Boolean indicating standard signal

## Examples

### Create a new operator

```bash
# 1. Create structure
node-cli init myfilter

# 2. Copy your shared library
cp build/libmyfilter.dylib myfilter/lib/

# 3. Edit meta.json with your operator details

# 4. Validate
node-cli validate myfilter

# 5. Push to registry
node-cli push myfilter \
  --registry https://registry.example.com/api/operators \
  --token your-auth-token
```

## Error Handling

The CLI will:
- Exit with code 1 on validation errors
- Show detailed error messages
- Warn about missing files but allow validation to pass
- Clean up temporary files on push errors

## See Also

- [META_JSON_DOCUMENTATION.md](../../META_JSON_DOCUMENTATION.md) - Complete meta.json schema documentation