@eigenpal/cli 0.0.1 → 0.4.2

package/dist/skill/reference/workflow-yaml.md

@@ -0,0 +1,304 @@
+# workflow.yaml — required schema
+
+A workflow is a DAG of named steps with named inputs, named outputs, and
+trigger metadata. The full Zod schema lives in
+`@eigenpal/types/src/workflow/` and ships with the CLI — query the
+authoritative shape per step type with:
+
+```bash
+eigenpal workflow step-type list         # all step types
+eigenpal workflow step-type get <type>   # JSON Schema for one type's config + output
+```
+
+## Top-level required fields
+
+```yaml
+name: extract-invoices # string, lowercase kebab/snake-case, unique within tenant
+version: 1.0.0 # bare semver `MAJOR.MINOR.PATCH`, no leading `v`
+description: Parse a PDF and extract invoice fields. # string, optional
+triggerMethods: [api] # array, ≥1 entry from: api | cron | email
+inputs: [...] # array of input definitions (see below)
+steps: [...] # array of steps, executed in topological order
+output: {...} # object — the workflow's return shape
+```
+
+`name` + `version` together identify the version row. Pushing a new
+version with the same `name` and a different `version` appends to history;
+re-using the same `version` is rejected.
+
+### `triggerMethods`
+
+Required. Each entry adds an invocation surface:
+
+- `api` — the workflow can be called via REST or the CLI's `workflow execution run`
+- `cron` — scheduled. Add a sibling `cron: { schedule: "0 9 * * *", timezone: "UTC" }`
+- `email` — inbound email. Add a sibling `email: { subject?: ..., aliases?: [...] }`
+
+If `api` is missing, `eigenpal workflow execution run` and `workflow run` reject with a
+403 / "Workflow does not have API trigger enabled."
+
+### `inputs`
+
+```yaml
+inputs:
+  - name: document # required — becomes a key on triggerInput
+    type: file # one of: string | number | boolean | object | file
+    file: true # required when type=file (legacy duplicate of `type: file`)
+    description: PDF or image to extract from
+    required: true # default true; pass false for optional inputs
+
+  - name: language
+    type: string
+    description: Language hint
+    default: auto
+```
+
+Per input:
+
+- `name` — `[a-z0-9][a-z0-9-_]*`
+- `type` — `string` | `number` | `boolean` | `object` | `array` | `file`
+- `file: true` for binary inputs (PDF, DOCX, image). The CLI uploads,
+  then references via `{{ input.<name> }}` which resolves to a
+  `FilePathDescriptor` the worker reads.
+- `default` — used when the input is omitted at runtime
+- `description` — surfaced in the dashboard + agent tools
+
+#### File input shape — single vs array
+
+The materialized shape on `triggerInput` is driven by the YAML, not by
+how many files the dataset uploaded. Get this wrong and the worker
+sees the opposite shape:
+
+| YAML                                       | `triggerInput.<name>` | Template                                |
+| ------------------------------------------ | --------------------- | --------------------------------------- |
+| `type: file`                               | `{ fileId }`          | `{{ input.<name> }}`                    |
+| `type: array`, `items: { type: file }`     | `[{ fileId }, ...]`   | `{{ input.<name>[0] }}` (or `forEach:`) |
+
+If you see `Invalid input ... expected object, received array` from a
+step that takes a single file, the workflow input is `type: file` but
+the dataset folder probably has multiple files in it (or the workflow
+was on a stale version that materialized arrays unconditionally).
+Trim the folder to one file, or switch the input to the array form.
+
+### `steps`
+
+```yaml
+steps:
+  - name: parse # required, unique within the workflow
+    type: ai.document-parser # see `reference/step-types.md`; introspect with `step-type get`
+    if: '{{ input.skipParse != true }}' # optional — Liquid expression; falsy skips the step
+    forEach: '{{ input.documents }}' # optional — runs the step over each item; output is array
+    with: # step-specific config — schema depends on `type`
+      file: '{{ input.document }}'
+      parser: auto
+
+  - name: extract
+    type: ai.extract
+    with:
+      input: '{{ steps.parse.output.text }}'
+      schema:
+        type: object
+        properties:
+          invoiceNumber: { type: string }
+          totalAmount: { type: number }
+        required: [invoiceNumber]
+```
+
+Step references resolve via Liquid template expressions:
+
+- `{{ input.<name> }}` — workflow input
+- `{{ steps.<step-name>.output.<field> }}` — prior step output
+- `{{ item.<field> }}` — current item inside `forEach`
+
+`steps[].name` is the only handle into the step from later steps. Use
+short, descriptive names (`parse`, `extract`, `score`).
+
+### `output`
+
+```yaml
+output:
+  invoiceNumber: '{{ steps.extract.output.invoiceNumber }}'
+  totalAmount: '{{ steps.extract.output.totalAmount }}'
+  confidence: '{{ steps.score.output.confidence | default: 0 }}'
+```
+
+Whatever shape you write here is the workflow's return value. Reference
+any step's output. Static keys are fine — only the values are templated.
+
+## Step types — pick the right one
+
+See `reference/step-types.md` for the full catalog. Categories:
+
+- `action.*` — side-effectful operations (HTTP, email, connectors)
+- `ai.*` — model-backed processing (parse, extract, classify, judge)
+- `transform.*` — deterministic data transforms (script, template, merge)
+- `control.*` — flow control (if, for-each, parallel-map)
+
+When in doubt, use `eigenpal workflow step-type get <type>` — it returns
+the exact JSON Schema for the step's `config` + `output` so you know
+which fields are required and what values they accept.
+
+## Liquid vs `transform.script`
+
+Use Liquid `{{ ... }}` for one-liners:
+
+| Use case      | Use                              |
+| ------------- | -------------------------------- |
+| Field access  | `{{ steps.x.output.field }}`     |
+| Default value | `{{ value \| default: 0 }}`      |
+| Simple math   | `{{ price \| times: quantity }}` |
+
+Anything more complex (array reduce/filter, multi-step calc, date
+arithmetic, regex) goes in `transform.script`:
+
+```yaml
+- name: total
+  type: transform.script
+  with:
+    inputs: # explicit data deps — visible to the validator
+      lineItems: '{{ steps.extract.output.lineItems }}'
+      taxRate: '{{ input.taxRate }}'
+    code: |
+      const subtotal = lineItems.reduce((s, i) => s + i.price * i.qty, 0);
+      const tax = subtotal * taxRate;
+      return { subtotal, tax, total: subtotal + tax };
+    outputSchema: # optional but recommended — runtime-validated
+      type: object
+      properties:
+        subtotal: { type: number }
+        tax: { type: number }
+        total: { type: number }
+```
+
+The script runs in a WASM sandbox: 5s wall clock, 10 MB heap, no network,
+no filesystem. Trips show up as `script_timeout` / `script_memory_limit`
+on the step execution.
+
+## Common patterns
+
+### Conditional branches
+
+```yaml
+- name: classify
+  type: ai.extract
+  with:
+    input: '{{ input.text }}'
+    schema:
+      type: object
+      properties:
+        kind: { type: string, enum: [invoice, contract, other] }
+
+- name: extract-invoice
+  type: ai.extract
+  if: '{{ steps.classify.output.kind == "invoice" }}'
+  with: { ... }
+
+- name: extract-contract
+  type: ai.extract
+  if: '{{ steps.classify.output.kind == "contract" }}'
+  with: { ... }
+```
+
+### Map over an array input
+
+```yaml
+- name: extract-each
+  type: ai.extract
+  forEach: '{{ input.documents }}'
+  with:
+    input: '{{ item.text }}'
+    schema: { ... }
+# steps.extract-each.output is an array of {invoiceNumber, totalAmount, ...}
+```
+
+### Parallel fan-out
+
+```yaml
+- name: extract-fields
+  type: control.parallel-map
+  forEach: '{{ input.fieldNames }}'
+  with:
+    steps:
+      - name: extract-one
+        type: ai.extract
+        with:
+          input: '{{ input.document }}'
+          schema: { type: object, properties: { value: { type: string } } }
+```
+
+## Validate before pushing
+
+```bash
+eigenpal workflow validate ./workflow.yaml
+```
+
+Reports field-level issues:
+
+```
+✗ workflow (./workflow.yaml) — 2 issues
+  steps.2.config.passThreshold  Required
+  steps.2.type                  Invalid step type: 'eval.llm-judg'
+```
+
+Push:
+
+```bash
+# Create a new workflow (version comes from the YAML's top-level `version:` field)
+eigenpal workflow push --file workflow.yaml
+
+# Update an existing one — three ways to set the new version:
+eigenpal workflow push --file workflow.yaml --workflow-id wf_…                       # bump in YAML's `version:`
+eigenpal workflow push --file workflow.yaml --workflow-id wf_… --set-version 2.0.0   # explicit semver
+eigenpal workflow push --file workflow.yaml --workflow-id wf_… --bump patch          # auto-bump (patch | minor | major)
+```
+
+`--bump` requires `--workflow-id` (it bumps from the current server
+version). `--set-version` works with or without `--workflow-id`. The
+YAML's top-level `version:` field is the fallback when neither flag is
+passed — server rejects pushes whose version doesn't strictly increase.
+
+## Discover step + evaluator types
+
+Don't memorize fields — introspect:
+
+```bash
+eigenpal workflow step-type      list                 # full step catalog
+eigenpal workflow step-type      get <type>           # config + output schema for one step type
+eigenpal workflow evaluator-type list                 # full evaluator catalog
+eigenpal workflow evaluator-type get <type>           # config schema for one evaluator type
+```
+
+Both catalogs are generated from the canonical Zod schemas in
+`@eigenpal/types`, so they're always in sync with what the deployment
+supports.
+
+<!-- GENERATED:WORKFLOW_REFERENCE START -->
+## Top-level fields — full reference
+
+_Generated from `WorkflowDefinitionSchema` in `@eigenpal/types/src/workflow/workflow.ts`. Do not hand-edit between the GENERATED fences — run `bun run --cwd packages/cli generate:skill`._
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes |  |  |
+| `kind` | `"workflow"` \| `"block"` | no | `"workflow"` |  |
+| `version` | string | no | `"1.0.0"` |  |
+| `description` | string | no |  |  |
+| `enabled` | boolean | no | `true` |  |
+| `triggerMethods` | array<object> | no | `[{"type":"manual"}]` |  |
+| `inputs` | array<object> | no |  |  |
+| `steps` | array<unknown> | yes |  |  |
+| `output` | record<string, string> | no |  |  |
+| `settings` | object | no |  |  |
+
+
+## Per-input fields
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | string | yes |  |  |
+| `type` | string | yes |  |  |
+| `description` | string | no |  |  |
+| `required` | boolean | no | `true` |  |
+| `default` | unknown | no |  |  |
+| `items` | object | no |  |  |
+<!-- GENERATED:WORKFLOW_REFERENCE END -->

