lua-cli 3.35.0 → 3.37.0

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.35.0
+# lua-cli v3.37.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.35.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.37.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 

package/docs/api/Workflows.md

@@ -15,7 +15,7 @@ Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is als
 - `start` **never awaits execution** — it returns `{ runId, status }` immediately. `waitSeconds` (≤ 55) asks the server to hold the response for early terminal state; it changes the response, never the execution model.
 - Runs are idempotent on `idempotencyKey` — re-sending the same key returns the existing run instead of a duplicate.
 - A workflow with `concurrencyPolicy: 'forbid'` refuses a second start while one is in flight with a thrown `WorkflowApiError { code: 'RUNS_IN_FLIGHT', blockingRunId }` — never a 429, never a gate.
-- `status: 'gated'` means the run is parked (quota, billing or consent) and holds no slot. Consent gates are cleared from the desktop or with `lua workflows approve`.
+- `status: 'gated'` means the run is parked (quota, billing or consent) and holds no slot. A **consent** gate is cleared by a person resolving its approval — from the desktop, or through the approvals API / inbox. `lua workflows approve` cannot clear one: it requires an `--approval wfa_…` id, which belongs to a workflow `approval` node, and a consent gate has no such id. `lua workflows status <runId>` reports a gated run, and exits 6 under `--strict`.
 - `nameOrId` resolves the workflow **name on the calling agent first**, then a workflow id.
 - `get` / `list` honour output visibility: a restricted run comes back with `restricted: true` and no `output` — never an error.
 - From a workflow code step, `Workflows.start` creates a **detached** run (no parent link). Use the `.workflow(...)` builder node when the parent should wait.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -114,9 +114,9 @@
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "@lua/sandbox-runtime": "0.0.1",
-    "@lua/shared-sandbox": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
     "@lua/shared-types": "0.0.1",
+    "@lua/shared-sandbox": "0.0.1",
     "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {
@@ -128,6 +128,7 @@
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "test": "node ../../scripts/test-gate.mjs jest",
     "test:watch": "jest --watch",
-    "test:coverage": "node ../../scripts/test-gate.mjs jest --coverage"
+    "test:coverage": "node ../../scripts/test-gate.mjs jest --coverage",
+    "test:compat-matrix": "node scripts/compat-matrix-previous-cli.mjs"
   }
 }

