blokctl 0.6.16 → 0.6.18

package/dist/commands/create/project.js

@@ -17,7 +17,7 @@ const exec = util.promisify(child_process.exec);
 const HOME_DIR = `${os.homedir()}/.blok`;
 const GITHUB_REPO_LOCAL = `${HOME_DIR}/blok`;
 const GITHUB_REPO_REMOTE = "https://github.com/well-prado/blok.git";
-const GITHUB_REPO_RELEASE_TAG = "v0.6.16";
+const GITHUB_REPO_RELEASE_TAG = "v0.6.18";
 fsExtra.ensureDirSync(HOME_DIR);
 const options = {
     baseDir: HOME_DIR,
@@ -487,7 +487,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             "@blokjs/trigger-websocket": "triggers/websocket",
             "@blokjs/trigger-worker": "triggers/worker",
         };
-        const BLOKJS_DEP_RANGE = "^0.6.16";
+        const BLOKJS_DEP_RANGE = "^0.6.18";
         for (const depGroup of ["dependencies", "devDependencies", "peerDependencies"]) {
             const deps = packageJsonContent[depGroup];
             if (!deps)

package/dist/commands/create/utils/Examples.d.ts

@@ -35,7 +35,7 @@ declare const php_dockerfile = "FROM php:8.2-cli-alpine AS builder\nWORKDIR /app
 declare const ruby_node_file = "require_relative '../../lib/blok'\n\nmodule Blok\n  module Nodes\n    class {{NODE_NAME_PASCAL}}Node < Blok::NodeHandler\n      def execute(ctx, config)\n        # Access request body\n        name = ctx.request.body.is_a?(Hash) ? ctx.request.body['name'] : nil\n        name ||= 'World'\n\n        # Access configuration\n        prefix = config['prefix'] || 'Hello'\n\n        message = \"#{prefix}, #{name}!\"\n\n        # Store in context for downstream nodes\n        ctx.vars['greeting'] = message\n\n        # Return response\n        {\n          'message' => message,\n          'timestamp' => Time.now.utc.iso8601,\n          'language' => 'Ruby'\n        }\n      end\n    end\n  end\nend\n";
 declare const ruby_gemfile = "source 'https://rubygems.org'\n\nruby '>= 3.1'\n\ngem 'sinatra', '~> 4.0'\ngem 'puma', '~> 6.4'\ngem 'rackup', '~> 2.1'\n";
 declare const ruby_dockerfile = "FROM ruby:3.2-alpine AS builder\nRUN apk add --no-cache build-base\nWORKDIR /app\nCOPY Gemfile Gemfile.lock ./\nRUN bundle install --without development test\n\nFROM ruby:3.2-alpine\nRUN apk --no-cache add ca-certificates wget\nWORKDIR /app\nCOPY --from=builder /usr/local/bundle /usr/local/bundle\nCOPY . .\n\nEXPOSE 8080\nENV PORT=8080\nENV RACK_ENV=production\nHEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \\\n  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1\n\nCMD [\"bundle\", \"exec\", \"puma\", \"-b\", \"tcp://0.0.0.0:8080\"]\n";
-declare const agents_md = "# Blok Project\n\nBlok is a TypeScript-first workflow orchestration framework. It executes declarative workflows (JSON or TypeScript DSL) composed of steps (nodes) that run across 8 language runtimes: NodeJS, Python3, Go, Rust, Java, C#, PHP, and Ruby.\n\n## Project Structure\n\n```\n\u251C\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 nodes/             # TypeScript node implementations\n\u251C\u2500\u2500 runtimes/              # Non-NodeJS runtime nodes (Go, Python3, etc.)\n\u2502   \u2514\u2500\u2500 {lang}/nodes/      # Language-specific node implementations\n\u251C\u2500\u2500 workflows/\n\u2502   \u251C\u2500\u2500 json/              # Workflow definitions (JSON)\n\u2502   \u251C\u2500\u2500 yaml/              # Workflow definitions (YAML)\n\u2502   \u2514\u2500\u2500 toml/              # Workflow definitions (TOML)\n\u251C\u2500\u2500 .blok/\n\u2502   \u251C\u2500\u2500 config.json        # Runtime configuration (ports, start commands)\n\u2502   \u2514\u2500\u2500 runtimes/          # Auto-generated runtime scaffolds\n\u251C\u2500\u2500 .env.local             # Environment variables (ports, paths)\n\u2514\u2500\u2500 supervisord.conf       # Process management config\n```\n\n## Commands\n\n```bash\nnpm run dev                # Start dev server (or blokctl dev for multi-runtime)\nnpm run build              # Build project\nnpm test                   # Run tests\nblokctl create node <name> # Scaffold a new node\nblokctl create workflow <n># Scaffold a new workflow\nblokctl trace              # Open Blok Studio (trace visualization)\nblokctl studio             # Alias for blokctl trace\n```\n\n## Context \u2014 Critical Data Flow\n\nThe Context type is the central execution state passed through every step.\n\n```typescript\ntype Context = {\n  id: string;                      // Unique request ID\n  request: RequestContext;          // Incoming request (body, headers, params, query)\n  response: ResponseContext;       // Current step output \u2014 OVERWRITTEN every step\n  vars?: VarsContext;              // Persistent variables \u2014 PERSISTS across workflow\n  config: ConfigContext;           // Node config (inputs resolved by Mapper)\n  env?: EnvContext;                // process.env access\n  logger: LoggerContext;\n  error: ErrorContext;\n};\n```\n\n### The Two Critical Rules\n\n**Rule 1: \\`ctx.prev\\` carries the immediately previous step's output.**\nEach step's output replaces \\`ctx.prev\\`. Use it for adjacent-step access only.\n\n**Rule 2: \\`ctx.state[id]\\` PERSISTS across the entire workflow.**\nEvery step's output is auto-stored at \\`ctx.state[<step-id>]\\` (the v2 default-store rule). Downstream steps reference it via \\`$.state.<id>\\` (TS DSL) or \\`\"$.state.<id>\"\\` / \\`\"js/ctx.state.<id>\"\\` (JSON). Opt out per step with \\`ephemeral: true\\`.\n\n### Data Flow Example\n\n```\nStep 1: id \"fetch-user\"\n  \u2192 ctx.state[\"fetch-user\"] = { id: \"123\", name: \"Alice\" }\n  \u2192 ctx.prev = { id: \"123\", name: \"Alice\" }\n\nStep 2: id \"transform\"\n  \u2192 ctx.state[\"transform\"] = { result: \"done\" }\n  \u2192 ctx.prev = { result: \"done\" }              \u2190 Step 1 output GONE from prev\n  \u2192 ctx.state[\"fetch-user\"] still available\n\nStep 3: id \"output\"\n  \u2192 Can read ctx.state[\"fetch-user\"].name      \u2190 still \"Alice\"\n```\n\n### Blueprint Mapper \u2014 Expression Resolution\n\nNode inputs support dynamic expressions resolved BEFORE node execution:\n\n```json\n{\n  \"inputs\": {\n    \"userId\": \"js/ctx.request.body.userId\",\n    \"chain\": \"js/ctx.vars['previous-step'].chain\",\n    \"previous\": \"js/ctx.response.data.result\"\n  }\n}\n```\n\nAvailable in js/ expressions: \\`ctx\\` (full context), \\`data\\` (ctx.prev.data), \\`func\\` (ctx.func), \\`vars\\` (alias for ctx.state).\n\n---\n\n## Creating Nodes with defineNode\n\nUse \\`defineNode()\\` for all new nodes. Never use the legacy class-based pattern.\n\n```typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"fetch-user\",\n  description: \"Fetches user by ID\",\n\n  input: z.object({\n    userId: z.string().uuid(),\n  }),\n\n  output: z.object({\n    user: z.object({\n      id: z.string(),\n      name: z.string(),\n      email: z.string().email(),\n    }),\n  }),\n\n  async execute(ctx, input) {\n    const user = await fetchUser(input.userId);\n    return { user };\n  },\n});\n```\n\n### Key Behaviors\n\n- Zod input/output validation runs automatically\n- ZodError is mapped to GlobalError with HTTP 400\n- \\`flow: true\\` nodes return NodeBase[] for conditional execution\n- \\`contentType\\` sets response Content-Type (e.g., \"text/html\")\n- Always \\`export default defineNode(...)\\`\n\n---\n\n## Workflow Structure (JSON)\n\n```json\n{\n  \"name\": \"My Workflow\",\n  \"version\": \"1.0.0\",\n  \"trigger\": {\n    \"http\": { \"method\": \"POST\", \"path\": \"/api/process\", \"accept\": \"application/json\" }\n  },\n  \"steps\": [\n    { \"id\": \"fetch\",   \"use\": \"@blokjs/api-call\", \"inputs\": { \"url\": \"https://api.example.com\", \"method\": \"GET\" } },\n    { \"id\": \"process\", \"use\": \"my-node\",         \"inputs\": { \"data\": \"$.state.fetch\" } },\n    { \"id\": \"go-step\", \"use\": \"chain-test\", \"type\": \"runtime.go\", \"inputs\": { \"processed\": \"$.state.process\" } }\n  ]\n}\n```\n\n### Step Types\n\n| Type | Description |\n|------|-------------|\n| \\`module\\` | TypeScript node from registered modules |\n| \\`local\\` | TypeScript node from filesystem (NODES_PATH) |\n| \\`runtime.python3\\` | Python3 SDK container (port 9007) |\n| \\`runtime.go\\` | Go SDK container (port 9001) |\n| \\`runtime.rust\\` | Rust SDK container (port 9002) |\n| \\`runtime.java\\` | Java SDK container (port 9003) |\n| \\`runtime.csharp\\` | C# SDK container (port 9004) |\n| \\`runtime.php\\` | PHP SDK container (port 9005) |\n| \\`runtime.ruby\\` | Ruby SDK container (port 9006) |\n\n### Conditional Workflow (if-else)\n\n```json\n{\n  \"nodes\": {\n    \"filter\": {\n      \"conditions\": [\n        {\n          \"type\": \"if\",\n          \"condition\": \"ctx.request.query.active === \\\\\"true\\\\\"\",\n          \"steps\": [{ \"name\": \"active-path\", \"node\": \"handle-active\", \"type\": \"module\" }]\n        },\n        {\n          \"type\": \"else\",\n          \"steps\": [{ \"name\": \"default-path\", \"node\": \"handle-default\", \"type\": \"module\" }]\n        }\n      ]\n    }\n  }\n}\n```\n\n---\n\n## Trigger Types\n\n| Trigger | Example Config |\n|---------|---------------|\n| \\`http\\` | \\`{ \"method\": \"GET\", \"path\": \"/\", \"accept\": \"application/json\" }\\` |\n| \\`grpc\\` | \\`{ \"service\": \"UserService\", \"method\": \"GetUser\" }\\` |\n| \\`cron\\` | \\`{ \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\" }\\` |\n| \\`queue\\` | \\`{ \"provider\": \"kafka\", \"topic\": \"events\" }\\` |\n| \\`pubsub\\` | \\`{ \"provider\": \"gcp\", \"topic\": \"updates\" }\\` |\n| \\`webhook\\` | \\`{ \"source\": \"github\", \"events\": [\"push\"] }\\` |\n| \\`websocket\\` | \\`{ \"events\": [\"message\"], \"path\": \"/ws\" }\\` |\n| \\`sse\\` | \\`{ \"events\": [\"update\"], \"path\": \"/stream\" }\\` |\n| \\`worker\\` | \\`{ \"queue\": \"jobs\", \"concurrency\": 5, \"retries\": 3 }\\` |\n\n### Worker Trigger\n\nThe worker trigger processes background jobs from a queue with retry logic and concurrency control.\n\n\\`\\`\\`typescript\nWorkflow({ name: \"Process Job\", version: \"1.0.0\" })\n  .addTrigger(\"worker\", { queue: \"background-jobs\" })\n  .addStep({\n    name: \"process\",\n    node: \"my-processor\",\n    type: \"module\",\n    inputs: { payload: \"js/ctx.request.body\", jobId: \"js/ctx.request.params.jobId\" },\n  });\n\\`\\`\\`\n\nJob context: \\`ctx.request.body\\` = payload, \\`ctx.request.params.queue\\` = queue name, \\`ctx.request.params.jobId\\` = job ID, \\`ctx.request.params.attempt\\` = attempt count, \\`ctx.vars._worker_job\\` = full metadata.\n\nAdapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev only).\n\n### NATS JetStream\n\nRecommended queue/worker backend. Environment variables:\n\\`\\`\\`\nNATS_SERVERS=localhost:4222\nNATS_STREAM_NAME=blok-queue     # or blok-worker for worker trigger\nNATS_TOKEN=                      # optional auth\n\\`\\`\\`\n\nQueue providers: \\`kafka\\`, \\`rabbitmq\\`, \\`sqs\\`, \\`redis\\`, \\`beanstalk\\`, \\`nats\\`\n\n### Standalone Workers (Go, Rust, Python)\n\nGo, Rust, and Python SDKs include standalone NATS workers that connect directly to NATS without the TypeScript runner:\n\n\\`\\`\\`\nWORKER_CONCURRENCY=1             # Max concurrent jobs\nWORKER_MAX_RETRIES=3             # Max delivery attempts\nWORKER_QUEUES=queue1,queue2      # Queues to consume\n\\`\\`\\`\n\n---\n\n## Testing Utilities\n\n\\`@blokjs/runner\\` provides testing utilities for nodes and workflows.\n\n### NodeTestHarness \u2014 Unit test a single node:\n\\`\\`\\`typescript\nimport { NodeTestHarness } from \"@blokjs/runner\";\nconst harness = new NodeTestHarness(myNode);\nconst result = await harness.execute({ input: \"data\" });\nharness.assertSuccess(result);\nharness.assertOutput(result, { expected: \"output\" });\n\\`\\`\\`\n\n### WorkflowTestRunner \u2014 Integration test a workflow:\n\\`\\`\\`typescript\nimport { WorkflowTestRunner } from \"@blokjs/runner\";\nconst runner = new WorkflowTestRunner({ verbose: true });\nrunner.registerNode(\"validate\", ValidateNode);\nrunner.mockNode(\"external-api\", async (input) => ({ result: \"mocked\" }));\nrunner.loadWorkflow(workflowDefinition);\nconst result = await runner.execute({ input: \"data\" });\n// result.success, result.output, result.trace, result.nodeResults\n\\`\\`\\`\n\n---\n\n## Runtime Adapter System\n\nAll non-NodeJS SDKs communicate via HTTP:\n- **POST /execute** \u2014 Execute node with context\n- **GET /health** \u2014 Health check\n\nEnvironment variables: \\`RUNTIME_{LANG}_HOST\\` / \\`RUNTIME_{LANG}_PORT\\`\n\nRuntime nodes auto-save \\`result.data\\` to \\`ctx.vars[stepName]\\`.\n\n---\n\n## Blok Studio\n\nReal-time workflow trace visualization UI.\n\n- Launch: \\`blokctl trace\\` or \\`blokctl studio\\`\n- API: \\`/__blok/runs\\`, \\`/__blok/runs/:id\\`, \\`/__blok/runs/:id/stream\\` (SSE)\n- Disable: \\`BLOK_TRACE_ENABLED=false\\`\n\n---\n\n## Do NOT\n\n- Do NOT rely on \\`ctx.response.data\\` for data from non-previous steps \u2014 it gets overwritten\n- Do NOT create class-based nodes \u2014 use \\`defineNode()\\` instead\n- Do NOT use \\`any\\` type \u2014 use \\`unknown\\` and narrow with Zod\n- Do NOT hardcode runtime ports \u2014 use environment variables\n- Do NOT skip Zod input/output schemas\n- Do NOT edit files in \\`.blok/runtimes/\\` \u2014 they are auto-generated\n\n## Do\n\n- Use \\`$.state.<id>\\` (or \\`js/ctx.state.<id>\\`) to pass data between non-adjacent steps \u2014 every step default-stores its output there\n- Opt out per step with \\`ephemeral: true\\` when the step is a side effect only\n- Use Zod schemas for all input/output validation\n- Use \\`defineNode()\\` for all new nodes\n- Handle errors via GlobalError with appropriate HTTP status codes\n- Keep nodes focused \u2014 one responsibility per node\n";
-declare const claude_md = "# Blok Project \u2014 Claude Code Guide\n\nRead \\`AGENTS.md\\` for full architecture and API details. This file contains Claude-specific guidance.\n\n## Quick Commands\n\n\\`\\`\\`bash\nnpm run dev                        # Start dev server\nblokctl dev                        # Multi-runtime dev server\nblokctl create node <name>         # Scaffold new node\nblokctl create workflow <name>     # Scaffold new workflow\nblokctl trace                      # Open Blok Studio\nnpm test                           # Run tests\n\\`\\`\\`\n\n## Context Rules (Memorize These)\n\n1. **\\`ctx.prev\\` is the immediately previous step's output.** Overwritten every step.\n2. **\\`ctx.state[<id>]\\` PERSISTS across the workflow.** Every step default-stores its output there; reference via \\`$.state.<id>\\` or \\`js/ctx.state.<id>\\`. Opt out with \\`ephemeral: true\\`.\n3. **Blueprint Mapper resolves \\`$.<path>\\` and \\`js/\\` expressions BEFORE node execution.**\n\nWhen users have data flow issues, check these three things first.\n\n## Debugging Workflows\n\n1. **Verify structure**: Every step has an \\`id\\` and a \\`use\\` (v2). v1's \\`name\\` + \\`nodes{}\\` still works but is normalized at load time.\n2. **Trace data flow**: Does the target step reference the correct source id (\\`$.state.<id>\\`)? Did the source step have \\`ephemeral: true\\` accidentally?\n3. **Check runtimes**: SDK containers running? \\`GET http://localhost:{port}/health\\`\n4. **Check Studio traces**: \\`/__blok/runs/:id\\` shows step-by-step inputs/outputs/errors\n\n### Common Errors\n\n| Error | Fix |\n|-------|-----|\n| \\`Node type X not found\\` | Wrong \\`type\\` in step \u2014 use module, local, or runtime.* |\n| \\`Validation failed\\` | Zod schema mismatch \u2014 check input schema vs actual data |\n| \\`Runtime execution error\\` | SDK container not running \u2014 check health endpoint |\n| \\`ctx.state['X'] undefined\\` | Source step has \\`ephemeral: true\\`, or the id doesn't match what's referenced in \\`$.state.<id>\\` |\n| \\`set_var, which was removed in v0.5\\` | Drop \\`set_var: true\\` (it's the default) or replace \\`set_var: false\\` with \\`ephemeral: true\\`. Run \\`blokctl migrate workflows\\`. |\n\n## Generating Code\n\nAlways use \\`defineNode()\\`. Never class-based BlokService.\n\n\\`\\`\\`typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"node-name\",\n  description: \"What this node does\",\n  input: z.object({ /* Zod schema */ }),\n  output: z.object({ /* Zod schema */ }),\n  async execute(ctx, input) {\n    return { /* must match output schema */ };\n  },\n});\n\\`\\`\\`\n\n### Checklist:\n- Zod input schema covers all inputs\n- Zod output schema matches execute() return\n- Node name matches workflow references\n- No \\`any\\` types \u2014 use \\`z.unknown()\\` if dynamic\n- \\`export default defineNode(...)\\`\n\n## Worker Workflows\n\nWorker trigger processes background jobs from a queue:\n\n\\`\\`\\`typescript\nWorkflow({ name: \"Process Job\", version: \"1.0.0\" })\n  .addTrigger(\"worker\", { queue: \"background-jobs\" })\n  .addStep({ name: \"process\", node: \"my-processor\", type: \"module\",\n    inputs: { payload: \"js/ctx.request.body\", jobId: \"js/ctx.request.params.jobId\" } });\n\\`\\`\\`\n\nJob data: \\`ctx.request.body\\` = payload, \\`ctx.request.params.queue/jobId/attempt\\` = metadata.\nAdapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev).\n\n## Testing\n\n\\`\\`\\`typescript\nimport { NodeTestHarness, WorkflowTestRunner } from \"@blokjs/runner\";\n\n// Unit test a node\nconst harness = new NodeTestHarness(myNode);\nconst result = await harness.execute({ input: \"data\" });\nharness.assertSuccess(result);\n\n// Integration test a workflow\nconst runner = new WorkflowTestRunner({ mockAllNodes: true });\nrunner.loadWorkflow(definition);\nconst wfResult = await runner.execute({ input: \"data\" });\n\\`\\`\\`\n\n## Blok Studio Help\n\n- Launch: \\`blokctl trace\\` or navigate to \\`/__blok\\`\n- \"No output\" \u2192 Node not returning data or Zod output validation failed\n- \"Step error\" \u2192 Expand error \u2014 check if 400 (validation) or 500 (runtime)\n- \"State not passing\" \u2192 Source step has \\`ephemeral: true\\`, OR target's \\`$.state.<id>\\` references a non-existent step id\n\n## Debugging Workers\n\n- NATS not reachable \u2192 Check \\`NATS_SERVERS\\` env var, ensure NATS is running\n- Job timeout \u2192 Increase \\`timeout\\` in trigger config or optimize node\n- Max retries exceeded \u2192 Check node errors, job moves to DLQ\n\n## Do NOT\n\n- Do NOT suggest class-based BlokService for new nodes\n- Do NOT generate code with \\`any\\` types\n- Do NOT assume \\`ctx.response.data\\` persists across steps\n- Do NOT skip Zod schemas when creating nodes\n- Do NOT edit files in \\`.blok/runtimes/\\`\n";
+declare const agents_md = "# Blok Project\n\nBlok is a TypeScript-first workflow orchestration framework. It executes declarative workflows (JSON or TypeScript DSL) composed of steps (nodes) that run across 8 language runtimes: NodeJS, Python3, Go, Rust, Java, C#, PHP, and Ruby.\n\n## Project Structure\n\n```\n\u251C\u2500\u2500 src/\n\u2502   \u2514\u2500\u2500 nodes/             # TypeScript node implementations\n\u251C\u2500\u2500 runtimes/              # Non-NodeJS runtime nodes (Go, Python3, etc.)\n\u2502   \u2514\u2500\u2500 {lang}/nodes/      # Language-specific node implementations\n\u251C\u2500\u2500 workflows/\n\u2502   \u251C\u2500\u2500 json/              # Workflow definitions (JSON)\n\u2502   \u251C\u2500\u2500 yaml/              # Workflow definitions (YAML)\n\u2502   \u2514\u2500\u2500 toml/              # Workflow definitions (TOML)\n\u251C\u2500\u2500 .blok/\n\u2502   \u251C\u2500\u2500 config.json        # Runtime configuration (ports, start commands)\n\u2502   \u2514\u2500\u2500 runtimes/          # Auto-generated runtime scaffolds\n\u251C\u2500\u2500 .env.local             # Environment variables (ports, paths)\n\u2514\u2500\u2500 supervisord.conf       # Process management config\n```\n\n## Commands\n\n```bash\nnpm run dev                # Start dev server (or blokctl dev for multi-runtime)\nnpm run build              # Build project\nnpm test                   # Run tests\nblokctl create node <name> # Scaffold a new node\nblokctl create workflow <n># Scaffold a new workflow\nblokctl trace              # Open Blok Studio (trace visualization)\nblokctl studio             # Alias for blokctl trace\n```\n\n## Context \u2014 Critical Data Flow\n\nThe Context type is the central execution state passed through every step.\n\n```typescript\ntype Context = {\n  id: string;                      // Unique request ID\n  request: RequestContext;          // Incoming request (body, headers, params, query)\n  response: ResponseContext;       // Current step output \u2014 OVERWRITTEN every step\n  vars?: VarsContext;              // Persistent variables \u2014 PERSISTS across workflow\n  config: ConfigContext;           // Node config (inputs resolved by Mapper)\n  env?: EnvContext;                // process.env access\n  logger: LoggerContext;\n  error: ErrorContext;\n};\n```\n\n### The Two Critical Rules\n\n**Rule 1: \\`ctx.prev\\` carries the immediately previous step's output.**\nEach step's output replaces \\`ctx.prev\\`. Use it for adjacent-step access only.\n\n**Rule 2: \\`ctx.state[id]\\` PERSISTS across the entire workflow.**\nEvery step's output is auto-stored at \\`ctx.state[<step-id>]\\` (the v2 default-store rule). Downstream steps reference it via \\`$.state.<id>\\` (TS DSL) or \\`\"$.state.<id>\"\\` / \\`\"js/ctx.state.<id>\"\\` (JSON). Opt out per step with \\`ephemeral: true\\`.\n\n### Data Flow Example\n\n```\nStep 1: id \"fetch-user\"\n  \u2192 ctx.state[\"fetch-user\"] = { id: \"123\", name: \"Alice\" }\n  \u2192 ctx.prev = { id: \"123\", name: \"Alice\" }\n\nStep 2: id \"transform\"\n  \u2192 ctx.state[\"transform\"] = { result: \"done\" }\n  \u2192 ctx.prev = { result: \"done\" }              \u2190 Step 1 output GONE from prev\n  \u2192 ctx.state[\"fetch-user\"] still available\n\nStep 3: id \"output\"\n  \u2192 Can read ctx.state[\"fetch-user\"].name      \u2190 still \"Alice\"\n```\n\n### Blueprint Mapper \u2014 Expression Resolution\n\nNode inputs support dynamic expressions resolved BEFORE node execution:\n\n```json\n{\n  \"inputs\": {\n    \"userId\": \"js/ctx.request.body.userId\",\n    \"chain\": \"js/ctx.vars['previous-step'].chain\",\n    \"previous\": \"js/ctx.response.data.result\"\n  }\n}\n```\n\nAvailable in js/ expressions: \\`ctx\\` (full context), \\`data\\` (ctx.prev.data), \\`func\\` (ctx.func), \\`vars\\` (alias for ctx.state).\n\n---\n\n## Creating Nodes with defineNode\n\nUse \\`defineNode()\\` for all new nodes. Never use the legacy class-based pattern.\n\n```typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"fetch-user\",\n  description: \"Fetches user by ID\",\n\n  input: z.object({\n    userId: z.string().uuid(),\n  }),\n\n  output: z.object({\n    user: z.object({\n      id: z.string(),\n      name: z.string(),\n      email: z.string().email(),\n    }),\n  }),\n\n  async execute(ctx, input) {\n    const user = await fetchUser(input.userId);\n    return { user };\n  },\n});\n```\n\n### Key Behaviors\n\n- Zod input/output validation runs automatically\n- ZodError is mapped to GlobalError with HTTP 400\n- \\`flow: true\\` nodes return NodeBase[] for conditional execution\n- \\`contentType\\` sets response Content-Type (e.g., \"text/html\")\n- Always \\`export default defineNode(...)\\`\n\n---\n\n## Workflow Structure (JSON)\n\n```json\n{\n  \"name\": \"My Workflow\",\n  \"version\": \"1.0.0\",\n  \"trigger\": {\n    \"http\": { \"method\": \"POST\", \"path\": \"/api/process\", \"accept\": \"application/json\" }\n  },\n  \"steps\": [\n    { \"id\": \"fetch\",   \"use\": \"@blokjs/api-call\", \"inputs\": { \"url\": \"https://api.example.com\", \"method\": \"GET\" } },\n    { \"id\": \"process\", \"use\": \"my-node\",         \"inputs\": { \"data\": \"$.state.fetch\" } },\n    { \"id\": \"go-step\", \"use\": \"chain-test\", \"type\": \"runtime.go\", \"inputs\": { \"processed\": \"$.state.process\" } }\n  ]\n}\n```\n\n### Workflow Naming\n\nEvery workflow's \\`name\\` must be UNIQUE across the project. The\n\\`WorkflowRegistry\\` rejects duplicate names at boot, so a collision\nmeans only one of the colliding workflows ever registers.\n\nPrefer a dotted \\`domain.action\\` convention \u2014 \\`countries.list\\`,\n\\`users.create\\`, \\`orders.refund\\`. The typed client\n(\\`@blokjs/client\\`) and \\`blokctl gen app-types\\` nest workflows by\ntheir dotted name, so a clean name surfaces as\n\\`blok.countries.list(...)\\` instead of a quoted\n\\`blok[\"World Countries\"]\\` accessor. Duplicate names also make\n\\`gen app-types\\` report a collision and DROP one workflow from the\ngenerated \\`BlokApp\\` type.\n\n### Step Types\n\n| Type | Description |\n|------|-------------|\n| \\`module\\` | TypeScript node from registered modules |\n| \\`local\\` | TypeScript node from filesystem (NODES_PATH) |\n| \\`runtime.python3\\` | Python3 SDK container (port 9007) |\n| \\`runtime.go\\` | Go SDK container (port 9001) |\n| \\`runtime.rust\\` | Rust SDK container (port 9002) |\n| \\`runtime.java\\` | Java SDK container (port 9003) |\n| \\`runtime.csharp\\` | C# SDK container (port 9004) |\n| \\`runtime.php\\` | PHP SDK container (port 9005) |\n| \\`runtime.ruby\\` | Ruby SDK container (port 9006) |\n\n### Conditional Workflow (if-else)\n\n```json\n{\n  \"nodes\": {\n    \"filter\": {\n      \"conditions\": [\n        {\n          \"type\": \"if\",\n          \"condition\": \"ctx.request.query.active === \\\\\"true\\\\\"\",\n          \"steps\": [{ \"name\": \"active-path\", \"node\": \"handle-active\", \"type\": \"module\" }]\n        },\n        {\n          \"type\": \"else\",\n          \"steps\": [{ \"name\": \"default-path\", \"node\": \"handle-default\", \"type\": \"module\" }]\n        }\n      ]\n    }\n  }\n}\n```\n\n---\n\n## Trigger Types\n\n| Trigger | Example Config |\n|---------|---------------|\n| \\`http\\` | \\`{ \"method\": \"GET\", \"path\": \"/\", \"accept\": \"application/json\" }\\` |\n| \\`grpc\\` | \\`{ \"service\": \"UserService\", \"method\": \"GetUser\" }\\` |\n| \\`cron\\` | \\`{ \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\" }\\` |\n| \\`queue\\` | \\`{ \"provider\": \"kafka\", \"topic\": \"events\" }\\` |\n| \\`pubsub\\` | \\`{ \"provider\": \"gcp\", \"topic\": \"updates\" }\\` |\n| \\`webhook\\` | \\`{ \"source\": \"github\", \"events\": [\"push\"] }\\` |\n| \\`websocket\\` | \\`{ \"events\": [\"message\"], \"path\": \"/ws\" }\\` |\n| \\`sse\\` | \\`{ \"events\": [\"update\"], \"path\": \"/stream\" }\\` |\n| \\`worker\\` | \\`{ \"queue\": \"jobs\", \"concurrency\": 5, \"retries\": 3 }\\` |\n\n### Worker Trigger\n\nThe worker trigger processes background jobs from a queue with retry logic and concurrency control.\n\n\\`\\`\\`typescript\nWorkflow({ name: \"Process Job\", version: \"1.0.0\" })\n  .addTrigger(\"worker\", { queue: \"background-jobs\" })\n  .addStep({\n    name: \"process\",\n    node: \"my-processor\",\n    type: \"module\",\n    inputs: { payload: \"js/ctx.request.body\", jobId: \"js/ctx.request.params.jobId\" },\n  });\n\\`\\`\\`\n\nJob context: \\`ctx.request.body\\` = payload, \\`ctx.request.params.queue\\` = queue name, \\`ctx.request.params.jobId\\` = job ID, \\`ctx.request.params.attempt\\` = attempt count, \\`ctx.vars._worker_job\\` = full metadata.\n\nAdapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev only).\n\n### NATS JetStream\n\nRecommended queue/worker backend. Environment variables:\n\\`\\`\\`\nNATS_SERVERS=localhost:4222\nNATS_STREAM_NAME=blok-queue     # or blok-worker for worker trigger\nNATS_TOKEN=                      # optional auth\n\\`\\`\\`\n\nQueue providers: \\`kafka\\`, \\`rabbitmq\\`, \\`sqs\\`, \\`redis\\`, \\`beanstalk\\`, \\`nats\\`\n\n### Standalone Workers (Go, Rust, Python)\n\nGo, Rust, and Python SDKs include standalone NATS workers that connect directly to NATS without the TypeScript runner:\n\n\\`\\`\\`\nWORKER_CONCURRENCY=1             # Max concurrent jobs\nWORKER_MAX_RETRIES=3             # Max delivery attempts\nWORKER_QUEUES=queue1,queue2      # Queues to consume\n\\`\\`\\`\n\n---\n\n## Testing Utilities\n\n\\`@blokjs/runner\\` provides testing utilities for nodes and workflows.\n\n### NodeTestHarness \u2014 Unit test a single node:\n\\`\\`\\`typescript\nimport { NodeTestHarness } from \"@blokjs/runner\";\nconst harness = new NodeTestHarness(myNode);\nconst result = await harness.execute({ input: \"data\" });\nharness.assertSuccess(result);\nharness.assertOutput(result, { expected: \"output\" });\n\\`\\`\\`\n\n### WorkflowTestRunner \u2014 Integration test a workflow:\n\\`\\`\\`typescript\nimport { WorkflowTestRunner } from \"@blokjs/runner\";\nconst runner = new WorkflowTestRunner({ verbose: true });\nrunner.registerNode(\"validate\", ValidateNode);\nrunner.mockNode(\"external-api\", async (input) => ({ result: \"mocked\" }));\nrunner.loadWorkflow(workflowDefinition);\nconst result = await runner.execute({ input: \"data\" });\n// result.success, result.output, result.trace, result.nodeResults\n\\`\\`\\`\n\n---\n\n## Runtime Adapter System\n\nAll non-NodeJS SDKs communicate via HTTP:\n- **POST /execute** \u2014 Execute node with context\n- **GET /health** \u2014 Health check\n\nEnvironment variables: \\`RUNTIME_{LANG}_HOST\\` / \\`RUNTIME_{LANG}_PORT\\`\n\nRuntime nodes auto-save \\`result.data\\` to \\`ctx.vars[stepName]\\`.\n\n---\n\n## Blok Studio\n\nReal-time workflow trace visualization UI.\n\n- Launch: \\`blokctl trace\\` or \\`blokctl studio\\`\n- API: \\`/__blok/runs\\`, \\`/__blok/runs/:id\\`, \\`/__blok/runs/:id/stream\\` (SSE)\n- Disable: \\`BLOK_TRACE_ENABLED=false\\`\n\n---\n\n## Do NOT\n\n- Do NOT rely on \\`ctx.response.data\\` for data from non-previous steps \u2014 it gets overwritten\n- Do NOT create class-based nodes \u2014 use \\`defineNode()\\` instead\n- Do NOT use \\`any\\` type \u2014 use \\`unknown\\` and narrow with Zod\n- Do NOT hardcode runtime ports \u2014 use environment variables\n- Do NOT skip Zod input/output schemas\n- Do NOT edit files in \\`.blok/runtimes/\\` \u2014 they are auto-generated\n\n## Do\n\n- Use \\`$.state.<id>\\` (or \\`js/ctx.state.<id>\\`) to pass data between non-adjacent steps \u2014 every step default-stores its output there\n- Opt out per step with \\`ephemeral: true\\` when the step is a side effect only\n- Use Zod schemas for all input/output validation\n- Use \\`defineNode()\\` for all new nodes\n- Handle errors via GlobalError with appropriate HTTP status codes\n- Keep nodes focused \u2014 one responsibility per node\n";
+declare const claude_md = "# Blok Project \u2014 Claude Code Guide\n\nRead \\`AGENTS.md\\` for full architecture and API details. This file contains Claude-specific guidance.\n\n## Quick Commands\n\n\\`\\`\\`bash\nnpm run dev                        # Start dev server\nblokctl dev                        # Multi-runtime dev server\nblokctl create node <name>         # Scaffold new node\nblokctl create workflow <name>     # Scaffold new workflow\nblokctl trace                      # Open Blok Studio\nnpm test                           # Run tests\n\\`\\`\\`\n\n## Context Rules (Memorize These)\n\n1. **\\`ctx.prev\\` is the immediately previous step's output.** Overwritten every step.\n2. **\\`ctx.state[<id>]\\` PERSISTS across the workflow.** Every step default-stores its output there; reference via \\`$.state.<id>\\` or \\`js/ctx.state.<id>\\`. Opt out with \\`ephemeral: true\\`.\n3. **Blueprint Mapper resolves \\`$.<path>\\` and \\`js/\\` expressions BEFORE node execution.**\n\nWhen users have data flow issues, check these three things first.\n\n## Workflow Naming\n\nWorkflow \\`name\\` must be UNIQUE across the project \u2014 the\n\\`WorkflowRegistry\\` rejects duplicates at boot. Use a dotted\n\\`domain.action\\` convention (\\`countries.list\\`, \\`users.create\\`)\nso the typed client (\\`@blokjs/client\\`) and \\`blokctl gen app-types\\`\nexpose clean nested accessors like \\`blok.countries.list(...)\\`. Duplicate\nnames make \\`gen app-types\\` flag a collision and drop one workflow from\nthe generated \\`BlokApp\\` type.\n\n## Debugging Workflows\n\n1. **Verify structure**: Every step has an \\`id\\` and a \\`use\\` (v2). v1's \\`name\\` + \\`nodes{}\\` still works but is normalized at load time.\n2. **Trace data flow**: Does the target step reference the correct source id (\\`$.state.<id>\\`)? Did the source step have \\`ephemeral: true\\` accidentally?\n3. **Check runtimes**: SDK containers running? \\`GET http://localhost:{port}/health\\`\n4. **Check Studio traces**: \\`/__blok/runs/:id\\` shows step-by-step inputs/outputs/errors\n\n### Common Errors\n\n| Error | Fix |\n|-------|-----|\n| \\`Node type X not found\\` | Wrong \\`type\\` in step \u2014 use module, local, or runtime.* |\n| \\`Validation failed\\` | Zod schema mismatch \u2014 check input schema vs actual data |\n| \\`Runtime execution error\\` | SDK container not running \u2014 check health endpoint |\n| \\`ctx.state['X'] undefined\\` | Source step has \\`ephemeral: true\\`, or the id doesn't match what's referenced in \\`$.state.<id>\\` |\n| \\`set_var, which was removed in v0.5\\` | Drop \\`set_var: true\\` (it's the default) or replace \\`set_var: false\\` with \\`ephemeral: true\\`. Run \\`blokctl migrate workflows\\`. |\n\n## Generating Code\n\nAlways use \\`defineNode()\\`. Never class-based BlokService.\n\n\\`\\`\\`typescript\nimport { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\nexport default defineNode({\n  name: \"node-name\",\n  description: \"What this node does\",\n  input: z.object({ /* Zod schema */ }),\n  output: z.object({ /* Zod schema */ }),\n  async execute(ctx, input) {\n    return { /* must match output schema */ };\n  },\n});\n\\`\\`\\`\n\n### Checklist:\n- Zod input schema covers all inputs\n- Zod output schema matches execute() return\n- Node name matches workflow references\n- No \\`any\\` types \u2014 use \\`z.unknown()\\` if dynamic\n- \\`export default defineNode(...)\\`\n\n## Worker Workflows\n\nWorker trigger processes background jobs from a queue:\n\n\\`\\`\\`typescript\nWorkflow({ name: \"Process Job\", version: \"1.0.0\" })\n  .addTrigger(\"worker\", { queue: \"background-jobs\" })\n  .addStep({ name: \"process\", node: \"my-processor\", type: \"module\",\n    inputs: { payload: \"js/ctx.request.body\", jobId: \"js/ctx.request.params.jobId\" } });\n\\`\\`\\`\n\nJob data: \\`ctx.request.body\\` = payload, \\`ctx.request.params.queue/jobId/attempt\\` = metadata.\nAdapters: NATS JetStream (recommended), BullMQ (Redis), InMemory (dev).\n\n## Testing\n\n\\`\\`\\`typescript\nimport { NodeTestHarness, WorkflowTestRunner } from \"@blokjs/runner\";\n\n// Unit test a node\nconst harness = new NodeTestHarness(myNode);\nconst result = await harness.execute({ input: \"data\" });\nharness.assertSuccess(result);\n\n// Integration test a workflow\nconst runner = new WorkflowTestRunner({ mockAllNodes: true });\nrunner.loadWorkflow(definition);\nconst wfResult = await runner.execute({ input: \"data\" });\n\\`\\`\\`\n\n## Blok Studio Help\n\n- Launch: \\`blokctl trace\\` or navigate to \\`/__blok\\`\n- \"No output\" \u2192 Node not returning data or Zod output validation failed\n- \"Step error\" \u2192 Expand error \u2014 check if 400 (validation) or 500 (runtime)\n- \"State not passing\" \u2192 Source step has \\`ephemeral: true\\`, OR target's \\`$.state.<id>\\` references a non-existent step id\n\n## Debugging Workers\n\n- NATS not reachable \u2192 Check \\`NATS_SERVERS\\` env var, ensure NATS is running\n- Job timeout \u2192 Increase \\`timeout\\` in trigger config or optimize node\n- Max retries exceeded \u2192 Check node errors, job moves to DLQ\n\n## Do NOT\n\n- Do NOT suggest class-based BlokService for new nodes\n- Do NOT generate code with \\`any\\` types\n- Do NOT assume \\`ctx.response.data\\` persists across steps\n- Do NOT skip Zod schemas when creating nodes\n- Do NOT edit files in \\`.blok/runtimes/\\`\n";
 declare const function_first_node_file = "import { defineNode } from \"@blokjs/runner\";\nimport { z } from \"zod\";\n\n/**\n * A function-first node that demonstrates the modern defineNode pattern.\n * This node is type-safe, validated, and requires 60% less boilerplate.\n */\nexport default defineNode({\n\tname: \"{{NODE_NAME}}\",\n\tdescription: \"A function-first node with Zod validation\",\n\n\t// Input schema using Zod - automatically validated\n\tinput: z.object({\n\t\tmessage: z.string().optional().default(\"Hello World\"),\n\t}),\n\n\t// Output schema using Zod - automatically validated\n\toutput: z.object({\n\t\tmessage: z.string(),\n\t\ttimestamp: z.string(),\n\t}),\n\n\t// Execute function - type-safe with inferred types from Zod schemas\n\tasync execute(ctx, input) {\n\t\t// Your business logic here\n\t\t// - ctx.vars: Access workflow variables\n\t\t// - ctx.request: Access HTTP request data\n\t\t// - ctx.logger: Log messages\n\t\t// - ctx.env: Access environment variables\n\n\t\t// Example: Store data for downstream nodes\n\t\tctx.vars[\"processed-message\"] = input.message;\n\n\t\t// Return type-safe output (validated automatically)\n\t\treturn {\n\t\t\tmessage: `Processed: ${input.message}`,\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t};\n\t},\n});\n";
 export { node_file, package_dependencies, package_dev_dependencies, python3_file, examples_url, workflow_template, supervisord_nodejs, supervisord_python, go_node_file, go_mod_file, go_dockerfile, java_node_file, java_pom_file, java_dockerfile, rust_node_file, rust_cargo_file, rust_dockerfile, csharp_node_file, csharp_csproj_file, csharp_dockerfile, php_node_file, php_composer_file, php_dockerfile, ruby_node_file, ruby_gemfile, ruby_dockerfile, function_first_node_file, agents_md, claude_md, };

package/dist/commands/create/utils/Examples.js

@@ -762,6 +762,21 @@ export default defineNode({
 }
 \`\`\`
 
+### Workflow Naming
+
+Every workflow's \\\`name\\\` must be UNIQUE across the project. The
+\\\`WorkflowRegistry\\\` rejects duplicate names at boot, so a collision
+means only one of the colliding workflows ever registers.
+
+Prefer a dotted \\\`domain.action\\\` convention — \\\`countries.list\\\`,
+\\\`users.create\\\`, \\\`orders.refund\\\`. The typed client
+(\\\`@blokjs/client\\\`) and \\\`blokctl gen app-types\\\` nest workflows by
+their dotted name, so a clean name surfaces as
+\\\`blok.countries.list(...)\\\` instead of a quoted
+\\\`blok["World Countries"]\\\` accessor. Duplicate names also make
+\\\`gen app-types\\\` report a collision and DROP one workflow from the
+generated \\\`BlokApp\\\` type.
+
 ### Step Types
 
 | Type | Description |
@@ -945,6 +960,16 @@ npm test                           # Run tests
 
 When users have data flow issues, check these three things first.
 
+## Workflow Naming
+
+Workflow \\\`name\\\` must be UNIQUE across the project — the
+\\\`WorkflowRegistry\\\` rejects duplicates at boot. Use a dotted
+\\\`domain.action\\\` convention (\\\`countries.list\\\`, \\\`users.create\\\`)
+so the typed client (\\\`@blokjs/client\\\`) and \\\`blokctl gen app-types\\\`
+expose clean nested accessors like \\\`blok.countries.list(...)\\\`. Duplicate
+names make \\\`gen app-types\\\` flag a collision and drop one workflow from
+the generated \\\`BlokApp\\\` type.
+
 ## Debugging Workflows
 
 1. **Verify structure**: Every step has an \\\`id\\\` and a \\\`use\\\` (v2). v1's \\\`name\\\` + \\\`nodes{}\\\` still works but is normalized at load time.

package/dist/commands/gen/appTypes.d.ts

@@ -0,0 +1,13 @@
+import type { OptionValues } from "commander";
+export interface WorkflowEntry {
+    name: string;
+    file: string;
+}
+export declare function extractWorkflowName(source: string): string | null;
+export declare function nameToIdentifier(name: string): string;
+export declare function importSpecifier(outFile: string, workflowFile: string): string;
+export declare function buildAppTypeSource(entries: readonly WorkflowEntry[], outFile: string): {
+    source: string;
+    collisions: string[];
+};
+export declare function generateAppTypes(opts: OptionValues): Promise<void>;

package/dist/commands/gen/appTypes.js

@@ -0,0 +1,195 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import color from "picocolors";
+export function extractWorkflowName(source) {
+    const stripped = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+    const factory = /\b(?:workflow|Workflow)\s*\(/.exec(stripped);
+    if (!factory)
+        return null;
+    const rest = stripped.slice(factory.index);
+    const nameMatch = /\bname\s*:\s*(["'`])([^"'`]+)\1/.exec(rest);
+    return nameMatch ? nameMatch[2].trim() : null;
+}
+export function nameToIdentifier(name) {
+    const parts = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const camel = parts.map((p, i) => (i === 0 ? p : p.charAt(0).toUpperCase() + p.slice(1))).join("");
+    const safe = camel.length === 0 ? "wf" : camel;
+    return /^[0-9]/.test(safe) ? `wf_${safe}` : safe;
+}
+export function importSpecifier(outFile, workflowFile) {
+    let rel = path.relative(path.dirname(outFile), workflowFile).replace(/\\/g, "/").replace(/\.ts$/, "");
+    if (!rel.startsWith("."))
+        rel = `./${rel}`;
+    return rel;
+}
+function isLeaf(node) {
+    return typeof node.__leaf === "string";
+}
+export function buildAppTypeSource(entries, outFile) {
+    const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+    const collisions = [];
+    const usedIdents = new Map();
+    const imports = [];
+    const tree = {};
+    for (const entry of sorted) {
+        let ident = nameToIdentifier(entry.name);
+        if (usedIdents.has(ident) && usedIdents.get(ident) !== entry.name) {
+            let n = 2;
+            while (usedIdents.has(`${ident}${n}`))
+                n++;
+            ident = `${ident}${n}`;
+        }
+        usedIdents.set(ident, entry.name);
+        imports.push(`import type ${ident} from "${importSpecifier(outFile, entry.file)}";`);
+        const segments = entry.name.split(".").filter(Boolean);
+        let node = tree;
+        let collided = false;
+        for (let i = 0; i < segments.length; i++) {
+            const seg = segments[i];
+            const last = i === segments.length - 1;
+            if (last) {
+                if (node[seg] !== undefined) {
+                    collisions.push(entry.name);
+                    collided = true;
+                    break;
+                }
+                node[seg] = { __leaf: ident };
+            }
+            else {
+                const existing = node[seg];
+                if (existing === undefined) {
+                    const child = {};
+                    node[seg] = child;
+                    node = child;
+                }
+                else if (isLeaf(existing)) {
+                    collisions.push(entry.name);
+                    collided = true;
+                    break;
+                }
+                else {
+                    node = existing;
+                }
+            }
+        }
+        if (collided)
+            imports.pop();
+    }
+    const render = (node, indent) => {
+        const lines = ["{"];
+        for (const key of Object.keys(node).sort()) {
+            const child = node[key];
+            const k = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+            if (isLeaf(child)) {
+                lines.push(`${indent}\t${k}: ${child.__leaf};`);
+            }
+            else {
+                lines.push(`${indent}\t${k}: ${render(child, `${indent}\t`)};`);
+            }
+        }
+        lines.push(`${indent}}`);
+        return lines.join("\n");
+    };
+    const header = [
+        "// AUTO-GENERATED by `blokctl gen app-types`. Do not edit by hand.",
+        "// Regenerate after adding, removing, or renaming a workflow.",
+        "// Consumed by `@blokjs/client`: `createBlokClient<BlokApp>()`.",
+        "",
+    ].join("\n");
+    const body = imports.length === 0
+        ? "export type BlokApp = Record<string, never>;\n"
+        : `${imports.join("\n")}\n\nexport type BlokApp = ${render(tree, "")};\n`;
+    return { source: `${header}${body}`, collisions };
+}
+async function collectTsFiles(dir) {
+    const out = [];
+    let dirents;
+    try {
+        dirents = await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const d of dirents) {
+        if (d.name.startsWith("_") || d.name.startsWith("."))
+            continue;
+        const full = path.join(dir, d.name);
+        if (d.isDirectory()) {
+            out.push(...(await collectTsFiles(full)));
+        }
+        else if (d.name.endsWith(".ts") &&
+            !d.name.endsWith(".test.ts") &&
+            !d.name.endsWith(".spec.ts") &&
+            !d.name.endsWith(".d.ts")) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+async function resolveWorkflowsDir(cwd, explicit) {
+    const candidates = explicit
+        ? [explicit]
+        : ["triggers/http/src/workflows", "src/workflows", "workflows/ts", "workflows"];
+    for (const c of candidates) {
+        const abs = path.isAbsolute(c) ? c : path.join(cwd, c);
+        try {
+            const stat = await fsp.stat(abs);
+            if (stat.isDirectory())
+                return abs;
+        }
+        catch {
+        }
+    }
+    return null;
+}
+export async function generateAppTypes(opts) {
+    const cwd = process.cwd();
+    const explicitDir = opts.dir ?? null;
+    console.log(color.cyan("\n🧬 Blok app-types generator"));
+    console.log(color.dim("Generates the typed `BlokApp` index consumed by @blokjs/client.\n"));
+    const dir = await resolveWorkflowsDir(cwd, explicitDir);
+    if (!dir) {
+        console.log(color.red("❌ Could not find a TS workflows directory. Looked in: triggers/http/src/workflows/, " +
+            "src/workflows/, workflows/. Pass --dir <path> to override."));
+        process.exit(1);
+        return;
+    }
+    const outFile = path.isAbsolute(opts.out ?? "")
+        ? opts.out
+        : path.join(cwd, opts.out ?? "blok-app.d.ts");
+    console.log(color.dim(`Scanning ${color.cyan(dir)} (recursive)\n`));
+    const files = await collectTsFiles(dir);
+    const entries = [];
+    const skipped = [];
+    for (const file of files) {
+        const src = await fsp.readFile(file, "utf8");
+        const name = extractWorkflowName(src);
+        if (name)
+            entries.push({ name, file });
+        else
+            skipped.push(path.relative(cwd, file));
+    }
+    if (entries.length === 0) {
+        console.log(color.yellow("No TS workflows with a literal `name:` found — nothing to generate."));
+        if (skipped.length > 0)
+            console.log(color.dim(`Skipped (no literal name): ${skipped.join(", ")}`));
+        return;
+    }
+    const { source, collisions } = buildAppTypeSource(entries, outFile);
+    if (opts.dryRun === true) {
+        console.log(color.dim(`— dry run — would write ${color.cyan(path.relative(cwd, outFile))}:\n`));
+        console.log(source);
+    }
+    else {
+        await fsp.mkdir(path.dirname(outFile), { recursive: true });
+        await fsp.writeFile(outFile, source, "utf8");
+        console.log(color.green(`✅ Wrote ${color.cyan(path.relative(cwd, outFile))} (${entries.length} workflow(s)).`));
+    }
+    for (const c of collisions) {
+        console.log(color.yellow(`⚠️  name collision — "${c}" overlaps another workflow's path and was dropped.`));
+    }
+    if (skipped.length > 0) {
+        console.log(color.dim(`ℹ️  Skipped ${skipped.length} file(s) without a literal workflow name (dynamic name or not a workflow): ${skipped.join(", ")}`));
+    }
+    console.log(color.dim('\nNext: `import type { BlokApp } from "<out>"` and `createBlokClient<BlokApp>({ baseUrl })`.\n'));
+}

package/dist/commands/gen/appTypes.test.d.ts

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

package/dist/commands/gen/appTypes.test.js

@@ -0,0 +1,116 @@
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildAppTypeSource, extractWorkflowName, generateAppTypes, importSpecifier, nameToIdentifier, } from "./appTypes.js";
+describe("extractWorkflowName", () => {
+    it("extracts the name from a v2 workflow() factory call", () => {
+        const src = `import { workflow } from "@blokjs/helper";
+export default workflow({ name: "users.list", version: "1.0.0", trigger: { http: { method: "GET" } }, steps: [{ id: "s", use: "@blokjs/respond", inputs: {} }] });`;
+        expect(extractWorkflowName(src)).toBe("users.list");
+    });
+    it("handles the legacy Workflow() factory and single quotes", () => {
+        expect(extractWorkflowName("const x = Workflow({ name: 'orders.create' })")).toBe("orders.create");
+    });
+    it("anchors on the factory call, not a step/node `name:`", () => {
+        const src = `export default workflow({
+			name: "the.workflow",
+			steps: [{ id: "x", use: "n", inputs: { name: "not-the-workflow" } }],
+		});`;
+        expect(extractWorkflowName(src)).toBe("the.workflow");
+    });
+    it("ignores a commented-out name", () => {
+        const src = `// name: "commented"
+		/* name: "blocked" */
+		export default workflow({ name: "real.name" });`;
+        expect(extractWorkflowName(src)).toBe("real.name");
+    });
+    it("returns null when there is no workflow factory call", () => {
+        expect(extractWorkflowName(`export const x = { name: "not.a.workflow" };`)).toBeNull();
+    });
+    it("returns null when the name is a non-literal (variable)", () => {
+        expect(extractWorkflowName(`export default workflow({ name: WF_NAME, version: "1" })`)).toBeNull();
+    });
+});
+describe("nameToIdentifier", () => {
+    it("camelCases a dotted name", () => {
+        expect(nameToIdentifier("users.list")).toBe("usersList");
+        expect(nameToIdentifier("a.b.c")).toBe("aBC");
+    });
+    it("passes a single segment through", () => {
+        expect(nameToIdentifier("health")).toBe("health");
+    });
+    it("prefixes identifiers that would start with a digit", () => {
+        expect(nameToIdentifier("2fa.verify")).toBe("wf_2faVerify");
+    });
+});
+describe("importSpecifier", () => {
+    it("computes a relative, extensionless, ./-prefixed specifier", () => {
+        const spec = importSpecifier("/proj/blok-app.d.ts", "/proj/triggers/http/src/workflows/users/list.ts");
+        expect(spec).toBe("./triggers/http/src/workflows/users/list");
+    });
+    it("emits ../ when the workflow is above the output dir", () => {
+        const spec = importSpecifier("/proj/web/blok-app.d.ts", "/proj/server/workflows/health.ts");
+        expect(spec).toBe("../server/workflows/health");
+    });
+});
+describe("buildAppTypeSource", () => {
+    const out = "/proj/blok-app.d.ts";
+    it("nests workflows by their dotted name and imports each by file", () => {
+        const entries = [
+            { name: "users.list", file: "/proj/wf/users/list.ts" },
+            { name: "users.create", file: "/proj/wf/users/create.ts" },
+            { name: "health", file: "/proj/wf/health.ts" },
+        ];
+        const { source, collisions } = buildAppTypeSource(entries, out);
+        expect(collisions).toEqual([]);
+        expect(source).toContain('import type usersList from "./wf/users/list";');
+        expect(source).toContain('import type usersCreate from "./wf/users/create";');
+        expect(source).toContain('import type health from "./wf/health";');
+        expect(source).toContain("export type BlokApp = {");
+        expect(source).toContain("users: {");
+        expect(source).toContain("list: usersList;");
+        expect(source).toContain("create: usersCreate;");
+        expect(source).toContain("health: health;");
+    });
+    it("flags a leaf-vs-group collision and drops the loser", () => {
+        const entries = [
+            { name: "users", file: "/proj/wf/users.ts" },
+            { name: "users.list", file: "/proj/wf/users/list.ts" },
+        ];
+        const { collisions } = buildAppTypeSource(entries, out);
+        expect(collisions.length).toBe(1);
+    });
+    it("quotes non-identifier path segments", () => {
+        const { source } = buildAppTypeSource([{ name: "weird-name.go", file: "/proj/wf/x.ts" }], out);
+        expect(source).toContain('"weird-name":');
+    });
+    it("emits an empty-but-valid type when there are no workflows", () => {
+        const { source } = buildAppTypeSource([], out);
+        expect(source).toContain("export type BlokApp = Record<string, never>;");
+    });
+});
+describe("generateAppTypes (fs integration)", () => {
+    const tmpDirs = [];
+    afterEach(async () => {
+        for (const d of tmpDirs)
+            await fsp.rm(d, { recursive: true, force: true });
+        tmpDirs.length = 0;
+    });
+    it("scans a workflows dir and writes blok-app.d.ts", async () => {
+        const root = await fsp.mkdtemp(path.join(os.tmpdir(), "blok-gen-"));
+        tmpDirs.push(root);
+        const wfDir = path.join(root, "workflows", "users");
+        await fsp.mkdir(wfDir, { recursive: true });
+        await fsp.writeFile(path.join(wfDir, "list.ts"), `import { workflow } from "@blokjs/helper";
+export default workflow({ name: "users.list", version: "1.0.0", trigger: { http: { method: "GET" } }, steps: [] });`);
+        await fsp.writeFile(path.join(root, "workflows", "_helper.ts"), "export const x = 1;");
+        const out = path.join(root, "blok-app.d.ts");
+        await generateAppTypes({ dir: path.join(root, "workflows"), out });
+        const written = await fsp.readFile(out, "utf8");
+        expect(written).toContain("export type BlokApp = {");
+        expect(written).toContain("users: {");
+        expect(written).toContain("list: usersList;");
+        expect(written).toContain('import type usersList from "./workflows/users/list";');
+    });
+});

package/dist/commands/gen/index.d.ts

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

package/dist/commands/gen/index.js

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+import { program } from "../../services/commander.js";
+import { generateAppTypes } from "./appTypes.js";
+const gen = new Command("gen").description("Generate typed client artifacts for @blokjs/client");
+const appTypes = new Command("app-types")
+    .description("Generate the typed `BlokApp` index (blok-app.d.ts) from your TS workflow files")
+    .option("-d, --dir <value>", "TS workflows directory (defaults to triggers/http/src/workflows, src/workflows, or workflows)")
+    .option("-o, --out <value>", "Output file (default: ./blok-app.d.ts)")
+    .option("--dry-run", "Print the generated file without writing it")
+    .action(async (options) => {
+    await generateAppTypes(options);
+});
+gen.addCommand(appTypes);
+program.addCommand(gen);

package/dist/commands/nodes/index.d.ts

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

package/dist/commands/nodes/index.js

@@ -0,0 +1,13 @@
+import { Command } from "commander";
+import { program } from "../../services/commander.js";
+import { listNodes } from "./listNodes.js";
+const nodes = new Command("nodes").description("Inspect the node catalog of a running Blok server");
+const list = new Command("list")
+    .description("List every node across all runtimes (hits GET /__blok/nodes on a running server)")
+    .option("-u, --url <value>", "Base URL of the running Blok server", "http://localhost:4000")
+    .option("--json", "Output raw JSON instead of a table")
+    .action(async (options) => {
+    await listNodes(options);
+});
+nodes.addCommand(list);
+program.addCommand(nodes);

package/dist/commands/nodes/listNodes.d.ts

@@ -0,0 +1,12 @@
+import type { OptionValues } from "commander";
+export interface NodeEntry {
+    name: string;
+    runtime: string;
+    description?: string;
+    inputSchema: unknown | null;
+    outputSchema: unknown | null;
+    tags?: string[];
+}
+export declare function schemaMark(node: NodeEntry): string;
+export declare function formatCatalog(nodes: readonly NodeEntry[]): string;
+export declare function listNodes(opts: OptionValues): Promise<void>;

package/dist/commands/nodes/listNodes.js

@@ -0,0 +1,56 @@
+import color from "picocolors";
+export function schemaMark(node) {
+    const parts = [];
+    if (node.inputSchema)
+        parts.push("in");
+    if (node.outputSchema)
+        parts.push("out");
+    return parts.length > 0 ? parts.join(",") : "—";
+}
+export function formatCatalog(nodes) {
+    if (nodes.length === 0)
+        return "No nodes found.";
+    const rows = nodes.map((n) => ({
+        name: n.name,
+        runtime: n.runtime,
+        schema: schemaMark(n),
+        description: n.description ?? "",
+    }));
+    const nameW = Math.max("NAME".length, ...rows.map((r) => r.name.length));
+    const rtW = Math.max("RUNTIME".length, ...rows.map((r) => r.runtime.length));
+    const schW = Math.max("SCHEMA".length, ...rows.map((r) => r.schema.length));
+    const header = `${"NAME".padEnd(nameW)}  ${"RUNTIME".padEnd(rtW)}  ${"SCHEMA".padEnd(schW)}  DESCRIPTION`;
+    const lines = [header];
+    for (const r of rows) {
+        lines.push(`${r.name.padEnd(nameW)}  ${r.runtime.padEnd(rtW)}  ${r.schema.padEnd(schW)}  ${r.description}`.trimEnd());
+    }
+    return lines.join("\n");
+}
+export async function listNodes(opts) {
+    const baseUrl = (opts.url ?? "http://localhost:4000").replace(/\/+$/, "");
+    const endpoint = `${baseUrl}/__blok/nodes`;
+    let body;
+    try {
+        const res = await fetch(endpoint);
+        if (!res.ok) {
+            console.log(color.red(`❌ ${endpoint} returned HTTP ${res.status}.`));
+            process.exit(1);
+            return;
+        }
+        body = (await res.json());
+    }
+    catch (err) {
+        console.log(color.red(`❌ Could not reach ${color.cyan(endpoint)} — is the Blok server running? ` +
+            `Pass --url <baseUrl> to point elsewhere. (${err.message})`));
+        process.exit(1);
+        return;
+    }
+    const nodes = body.nodes ?? [];
+    if (opts.json === true) {
+        console.log(JSON.stringify(nodes, null, 2));
+        return;
+    }
+    console.log(color.cyan(`\n📦 Node catalog — ${nodes.length} node(s) across runtimes (${baseUrl})\n`));
+    console.log(formatCatalog(nodes));
+    console.log("");
+}

package/dist/commands/nodes/listNodes.test.d.ts

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

package/dist/commands/nodes/listNodes.test.js

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { formatCatalog, listNodes, schemaMark } from "./listNodes.js";
+describe("schemaMark", () => {
+    it("reports which schemas a node exposes", () => {
+        expect(schemaMark({ name: "a", runtime: "module", inputSchema: {}, outputSchema: {} })).toBe("in,out");
+        expect(schemaMark({ name: "a", runtime: "module", inputSchema: {}, outputSchema: null })).toBe("in");
+        expect(schemaMark({ name: "a", runtime: "module", inputSchema: null, outputSchema: {} })).toBe("out");
+        expect(schemaMark({ name: "a", runtime: "module", inputSchema: null, outputSchema: null })).toBe("—");
+    });
+});
+describe("formatCatalog", () => {
+    it("renders an aligned table with a header", () => {
+        const nodes = [
+            {
+                name: "@blokjs/respond",
+                runtime: "module",
+                description: "Shape the HTTP response",
+                inputSchema: {},
+                outputSchema: null,
+            },
+            {
+                name: "@py/search",
+                runtime: "runtime.python3",
+                description: "Semantic search",
+                inputSchema: {},
+                outputSchema: {},
+            },
+        ];
+        const out = formatCatalog(nodes);
+        const lines = out.split("\n");
+        expect(lines[0]).toMatch(/^NAME\s+RUNTIME\s+SCHEMA\s+DESCRIPTION$/);
+        expect(out).toContain("@blokjs/respond");
+        expect(out).toContain("runtime.python3");
+        expect(out).toContain("in,out");
+        expect(out).toContain("Semantic search");
+        const rtOffset = lines[0].indexOf("RUNTIME");
+        expect(lines[1].slice(rtOffset, rtOffset + 6)).toBe("module");
+    });
+    it("handles an empty catalog", () => {
+        expect(formatCatalog([])).toBe("No nodes found.");
+    });
+});
+describe("listNodes (fetch-mocked)", () => {
+    const realFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = realFetch;
+        vi.restoreAllMocks();
+    });
+    it("fetches /__blok/nodes from the given --url and prints the table", async () => {
+        let seenUrl = "";
+        globalThis.fetch = vi.fn(async (url) => {
+            seenUrl = String(url);
+            return new Response(JSON.stringify({ count: 1, nodes: [{ name: "@x/a", runtime: "module", inputSchema: {}, outputSchema: null }] }), { status: 200, headers: { "content-type": "application/json" } });
+        });
+        const log = vi.spyOn(console, "log").mockImplementation(() => { });
+        await listNodes({ url: "https://api.test/" });
+        expect(seenUrl).toBe("https://api.test/__blok/nodes");
+        const printed = log.mock.calls.map((c) => String(c[0])).join("\n");
+        expect(printed).toContain("@x/a");
+        expect(printed).toContain("1 node(s)");
+    });
+    it("emits raw JSON with --json", async () => {
+        globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({ nodes: [{ name: "@x/a", runtime: "module", inputSchema: null, outputSchema: null }] }), {
+            status: 200,
+            headers: { "content-type": "application/json" },
+        }));
+        const log = vi.spyOn(console, "log").mockImplementation(() => { });
+        await listNodes({ url: "http://localhost:4000", json: true });
+        const printed = log.mock.calls.map((c) => String(c[0])).join("\n");
+        expect(JSON.parse(printed)).toEqual([{ name: "@x/a", runtime: "module", inputSchema: null, outputSchema: null }]);
+    });
+});