package/dist/templates/blank/README.md

@@ -0,0 +1,22 @@
+# __NAME__
+
+Generated by `eigenpal init workflow`. Edit `workflow.yaml` to define your pipeline,
+then run:
+
+```bash
+# Validate locally (no server contact)
+eigenpal workflow validate
+
+# Run an example end-to-end against the configured base URL
+eigenpal workflow execution run __NAME__ sample
+```
+
+Add more examples under `dataset/examples/<name>/`. Each example needs an
+`input/arguments.json`; `expected/output.json` and `meta.json` are optional.
+File arguments live in `input/<arg-name>/<filename>`.
+
+When you're ready to push this workflow to the server:
+
+```bash
+eigenpal workflow push --file workflow.yaml
+```

package/dist/templates/blank/dataset/examples/sample/expected/output.json

@@ -0,0 +1,4 @@
+{
+  "length": 16,
+  "original": "Hello, eigenpal."
+}

package/dist/templates/blank/dataset/examples/sample/input/arguments.json

@@ -0,0 +1,3 @@
+{
+  "text": "Hello, eigenpal."
+}

package/dist/templates/blank/evaluators.yaml

@@ -0,0 +1,9 @@
+# Evaluators run after every workflow execution that's part of an eval batch.
+# Comment them in once you have an `expected/output.json` to compare against.
+#
+# evaluators:
+#   - name: exact-match
+#     type: exact-diff
+#     config:
+#       passThreshold: 1.0
+evaluators: []