package/scripts/compat-matrix-previous-cli.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * [WMC-E7] The CLI compatibility matrix's real leg (plan §6.9, "Older CLIs keep working").
+ *
+ * Installs the PREVIOUS MINOR RELEASE of this CLI from npm into a temporary directory and drives it, as a
+ * child process, against the mock API in `tests/helpers/workflow-compat-server.mjs`. It runs the matrix
+ * twice: once against a server serving definitions and runs WITHOUT any of the per-step model-selection
+ * fields, and once WITH all of them, including the run-event types the older CLI has never heard of.
+ *
+ * The verbs exercised are the three §6.9 names: **push**, **view** and **watch**.
+ *
+ * ── Safety ────────────────────────────────────────────────────────────────
+ * Nothing here touches a real account or a real agent. The child CLI is pointed at `127.0.0.1` through
+ * `LUA_API_URL` and given a throwaway `LUA_API_KEY`, so there is no `lua auth`, no production host and no
+ * production verb against anything that exists. The temp directory is removed on the way out.
+ *
+ * ── Why it is gated ───────────────────────────────────────────────────────
+ * It needs the npm registry. Every property it proves is also asserted offline in
+ * `tests/__tests__/workflows.compat-matrix.test.ts`, which runs on every PR; this leg is the end-to-end
+ * confirmation and belongs in the nightly job and on demand:
+ *
+ *     pnpm --filter lua-cli test:compat-matrix
+ *     LUA_COMPAT_MATRIX_VERSION=3.33.0 pnpm --filter lua-cli test:compat-matrix
+ *
+ * Exit 0 = the previous release coped with both halves. Non-zero names the leg that failed.
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_ID, RUN_ID, WORKFLOW_ID, startCompatServer } from '../tests/helpers/workflow-compat-server.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(fs.readFileSync(path.join(HERE, '..', 'package.json'), 'utf8'));
+
+/** The previous MINOR of the version in package.json — 3.34.x ⇒ 3.33.0 — unless one is named. */
+function previousMinor(current) {
+  const [major, minor] = current.split('.').map(Number);
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) throw new Error(`cannot read a version from "${current}"`);
+  if (minor === 0) throw new Error(`no previous minor for ${current} — name one with LUA_COMPAT_MATRIX_VERSION`);
+  return `${major}.${minor - 1}.0`;
+}
+
+const TARGET = process.env.LUA_COMPAT_MATRIX_VERSION || previousMinor(PKG.version);
+
+function say(msg) {
+  process.stdout.write(`${msg}\n`);
+}
+
+/**
+ * Run the installed previous CLI with the mock API as its whole world.
+ *
+ * ASYNC on purpose. `spawnSync` blocks this process's event loop, and the mock API runs in this process —
+ * so a synchronous spawn freezes the server and every request the child makes hangs until the child is
+ * killed on its timeout. That failure looks exactly like a compatibility failure (empty output, no requests
+ * recorded) and is not one, which is why the harness records the signal as well as the exit code below.
+ */
+function runOldCli(cliEntry, cwd, baseUrl, args, { timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [cliEntry, ...args], {
+      cwd,
+      // stdin CLOSED, not inherited: an open pipe leaves any interactive prompt waiting for ever.
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        LUA_API_URL: baseUrl,
+        LUA_AUTH_URL: baseUrl,
+        LUA_API_KEY: 'compat-matrix-not-a-real-key',
+        // Keep the child from phoning home for an update check or writing analytics during the matrix.
+        LUA_DISABLE_ANALYTICS: '1',
+        LUA_SKIP_UPDATE_CHECK: '1',
+        CI: '1',
+        NO_COLOR: '1',
+      },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (c) => (stdout += c));
+    child.stderr.on('data', (c) => (stderr += c));
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ status: null, signal: null, stdout, stderr, error });
+    });
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      resolve({ status, signal, stdout, stderr });
+    });
+  });
+}
+
+/** One half of the matrix: a server serving old-only or new-bearing shapes, and the three verbs against it. */
+async function runLeg({ withNewFields, cliEntry, projectDir }) {
+  const label = withNewFields ? 'WITH the new fields' : 'WITHOUT the new fields';
+  const server = await startCompatServer({ withNewFields });
+  const failures = [];
+  try {
+    const checks = [
+      { verb: 'view', args: ['workflows', 'view', 'compat', '--json'] },
+      { verb: 'list', args: ['workflows', 'list', '--json'] },
+      { verb: 'status', args: ['workflows', 'status', RUN_ID, '--steps', '--json'] },
+      // `watch` must reach the terminal frame and exit 0 even with event types it does not know.
+      { verb: 'watch', args: ['workflows', 'watch', RUN_ID, '--timeout', '20'] },
+      // The push half of §6.9: the old client compiles its own source and sends a body with none of the new
+      // members. `compile` is part of it on purpose — a push body an older CLI cannot even BUILD is the same
+      // failure as one the server rejects.
+      { verb: 'compile', args: ['compile', '--ci'] },
+      { verb: 'push', args: ['push', 'workflow', '--force'] },
+    ];
+    for (const { verb, args } of checks) {
+      const out = await runOldCli(cliEntry, projectDir, server.baseUrl, args);
+      const ok = out.status === 0;
+      say(
+        `  ${ok ? '✓' : '✗'} ${TARGET} · ${verb} · ${label}${ok ? '' : ` (${out.status === null ? `signal ${out.signal}` : `exit ${out.status}`})`}`
+      );
+      if (!ok) {
+        // `status: null` means the child never exited on its own — name the signal and the spawn error, or the
+        // failure is indistinguishable from a real incompatibility.
+        const how = out.status === null ? `killed by ${out.signal ?? 'an unknown signal'}` : `exit ${out.status}`;
+        failures.push(`${verb} (${label}) ${how}`);
+        if (out.error) say(`      spawn error: ${out.error.message}`);
+        say(`      stdout: ${(out.stdout || '').trim().slice(0, 2500)}`);
+        say(`      stderr: ${(out.stderr || '').trim().slice(0, 2500)}`);
+        say(`      routes: ${server.requests.join(' | ')}`);
+      }
+    }
+    // A leg that asked the server for nothing proves nothing — the "No tests found" failure mode.
+    if (server.requests.length === 0) failures.push(`${label}: the old CLI made no requests at all`);
+
+    // The push must have actually reached the version route, and what it sent is the thing under test:
+    // a body an older CLI builds carries NONE of the new members and leaves the envelope marker at 1.
+    if (server.pushed.length === 0) {
+      failures.push(`${label}: the old CLI never sent a version body`);
+    } else {
+      for (const body of server.pushed) {
+        const marker = body?.graph?.luaWorkflow;
+        if (marker !== 1) failures.push(`${label}: the old CLI sent luaWorkflow ${marker}, expected 1`);
+        const nodes = body?.graph?.definition?.graph ?? [];
+        const leaked = JSON.stringify(nodes).match(/"(taskClass|requires|modelReason|effort)"/g);
+        if (leaked) failures.push(`${label}: the old CLI's body carried ${[...new Set(leaked)].join(', ')}`);
+        say(`  ✓ ${TARGET} · push body · ${label} · luaWorkflow ${marker}, no new members`);
+      }
+    }
+  } finally {
+    await server.close();
+  }
+  return failures;
+}
+
+async function main() {
+  say(`\n🧭 CLI compatibility matrix — driving lua-cli@${TARGET} against the current shapes\n`);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lua-compat-'));
+  const failures = [];
+  try {
+    // 1. Install the previous release into a scratch directory of its own.
+    say(`  … installing lua-cli@${TARGET} into ${tmp}`);
+    fs.writeFileSync(path.join(tmp, 'package.json'), JSON.stringify({ name: 'compat-host', private: true }), 'utf8');
+    execFileSync('npm', ['install', '--no-audit', '--no-fund', '--silent', `lua-cli@${TARGET}`], {
+      cwd: tmp,
+      stdio: 'inherit',
+      timeout: 300_000,
+    });
+    const cliEntry = path.join(tmp, 'node_modules', 'lua-cli', 'dist', 'index.js');
+    if (!fs.existsSync(cliEntry)) throw new Error(`installed lua-cli@${TARGET} has no dist/index.js at ${cliEntry}`);
+
+    // 2. A project directory the old CLI recognises. No credential file: the key rides the environment.
+    const projectDir = path.join(tmp, 'project');
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, 'lua.skill.yaml'),
+      [
+        'agent:',
+        `  agentId: ${AGENT_ID}`,
+        '  orgId: org_compat',
+        '  name: compat',
+        'workflows:',
+        '  - name: compat',
+        `    workflowId: ${WORKFLOW_ID}`,
+        '    version: 1.0.0',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+    // A project the OLD CLI can compile: nothing in it uses anything this change added, which is the point.
+    fs.mkdirSync(path.join(projectDir, 'src', 'workflows'), { recursive: true });
+    fs.writeFileSync(
+      path.join(projectDir, 'package.json'),
+      JSON.stringify({ name: 'compat', private: true, type: 'module', dependencies: { 'lua-cli': TARGET } }, null, 2),
+      'utf8'
+    );
+    fs.symlinkSync(path.join(tmp, 'node_modules'), path.join(projectDir, 'node_modules'), 'dir');
+    fs.writeFileSync(
+      path.join(projectDir, 'tsconfig.json'),
+      JSON.stringify(
+        {
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            strict: true,
+            skipLibCheck: true,
+            esModuleInterop: true,
+            outDir: 'dist',
+          },
+          include: ['src/**/*'],
+        },
+        null,
+        2
+      ),
+      'utf8'
+    );
+    fs.writeFileSync(
+      path.join(projectDir, 'src', 'workflows', 'compat.ts'),
+      [
+        "import { createWorkflow } from 'lua-cli';",
+        "import { z } from 'zod';",
+        '',
+        'export const compat = createWorkflow({',
+        "  name: 'compat',",
+        "  description: 'compatibility matrix fixture',",
+        '  inputSchema: z.object({}),',
+        '  outputSchema: z.object({ text: z.string() }),',
+        '})',
+        "  .agentStep('summarise', { agentId: '$self', toolScope: {}, prompt: 'hi' })",
+        '  .commit();',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+    fs.writeFileSync(
+      path.join(projectDir, 'src', 'index.ts'),
+      [
+        "import { LuaAgent } from 'lua-cli';",
+        "import { compat } from './workflows/compat';",
+        '',
+        'export default new LuaAgent({',
+        "  name: 'compat',",
+        "  persona: 'compatibility matrix fixture',",
+        '  workflows: [compat],',
+        '});',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+
+    // 3. Both halves.
+    for (const withNewFields of [false, true]) {
+      failures.push(...(await runLeg({ withNewFields, cliEntry, projectDir })));
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+
+  if (failures.length) {
+    say(`\n✗ compatibility matrix: ${failures.length} failure(s)`);
+    for (const f of failures) say(`   • ${f}`);
+    process.exit(1);
+  }
+  say(`\n✓ compatibility matrix: lua-cli@${TARGET} pushes, views and watches against the current shapes.\n`);
+}
+
+main().catch((err) => {
+  process.stderr.write(`compatibility matrix failed to run: ${err?.stack || err}\n`);
+  process.exit(1);
+});

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.35.0",
+    "lua-cli": "^3.37.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"