package/dist/index.d.ts

@@ -8,6 +8,8 @@ import "./commands/publish/index.js";
 import "./commands/install/index.js";
 import "./commands/search/index.js";
 import "./commands/generate/index.js";
+import "./commands/gen/index.js";
+import "./commands/nodes/index.js";
 import "./commands/config/index.js";
 import "./commands/migrate/index.js";
 import "./commands/graph/index.js";

package/dist/index.js

@@ -23,6 +23,8 @@ import "./commands/publish/index.js";
 import "./commands/install/index.js";
 import "./commands/search/index.js";
 import "./commands/generate/index.js";
+import "./commands/gen/index.js";
+import "./commands/nodes/index.js";
 import "./commands/config/index.js";
 import "./commands/migrate/index.js";
 import "./commands/graph/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "blokctl",
-	"version": "0.6.16",
+	"version": "0.6.18",
 	"author": "Deskree Technologies Inc.",
 	"license": "Apache-2.0",
 	"description": "cli for blok",
@@ -30,7 +30,7 @@
 	"keywords": ["blokctl", "cli", "blok", "blok"],
 	"dependencies": {
 		"@ai-sdk/openai": "^1.3.22",
-		"@blokjs/runner": "^0.6.16",
+		"@blokjs/runner": "^0.6.18",
 		"@clack/prompts": "^1.0.0",
 		"ai": "^4.3.16",
 		"better-sqlite3": "^12.6.2",