package/dist/templates/blank/workflow.yaml

@@ -0,0 +1,39 @@
+name: __NAME__
+version: 1.0.0
+description: Replace this with what your workflow does.
+
+# `triggerMethods` controls how this workflow can be invoked:
+#   - api: workflow can be called via the REST API and CLI
+#   - cron: workflow can be scheduled (set `cron` field below)
+triggerMethods:
+  - api
+
+# `inputs` declares the schema of arguments the workflow accepts. Each entry
+# becomes a top-level key on the call's `triggerInput` object. Use `file: true`
+# to mark an input as a file-arg (its value is a `[{ fileId }]` array at
+# runtime; in the dataset folder layout it lives under `input/<name>/`).
+inputs:
+  - name: text
+    type: string
+    description: Free-form text to process
+
+# A pipeline of one or more steps. The first step receives `input.*`; later
+# steps reference earlier outputs via `{{ steps.<name>.output.<field> }}`.
+steps:
+  - name: passthrough
+    type: transform.script
+    with:
+      inputs:
+        text: '{{ input.text }}'
+      code: |
+        return { length: text.length, original: text };
+      outputSchema:
+        type: object
+        properties:
+          length: { type: number }
+          original: { type: string }
+
+# `output` shapes the final return value. References any step's output.
+output:
+  length: '{{ steps.passthrough.output.length }}'
+  original: '{{ steps.passthrough.output.original }}'

