@signstack/cli 0.1.1

package/README.md

@@ -0,0 +1,458 @@
+# signstack
+
+Modern Sign CLI — command-line tool for managing SignStack document workflows. Validate, preview, push, and run document blueprints from your terminal.
+
+Built with [oclif](https://oclif.io).
+
+[![Version](https://img.shields.io/npm/v/@signstack/cli.svg)](https://npmjs.org/package/@signstack/cli)
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Installation
+
+```bash
+npm install -g @signstack/cli
+```
+
+This installs the `signstack` command globally.
+
+Or use with npx:
+
+```bash
+npx @signstack/cli <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+signstack auth login
+
+# 2. Validate your YAML resources
+signstack validate
+
+# 3. Preview a blueprint
+signstack preview my_blueprint@1.0.0
+
+# 4. Push resources to the API
+signstack push
+
+# 5. Run a workflow
+signstack run my_blueprint@1.0.0
+```
+
+## Shell Completions
+
+Set up tab completions for your shell:
+
+```bash
+signstack autocomplete
+```
+
+Follow the printed instructions. Supports bash, zsh, and fish.
+
+---
+
+## Commands
+
+| Command | Description | Auth Required |
+|---------|-------------|:---:|
+| [`generate`](#generate) | Browse public blueprints or bootstrap a new project with AI tools | No |
+| [`init`](#init) | Show how to use AI tools to generate contracts | No |
+| [`auth login`](#auth-login) | Authenticate with an API key | No |
+| [`auth logout`](#auth-logout) | Remove stored credentials | No |
+| [`auth whoami`](#auth-whoami) | Show current user and config | No |
+| [`validate`](#validate) | Validate YAML files with dependency analysis | No |
+| [`push`](#push) | Push resources to the API | Yes |
+| [`preview`](#preview) | Preview a blueprint or template as PDF | Yes |
+| [`run`](#run) | Create and start a workflow | Yes |
+| `help [COMMAND]` | Display help for a command | No |
+| `update` | Update the CLI | No |
+| `autocomplete` | Set up shell completions | No |
+
+---
+
+### `generate`
+
+Bootstrap a new SignStack project. Browses public blueprints in the SignStack Library one page at a time (5 per page) and downloads the selected listing + all its dependencies as local YAML files. Pick **+ New** to print AI-tool instructions instead (Claude Code, Cursor, ChatGPT, Gemini).
+
+```bash
+# Browse the library interactively
+signstack generate
+
+# Download into a specific parent directory
+signstack generate -o ./projects
+```
+
+No authentication required — the command uses the public library endpoints and only shows listings with `scope: public`.
+
+---
+
+### `init`
+
+Show how to use AI tools (Claude Code, Cursor, ChatGPT, Gemini) to generate SignStack contracts from natural language descriptions.
+
+```bash
+signstack init
+```
+
+Prints a guide with the exact invocation for each AI tool and an example prompt.
+
+---
+
+### `auth login`
+
+Authenticate with the SignStack API using an API key. Credentials are stored locally in a config file.
+
+```bash
+# Interactive (recommended)
+signstack auth login
+
+# Via environment variable
+SIGNSTACK_API_KEY=sk_ns_live_xxx signstack auth login
+
+# Pipe from stdin (CI/scripts)
+echo "$SIGNSTACK_API_KEY" | signstack auth login --api-key-stdin
+
+# Custom API endpoint
+signstack auth login --api-url https://api.custom.io
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--api-key` | `-k` | API key (insecure — prefer interactive or stdin). Also reads `SIGNSTACK_API_KEY` env var. |
+| `--api-key-stdin` | | Read API key from stdin |
+| `--api-url` | `-u` | API URL (default: production). Also reads `SIGNSTACK_API_URL` env var. |
+| `--force` | `-f` | Force login even if already logged in |
+| `--json` | | Output in JSON format |
+
+**API key format:** `sk_{namespace}_{live|test}_{publicKey}_{secret}`
+
+---
+
+### `auth logout`
+
+Remove stored credentials.
+
+```bash
+signstack auth logout
+signstack auth logout --force   # Skip confirmation
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--force` | `-f` | Skip confirmation prompt |
+| `--json` | | Output in JSON format |
+
+---
+
+### `auth whoami`
+
+Display the current authenticated user and configuration.
+
+```bash
+signstack auth whoami
+signstack auth whoami --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output in JSON format |
+
+---
+
+### `validate`
+
+Validate YAML resource files against SignStack JSON schemas. When given a folder, builds a dependency graph and validates in topological order (leaf nodes first).
+
+```bash
+# Validate all YAML files in current directory
+signstack validate
+
+# Validate a specific folder
+signstack validate ./my-project
+
+# Validate a single file
+signstack validate template.yaml
+
+# Validate with glob pattern
+signstack validate "schemas/**/*.yaml"
+
+# Force a specific schema type
+signstack validate my-file.yaml --schema blueprint
+
+# Skip dependency analysis (faster)
+signstack validate --no-deps
+
+# Verbose output with graph stats
+signstack validate --verbose
+```
+
+| Arg/Flag | Short | Description |
+|----------|-------|-------------|
+| `PATH` (arg) | | Folder, file, or glob pattern (default: `.`) |
+| `--schema` | `-s` | Force schema type: `schema`, `template`, `asset`, `blueprint`, `jsonata-function` (auto-detected from `kind` field if omitted) |
+| `--verbose` | `-v` | Detailed output including dependency graph stats |
+| `--no-deps` | | Skip dependency ordering and validation |
+| `--json` | | Output in JSON format |
+
+**Auto-detection:** The `kind` field in your YAML file determines which schema is used. You only need `--schema` if auto-detection fails.
+
+---
+
+### `push`
+
+Push resources to the API. Validates all files first, then creates resources in dependency order (leaf nodes first).
+
+```bash
+# Push from current directory
+signstack push
+
+# Push from a specific folder
+signstack push ./my-project
+
+# Dry run — see what would be pushed
+signstack push --dry-run
+
+# Verbose output
+signstack push --verbose
+```
+
+| Arg/Flag | Short | Description |
+|----------|-------|-------------|
+| `PATH` (arg) | | Folder containing YAML files (default: `.`) |
+| `--dry-run` | | Show what would be pushed without calling the API |
+| `--verbose` | `-v` | Detailed output |
+| `--json` | | Output in JSON format |
+
+---
+
+### `preview`
+
+Preview a blueprint or template and get signed PDF URL(s). By default, resolves resources from local YAML files first, falling back to the API for anything not found locally.
+
+```bash
+# Preview with version
+signstack preview my_blueprint@1.0.0
+
+# Preview latest local version (no version = highest version in local files)
+signstack preview my_blueprint
+
+# Preview a single template instead of a blueprint
+signstack preview --template my_template@1.0.0
+
+# Use a specific scenario
+signstack preview my_blueprint@1.0.0 --scenario onboarding_scenario
+
+# List available scenarios
+signstack preview --list-scenarios
+
+# Use files from a different folder
+signstack preview my_blueprint@1.0.0 -p ./other-project
+
+# Strict local — fail if any resource is missing locally
+signstack preview my_blueprint@1.0.0 --resolve local
+
+# Strict remote — skip local files entirely
+signstack preview my_blueprint@1.0.0 --resolve remote
+```
+
+| Arg/Flag | Short | Description |
+|----------|-------|-------------|
+| `BLUEPRINT` (arg) | | Blueprint reference as `key@version` or `key` |
+| `--template` | `-t` | Template reference (instead of blueprint) |
+| `--path` | `-p` | Folder with YAML resource files (default: `.`) |
+| `--resolve` | `-r` | Resolution strategy: `local`, `remote`, `auto` (see below) |
+| `--scenario` | `-s` | Scenario key for entity data |
+| `--list-scenarios` | `-l` | List available scenarios |
+| `--skip-signature-fields` | | Disable dummy signatures/initials/auto-dates |
+| `--json` | | Output in JSON format |
+
+---
+
+### `run`
+
+Create and start a workflow from a blueprint. Same resource resolution as `preview`.
+
+```bash
+# Run with version
+signstack run my_blueprint@1.0.0
+
+# Run latest local version
+signstack run my_blueprint
+
+# Run in review mode
+signstack run my_blueprint@1.0.0 --mode Review
+
+# With a specific scenario
+signstack run my_blueprint@1.0.0 --scenario onboarding_scenario
+
+# Strict local
+signstack run my_blueprint@1.0.0 --resolve local
+```
+
+| Arg/Flag | Short | Description |
+|----------|-------|-------------|
+| `BLUEPRINT` (arg) | | Blueprint reference as `key@version` or `key` |
+| `--path` | `-p` | Folder with YAML resource files (default: `.`) |
+| `--resolve` | `-r` | Resolution strategy: `local`, `remote`, `auto` (see below) |
+| `--scenario` | `-s` | Scenario key for entity data |
+| `--mode` | `-m` | Workflow mode: `Run` (default) or `Review` |
+| `--json` | | Output in JSON format |
+
+---
+
+## Resource Resolution (`--resolve`)
+
+The `preview` and `run` commands resolve resources (templates, assets, schemas) using a configurable strategy:
+
+| Mode | Behavior |
+|------|----------|
+| *(default)* | Hybrid — local files first, API fallback for missing resources |
+| `local` | Strict local — all resources must exist in your YAML files. Fails if anything is missing. |
+| `remote` | Strict remote — ignores local files, resolves everything from the API. |
+| `auto` | Same as default (hybrid). Explicit alias. |
+
+**Version resolution:** When you omit the version (e.g., `signstack preview my_blueprint`), the CLI finds the highest version in your local files. If no local files exist, it falls back to the API.
+
+**Default path:** Both commands look for YAML files in the current directory (`.`) by default. Use `-p` to point elsewhere.
+
+---
+
+## Resource Types
+
+SignStack YAML files use a `kind` field to declare their type:
+
+| Kind | Description |
+|------|-------------|
+| `Schema` | JSON Schema definitions for validating entity data |
+| `Template` | Document templates (HTML/Handlebars → PDF) with dependencies |
+| `Asset` | Static files — CSS stylesheets, images, HTML partials, PDF forms |
+| `Blueprint` | Workflow definitions that compose templates, schemas, and signing steps |
+| `JsonataFunction` | Reusable JSONata transformation functions |
+
+### Reference Format
+
+Resources reference each other using `key@version`:
+
+```yaml
+# In a blueprint
+templates:
+  - key: offer_letter
+    version: 1.0.0
+
+# In a template
+dependencies:
+  - kind: Asset
+    key: company_logo
+    version: 1.0.0
+```
+
+---
+
+## Project Structure
+
+A typical project folder looks like this:
+
+```
+my-project/
+├── blueprint.yaml          # Blueprint definition
+├── schema.yaml             # Data schema(s)
+├── template.yaml           # Template definition(s)
+├── asset.yaml              # Asset declaration(s)
+├── html/
+│   └── offer_letter.hbs    # Handlebars template file
+├── styles/
+│   └── main.css            # CSS stylesheet
+├── images/
+│   └── logo.png            # Image assets
+├── partials/
+│   └── footer.hbs          # Handlebars partials
+└── scenarios/
+    └── test_data.json       # Test entity data for preview/run
+```
+
+Multi-document YAML files are supported — you can put multiple resources in a single `.yaml` file separated by `---`.
+
+---
+
+## Global Flags
+
+These flags are available on every command:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output in JSON format (for scripting and CI) |
+| `--help` | Show help for any command |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SIGNSTACK_API_KEY` | API key for `auth login` (avoids interactive prompt) |
+| `SIGNSTACK_API_URL` | Override the API URL |
+
+---
+
+## CI/CD Usage
+
+All commands support `--json` for machine-readable output. Combine with `--api-key-stdin` for secure authentication:
+
+```bash
+# Login
+echo "$SIGNSTACK_API_KEY" | signstack auth login --api-key-stdin
+
+# Validate
+signstack validate ./resources --json
+
+# Push (with dry-run check first)
+signstack push ./resources --dry-run --json
+signstack push ./resources --json
+```
+
+---
+
+## Development
+
+### Building the CLI
+
+```bash
+# From the monorepo root
+npm run cli:build
+```
+
+### Running Validation on Examples
+
+```bash
+npm run signstack:validate -- ./apps/signstack-cli/schemas/examples
+```
+
+### Running Locally (Without Installing)
+
+```bash
+# From the monorepo root, after building
+node apps/signstack-cli/bin/run.js <command>
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `Not logged in` | Run `signstack auth login` |
+| `Configuration is corrupted` | Run `signstack auth logout` then `signstack auth login` |
+| `Session expired` | Tokens auto-refresh. If persists, re-login. |
+| `Invalid API key format` | Key must match `sk_{ns}_{live\|test}_{public}_{secret}` |
+| `Permission denied (403)` | Your API key may lack required scopes |
+| `Rate limit exceeded (429)` | Wait and retry |
+| Validation fails on dependencies | Check `key@version` references match across files |
+| Circular dependency detected | Remove circular references between resources |
+
+## License
+
+MIT

package/bin/run.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// @common/base and @signstack/base are shipped inside this package's
+// node_modules (see "bundledDependencies"), so they resolve via normal
+// Node module resolution — no path-alias registration needed.
+
+async function main() {
+  const { execute } = await import('@oclif/core');
+  await execute({ dir: import.meta.url });
+}
+
+await main();

package/dist/apps/signstack-cli/schemas/asset.schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://signstack.ai/schemas/asset/v1beta2",
+  "title": "SignStack Asset",
+  "description": "An Asset wraps a file (PDF, HTML, image, CSS) for use in templates. HTML Assets can reference other Assets for partials, styles, and images. All references are versioned (key@version). Each Asset version is immutable.",
+  "type": "object",
+  "required": ["apiVersion", "kind", "metadata", "spec"],
+  "additionalProperties": false,
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "const": "signstack/v1beta2",
+      "description": "API version for the asset schema"
+    },
+    "kind": {
+      "type": "string",
+      "const": "Asset",
+      "description": "Resource type identifier"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["key", "version", "name"],
+      "additionalProperties": false,
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+          "description": "Unique identifier for the asset (snake_case)",
+          "examples": ["company_logo", "offer_letter", "corporate_theme"]
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$",
+          "description": "Semantic version (e.g., 1.0.0)"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Human-readable name for the asset"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1000,
+          "description": "Description of the asset"
+        },
+        "labels": {
+          "type": "object",
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$"
+          },
+          "additionalProperties": { "type": "string" },
+          "description": "Key-value labels for categorization"
+        }
+      }
+    },
+    "spec": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "description": "Asset specification. HTML assets can reference other versioned assets for dependencies. Use 'file' for file-based assets or 'content' for inline HTML/CSS.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["pdf", "html", "image", "css"],
+          "description": "Asset type"
+        },
+        "file": {
+          "type": "string",
+          "description": "Relative path to the asset file",
+          "examples": [
+            "./offer_letter.html",
+            "./document.pdf",
+            "./logo.png",
+            "./theme.css"
+          ]
+        },
+        "fileId": {
+          "type": "string",
+          "pattern": "^f_[0-9a-z]{26}$",
+          "description": "Uploaded file identifier (used by API for PDF/image assets)"
+        },
+        "content": {
+          "type": "string",
+          "description": "Inline content for html or css assets. Use this instead of 'file' when providing content directly."
+        },
+        "partials": {
+          "type": "object",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$"
+              },
+              {
+                "type": "object",
+                "required": ["asset"],
+                "additionalProperties": false,
+                "properties": {
+                  "asset": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$",
+                    "description": "Asset reference (key@version)"
+                  },
+                  "roleMap": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    },
+                    "description": "Maps roles defined in the partial to roles in the parent context"
+                  }
+                }
+              }
+            ]
+          },
+          "description": "Handlebars partials. Keys are partial names used in {{> name}}. Values can be a simple asset reference (key@version) or an object with asset and roleMap."
+        },
+        "styles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$"
+          },
+          "description": "CSS asset references (key@version). Order matters for cascading."
+        },
+        "images": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$"
+          },
+          "description": "Image asset references. Keys are names used in HTML, values are asset references (key@version)."
+        },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Data configuration for HTML assets",
+          "properties": {
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$",
+              "description": "Schema defining the data context this HTML expects (key@version). Required for HTML assets. Partials can use the same schema as parent for implicit inheritance."
+            }
+          },
+          "required": ["schema"]
+        },
+        "pdfSettings": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "PDF rendering settings for HTML assets",
+          "properties": {
+            "paperSize": {
+              "type": "string",
+              "enum": ["Letter", "Legal", "A4", "A3"],
+              "default": "Letter",
+              "description": "Paper size for PDF output"
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "pdf" } } },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["file"],
+                "properties": {
+                  "file": { "pattern": "\\.(pdf)$" }
+                }
+              },
+              { "required": ["fileId"] }
+            ]
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "html" } } },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["file"],
+                "properties": {
+                  "file": { "pattern": "\\.(html|hbs|handlebars)$" }
+                }
+              },
+              { "required": ["content"] }
+            ]
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "image" } } },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["file"],
+                "properties": {
+                  "file": { "pattern": "\\.(png|jpg|jpeg|gif|svg|webp)$" }
+                }
+              },
+              { "required": ["fileId"] }
+            ]
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "css" } } },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["file"],
+                "properties": { "file": { "pattern": "\\.(css)$" } }
+              },
+              { "required": ["content"] }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}