package/dist/templates/pdf-extraction/README.md

@@ -0,0 +1,20 @@
+# __NAME__
+
+A PDF/document extraction workflow scaffolded by `eigenpal init workflow`. The
+pipeline parses an uploaded document with the auto-detected parser
+(plaintext / office / OCR / LLM-vision), then runs `ai.extract` against a
+fixed JSON schema.
+
+## Wire it up
+
+1. Drop a sample PDF at `dataset/examples/sample-invoice/input/document/<filename>`.
+2. Adjust the `extract.with.schema` to the fields your documents actually carry.
+3. Run an example: `eigenpal workflow execution run __NAME__ sample-invoice`.
+4. When the output looks right, push: `eigenpal workflow push --file workflow.yaml`.
+
+## Extending
+
+- Multiple file inputs: declare more inputs in `workflow.yaml` and add
+  `dataset/examples/<name>/input/<arg>/` folders with their files.
+- Per-example overrides: drop a `meta.json` next to the example with
+  `{ "overrides": { "steps": { "<step>": { ... } } } }` to skip steps in eval.

package/dist/templates/pdf-extraction/dataset/examples/sample-invoice/README.md

@@ -0,0 +1,5 @@
+# sample-invoice
+
+Drop your PDF/image at `input/document/<filename>` to give this example
+something to extract from. The argument folder name (`document`) matches
+the input declared in `workflow.yaml`.

package/dist/templates/pdf-extraction/dataset/examples/sample-invoice/expected/output.json

@@ -0,0 +1,6 @@
+{
+  "invoiceNumber": "INV-001",
+  "totalAmount": 1500,
+  "vendorName": "Acme Corp",
+  "dueDate": "2026-05-15"
+}

package/dist/templates/pdf-extraction/dataset/examples/sample-invoice/input/arguments.json

@@ -0,0 +1 @@
+{}

package/dist/templates/pdf-extraction/evaluators.yaml

@@ -0,0 +1,5 @@
+evaluators:
+  - name: exact-match
+    type: exact-diff
+    config:
+      passThreshold: 1.0

package/dist/templates/pdf-extraction/workflow.yaml

@@ -0,0 +1,38 @@
+name: __NAME__
+version: 1.0.0
+description: Parse a PDF and extract structured fields with an LLM.
+
+triggerMethods:
+  - api
+
+inputs:
+  - name: document
+    type: file
+    file: true
+    description: PDF or image to extract from
+
+steps:
+  - name: parse
+    type: ai.document-parser
+    with:
+      file: '{{ input.document }}'
+      parser: auto
+
+  - name: extract
+    type: ai.extract
+    with:
+      input: '{{ steps.parse.output.text }}'
+      schema:
+        type: object
+        properties:
+          invoiceNumber: { type: string }
+          totalAmount: { type: number }
+          vendorName: { type: string }
+          dueDate: { type: string, format: date }
+        required: [invoiceNumber, totalAmount, vendorName]
+
+output:
+  invoiceNumber: '{{ steps.extract.output.invoiceNumber }}'
+  totalAmount: '{{ steps.extract.output.totalAmount }}'
+  vendorName: '{{ steps.extract.output.vendorName }}'
+  dueDate: '{{ steps.extract.output.dueDate | default: null }}'

package/dist/templates/text-classification/README.md

@@ -0,0 +1,8 @@
+# __NAME__
+
+A text classification workflow scaffolded by `eigenpal init workflow`. Two examples
+are pre-seeded so you can immediately run `eigenpal workflow execution run __NAME__` and see
+end-to-end behavior.
+
+The eval config asserts on the `label` path only — confidence/rationale are
+free to vary between runs without failing the eval.

package/dist/templates/text-classification/dataset/examples/negative/expected/output.json

@@ -0,0 +1,3 @@
+{
+  "label": "negative"
+}

package/dist/templates/text-classification/dataset/examples/negative/input/arguments.json

@@ -0,0 +1,3 @@
+{
+  "text": "Worst experience ever, do not buy."
+}

package/dist/templates/text-classification/dataset/examples/positive/expected/output.json

@@ -0,0 +1,3 @@
+{
+  "label": "positive"
+}

package/dist/templates/text-classification/dataset/examples/positive/input/arguments.json

@@ -0,0 +1,3 @@
+{
+  "text": "Best product I have used in years!"
+}

package/dist/templates/text-classification/evaluators.yaml

@@ -0,0 +1,6 @@
+evaluators:
+  - name: label-match
+    type: exact-diff
+    config:
+      passThreshold: 1.0
+      paths: [label]

package/dist/templates/text-classification/workflow.yaml

@@ -0,0 +1,35 @@
+name: __NAME__
+version: 1.0.0
+description: Classify free-form text into one of a fixed set of labels.
+
+triggerMethods:
+  - api
+
+inputs:
+  - name: text
+    type: string
+    description: Text to classify
+
+steps:
+  - name: classify
+    type: ai.extract
+    with:
+      input: '{{ input.text }}'
+      schema:
+        type: object
+        properties:
+          label:
+            type: string
+            enum: [positive, neutral, negative]
+          confidence:
+            type: number
+            minimum: 0
+            maximum: 1
+          rationale:
+            type: string
+        required: [label, confidence]
+
+output:
+  label: '{{ steps.classify.output.label }}'
+  confidence: '{{ steps.classify.output.confidence }}'
+  rationale: '{{ steps.classify.output.rationale | default: null }}'

package/package.json

@@ -1,12 +1,35 @@
 {
   "name": "@eigenpal/cli",
-  "version": "0.0.1",
-  "description": "Eigenpal CLI — placeholder release. The real CLI will replace this shortly.",
+  "version": "0.4.2",
+  "description": "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
+  "keywords": [
+    "eigenpal",
+    "cli",
+    "ai",
+    "agent",
+    "workflow",
+    "llm",
+    "evals",
+    "experiments",
+    "document",
+    "extraction",
+    "ocr"
+  ],
+  "homepage": "https://github.com/eigenpal/cli#readme",
+  "bugs": {
+    "url": "https://github.com/eigenpal/cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eigenpal/cli.git"
+  },
   "license": "Apache-2.0",
+  "author": "Eigenpal <hello@eigenpal.com> (https://eigenpal.com)",
   "type": "module",
-  "main": "./index.js",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "bin": {
-    "eigenpal": "./index.js"
+    "eigenpal": "dist/cli.js"
   },
   "engines": {
     "node": ">=20"
@@ -14,16 +37,38 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "index.js",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/eigenpal/cli"
+  "scripts": {
+    "dev": "bun src/cli.ts",
+    "build": "bun run generate:skill && bun build src/cli.ts --outdir dist --target node --format esm && rm -rf dist/templates dist/skill && cp -R src/templates dist/templates && cp -R src/skill dist/skill",
+    "generate:skill": "bun scripts/generate-skill-reference.ts",
+    "generate:skill:check": "bun scripts/generate-skill-reference.ts --check",
+    "generate:cli-docs": "bun scripts/generate-cli-docs.ts",
+    "generate:cli-docs:check": "bun scripts/generate-cli-docs.ts --check",
+    "generate:logo": "bun scripts/render-logo-ascii.ts --cells 20",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
   },
-  "homepage": "https://github.com/eigenpal/cli#readme",
-  "bugs": {
-    "url": "https://github.com/eigenpal/cli/issues"
-  }
+  "dependencies": {
+    "@clack/prompts": "^0.10.1",
+    "ajv": "^8.17.1",
+    "commander": "^13.1.0",
+    "fflate": "0.8.2",
+    "openai": "^6.27.0",
+    "picocolors": "^1.1.1",
+    "quickjs-emscripten": "^0.31.0",
+    "yaml": "^2.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eigenpal/types": "workspace:*",
+    "@eigenpal/workflow-yaml": "workspace:*",
+    "@t3-oss/env-core": "^0.13.11",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
 }

package/index.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-console.log('@eigenpal/cli placeholder — the real CLI ships in the next release.');
-console.log('See https://github.com/eigenpal/cli for source.');
-process.exit(0);