lua-cli 3.31.0 → 3.32.2

package/template/examples/workflows/ticket-to-pr.ts

@@ -1,5 +1,8 @@
-// Linear label -> clone -> parallel worktree arms -> merge -> tests -> PR -> review loop -> approval -> merge.
-// Verbatim from workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative).
+// Linear label -> clone -> parallel worktree arms -> merge -> tests -> PR (coding turn) -> review loop -> approval -> the decision (the merge stays human).
+// From workflows-spec 03 §3.2 (f) (WF-215 / WF-223 — the spec is normative). LUA-635: `openPr` is placed by `.then(openPr)` on
+// both test outcomes — the listing's `otherwise: 'openPr'` named a `.then(createStep)` placement, which never declares an id
+// (03 §3.2.0); a string arm names an agentStep / specialistStep / toolStep / map / workflow declaration. `mergeGate.title` is a
+// plain string — the grammar is `title: string` (03 §3.1) and bindings ride `details`.
 // src/workflows/ticket-to-pr.ts — Linear label → clone → parallel worktree arms → merge → test suite → PR → review loop → approval → merge
 import { z } from 'zod';
 import { createStep, createWorkflow, step, fromInit, fromStep, template, eq, lit } from 'lua-cli';
@@ -7,59 +10,135 @@ import { prReviewRound } from './pr-review-round';
 
 const runTests = createStep({
   id: 'runTests',
-  inputSchema: z.any(), outputSchema: z.object({ passed: z.boolean(), summary: z.string() }),
-  tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 3600, jobResources: 'large',   // a 15–40 min monorepo suite fits one 4 h segment (D19-r1); up to 86 400 s is legal since D19-r2 — see §3.2 (h) for a step that crosses the segment boundary
-  async execute({ workspace, log }) {
-    const r = await $`cd ${workspace!.path} && npm ci && npm test -- --maxWorkers=2`.nothrow();   // untracked node_modules were rebuilt on restore (05 §5.17.5, E12); `--maxWorkers=2` keeps a mongodb-memory-server-per-file suite inside `large`'s 8 GiB — over it the container is OOM-killed and the step fails `job_oom_killed` (customer fault, 05 §5.17.4; §3.12 note)
+  inputSchema: z.any(),
+  outputSchema: z.object({ passed: z.boolean(), summary: z.string() }),
+  tier: 'job',
+  workspace: { mount: 'rw' },
+  timeoutSeconds: 3600,
+  jobResources: 'large', // a 15–40 min monorepo suite fits one 4 h segment (D19-r1); up to 86 400 s is legal since D19-r2 — see §3.2 (h) for a step that crosses the segment boundary
+  async execute({ $, log }) {
+    // `ctx.$` runs ONE allow-listed binary per call, argv only, in the checkout (LUA-682): no `cd`, no `&&` — the
+    // cwd is the workspace root and a second command is a second call. `.strict` throws on a non-zero exit; the
+    // plain form returns it, which is what a test run wants.
+    await $!.strict`npm ci`; // untracked node_modules were rebuilt on restore (05 §5.17.5, E12)
+    const r = await $!`npm test -- --maxWorkers=2`; // `--maxWorkers=2` keeps a mongodb-memory-server-per-file suite inside `large`'s 8 GiB — over it the container is OOM-killed and the step fails `job_oom_killed` (customer fault, 05 §5.17.4; §3.12 note)
     log(r.stdout.slice(-4000));
-    return { passed: r.exitCode === 0, summary: r.stdout.slice(-2000) };
+    return { passed: r.code === 0, summary: r.stdout.slice(-2000) };
   },
 });
 
-const openPr = createStep({
-  id: 'openPr',
-  inputSchema: z.object({ ticketId: z.string(), title: z.string() }), outputSchema: z.object({ prNumber: z.number(), url: z.string() }),
-  tier: 'job', workspace: { mount: 'ro' },
-  sideEffects: 'external', onError: 'park',                                                 // a PR is an external effect: a platform fault PARKS (06 §6.3.5); `gh` is idempotent on the branch anyway
-  async execute({ workspace, inputData, runId }) {
-    const out = await $`cd ${workspace!.path} && gh pr create --fill --title ${inputData.title} --body ${`Closes ${inputData.ticketId}\n\n<!-- lua-run:${runId} -->`}`;   // the run id in the PR body is what the GitHub webhook uses to route review signals (§3.7)
-    const url = out.stdout.trim(); return { prNumber: Number(url.split('/').pop()), url };
-  },
-});
+// `openPr` is a CODING TURN (05 §5.17.6) — the pilot's real pattern: the harness's own `gh` tool talks to the sidecar's
+// gh proxy. A Job-tier code step can run `gh` too (`ctx.$`, with `jobTools:['gh']` on the step), but the proxy admits
+// `gh pr create` / `gh pr edit` / `gh pr comment` on the pinned repo only — no merge, no /graphql (T17-D-SE25) — and the
+// end-to-end path is the sidecar's to prove; the coding turn is what ships PRs today.
 
-const mergePr = createStep({
-  id: 'mergePr', inputSchema: z.object({ approved: z.boolean(), input: z.object({ prNumber: z.number() }) }), outputSchema: z.object({ merged: z.boolean() }),
-  tier: 'job', workspace: { mount: 'ro' }, jobTools: ['gh'], sideEffects: 'external', onError: 'park',   // `jobTools:['gh']` is what mints GH_TOKEN for a code step (11 §11.5.6: pull_requests:write + contents:write + issues:read, repo-scoped — merge is a contents write on GitHub)
-  async execute({ workspace, inputData }) {
-    if (!inputData.approved) return { merged: false };
-    await $`cd ${workspace!.path} && gh pr merge ${inputData.input.prNumber} --squash --delete-branch`;   // succeeds only if the base branch's ruleset lets the App merge — human-only-merge orgs keep contents:write off the App (11 T21)
-    return { merged: true };
+const recordDecision = createStep({
+  id: 'recordDecision',
+  inputSchema: z.object({ approved: z.boolean(), prNumber: z.number() }), // projected by the `mergeInput` map below — an approval's output carries `approved` (and `decidedBy`, `editRevision`…), never the payload it was shown (docs/workflows/approvals.md), so the PR number is read back from `openPr`
+  outputSchema: z.object({ approved: z.boolean(), prNumber: z.number(), merged: z.boolean() }),
+  async execute({ inputData, log }) {
+    // The merge itself stays with a person: `gh pr merge` is refused by the sidecar BY DESIGN (a contents write; human-only-merge
+    // orgs keep contents:write off the App, 11 T21), so the workflow ends at the decision — `merged` is always false here and
+    // the approver merges when ready.
+    log(
+      inputData.approved
+        ? `PR #${inputData.prNumber} approved — merge when ready`
+        : `PR #${inputData.prNumber} not approved`
+    );
+    return { approved: inputData.approved, prNumber: inputData.prNumber, merged: false };
   },
 });
 
 export const ticketToPr = createWorkflow({
   name: 'ticket-to-pr',
-  description: 'Linear label → implement/tests/docs in parallel worktrees → merge → test suite → PR → review rounds → approval → merge',
-  inputSchema: z.object({ ticketId: z.string(), title: z.string(), spec: z.string(), repo: z.string(), baseRef: z.string().default('main') }),
-  outputSchema: z.object({ merged: z.boolean(), prUrl: z.string().optional(), rounds: z.number() }),
-  workspace: { kind: 'git', repo: template('${initData.repo}'), ref: template('${initData.baseRef}'), credentialsRef: 'github-app', sizeGb: 20, verify: 'npm test' },   // `github-app` = the org's GitHub connection id (a template would use `connections[].key`, §13 §13.3.3)
-  budget: { maxCredits: 400, maxDurationSeconds: 21 * 24 * 3600 },                         // review rounds may wait a week each. Job seconds (wall, claim → terminal) worst case: 7200+5400+1800 arms + 3600 merge + 3600 tests + 3600 fixTests + 3600 openPr + 8 × (7200+600) rounds + 3600 merge ≈ 94 800 s — fits the org default maxJobSecondsPerRun 172 800 (48 h) with margin; the push-time `job-seconds-exceed-cap` BLOCKER (10 §10.7.6) refuses this file on an org that lowered the cap below the sum, and prints the R23 raise path. Declare `maxJobSeconds` explicitly only to narrow.
+  description:
+    'Linear label → implement/tests/docs in parallel worktrees → merge → test suite → PR → review rounds → approval → decision (a human merges)',
+  inputSchema: z.object({
+    ticketId: z.string(),
+    title: z.string(),
+    spec: z.string(),
+    repo: z.string(),
+    baseRef: z.string().default('main'),
+  }),
+  outputSchema: z.object({ approved: z.boolean(), prNumber: z.number(), merged: z.boolean() }), // the decision; the merge is a human act (see `recordDecision`)
+  connections: [{ key: 'github', integrationType: 'github', required: true }], // the GitHub connection this workflow acts through, declared ONCE by key — resolved on the owner agent at run time (an agent-scoped GitHub connection first, then org-scoped; LUA-623), so the same definition runs on any agent: no frozen connection id in source, no per-agent build
+  workspace: {
+    kind: 'git',
+    repo: template('${initData.repo}'),
+    ref: template('${initData.baseRef}'),
+    credentialsRef: 'github',
+    sizeGb: 20,
+    verify: 'npm test',
+  }, // `credentialsRef` names the declared key above; an undeclared key fails `lua compile` / `lua push` with connection-key-undeclared
+  budget: { maxCredits: 400, maxDurationSeconds: 21 * 24 * 3600 }, // review rounds may wait a week each. Job seconds (wall, claim → terminal) worst case: 7200+5400+1800 arms + 3600 merge + 3600 tests + 3600 fixTests + 3600 openPr + 8 × (7200+600) rounds + 3600 merge ≈ 94 800 s — fits the org default maxJobSecondsPerRun 172 800 (48 h) with margin; the push-time `job-seconds-exceed-cap` BLOCKER (10 §10.7.6) refuses this file on an org that lowered the cap below the sum, and prints the R23 raise path. Declare `maxJobSeconds` explicitly only to narrow.
 })
-  .parallel(['implement', 'writeTests', 'updateDocs'], { merge: { strategy: 'rebase', onConflict: 'agent' } })   // three coding turns on three clone volumes + branches; the merge row rebases them onto the run branch and lets one resolver turn fix conflicts (05 §5.17.5)
-  .agentStep('implement', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 7200,
-    prompt: template('Implement ${initData.spec} for ticket ${initData.ticketId}. Do not touch tests or docs; commit as you go.'),
-    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] } })
-  .agentStep('writeTests', { agentId: 'swe-tester', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 5400,
-    prompt: template('Write tests for the behaviour described in ${initData.spec}; they may fail until implementation lands. Only touch test files.') })
-  .agentStep('updateDocs', { agentId: 'swe-writer', tier: 'job', workspace: { mount: 'rw', isolation: 'worktree' }, timeoutSeconds: 1800, jobResources: 'small',
-    prompt: template('Update docs/ for ${initData.spec}. Only touch markdown files.') })
-  .then(runTests)                                                                          // shared mount, sequential — the merged run branch
-  .switch([[eq(step('runTests').path('passed'), lit(false)), 'fixTests']], 'openPr')
-  .agentStep('fixTests', { agentId: 'swe-implementer', tier: 'job', workspace: { mount: 'rw' }, timeoutSeconds: 3600,
-    prompt: template('The test suite failed:\n${stepResults.runTests.summary}\nFix the code (not the tests unless they are wrong) and re-run `npm test` until green.') })
-  .then(openPr)
-  .dowhile('reviewRound', eq(step('reviewRound').path('state'), lit('changes_requested')), { maxIterations: 8 })   // ≤ 8 review rounds (the SWE_REVIEW_MAX_ROUNDS lesson)
-  .workflow('reviewRound', prReviewRound, { prNumber: fromStep('openPr', 'prNumber'), repo: fromInit('repo') }, { workspace: 'inherit' })   // each round is a child run on the SAME workspace; the parent's PVC is released while a round waits for the webhook (E12)
-  .approval('mergeGate', { title: template('Merge PR ${stepResults.openPr.url}?'), approver: { role: 'eng-lead' }, excludeInitiator: true, timeoutHours: 72, onTimeout: 'deny' })
-  .then(mergePr)
+  .parallel(['implement', 'writeTests', 'updateDocs'], { merge: { strategy: 'rebase', onConflict: 'agent' } }) // three coding turns on three clone volumes + branches; the merge row rebases them onto the run branch and lets one resolver turn fix conflicts (05 §5.17.5)
+  .agentStep('implement', {
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'rw', isolation: 'worktree' },
+    timeoutSeconds: 7200,
+    prompt: template(
+      'Implement ${initData.spec} for ticket ${initData.ticketId}. Do not touch tests or docs; commit as you go.'
+    ),
+    toolScope: { jobTools: ['shell', 'read', 'write', 'edit', 'glob', 'grep', 'git'] },
+  })
+  .agentStep('writeTests', {
+    agentId: 'swe-tester',
+    tier: 'job',
+    workspace: { mount: 'rw', isolation: 'worktree' },
+    timeoutSeconds: 5400,
+    prompt: template(
+      'Write tests for the behaviour described in ${initData.spec}; they may fail until implementation lands. Only touch test files.'
+    ),
+  })
+  .agentStep('updateDocs', {
+    agentId: 'swe-writer',
+    tier: 'job',
+    workspace: { mount: 'rw', isolation: 'worktree' },
+    timeoutSeconds: 1800,
+    jobResources: 'small',
+    prompt: template('Update docs/ for ${initData.spec}. Only touch markdown files.'),
+  })
+  .then(runTests) // shared mount, sequential — the merged run branch
+  .switch([[eq(step('runTests').path('passed'), lit(false)), 'fixTests']]) // red ⇒ one fix turn (placed inside this arm by the string ref below); green falls through — no `otherwise`, `openPr` follows either way
+  .agentStep('fixTests', {
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'rw' },
+    timeoutSeconds: 3600,
+    prompt: template(
+      'The test suite failed:\n${stepResults.runTests.summary}\nFix the code (not the tests unless they are wrong) and re-run `npm test` until green.'
+    ),
+  })
+  .agentStep('openPr', {
+    // a CODING TURN with `gh` (05 §5.17.6): opens the PR from the run branch and reports it as typed output
+    agentId: 'swe-implementer',
+    tier: 'job',
+    workspace: { mount: 'ro' },
+    timeoutSeconds: 600,
+    jobResources: 'small',
+    prompt: template(
+      'Open a pull request from the current branch against ${initData.baseRef} for ticket ${initData.ticketId}, titled "${initData.title}". Put the marker the harness gives you for this run in the PR body (the GitHub webhook routes review signals by it). Reply with the PR number and URL.'
+    ),
+    toolScope: { jobTools: ['gh', 'git', 'read', 'glob', 'grep'] }, // `gh` here is the harness's tool through the sidecar's gh proxy (create / edit / comment on this repo only)
+    outputSchema: z.object({ prNumber: z.number(), url: z.string() }),
+  })
+  .dowhile('reviewRound', eq(step('reviewRound').path('state'), lit('changes_requested')), { maxIterations: 8 }) // ≤ 8 review rounds (the SWE_REVIEW_MAX_ROUNDS lesson)
+  .workflow(
+    'reviewRound',
+    prReviewRound,
+    { prNumber: fromStep('openPr', 'prNumber'), repo: fromInit('repo') },
+    { workspace: 'inherit' }
+  ) // declared here, placed as the loop body by the string ref above; each round is a child run on the SAME workspace; the parent's PVC is released while a round waits for the webhook (E12)
+  .approval('mergeGate', {
+    title: 'Merge the PR?',
+    details: template('Merge ${stepResults.openPr.url} into ${initData.baseRef}?'),
+    approver: { role: 'eng-lead' },
+    excludeInitiator: true,
+    timeoutHours: 72,
+    onTimeout: 'deny',
+  })
+  .map({ approved: fromStep('mergeGate', 'approved'), prNumber: fromStep('openPr', 'prNumber') }, { id: 'mergeInput' }) // a `.then(step)` receives the PREVIOUS node's output — the approval's, which has `approved` but not the PR number — so the fields `recordDecision` declares are projected explicitly; without this map the row fails `input_schema_invalid` before dispatch (LUA-679, found by the LUA-669 builder)
+  .then(recordDecision)
   .commit();

package/template/examples/workflows/vendor-invoices.ts

@@ -1,30 +1,83 @@
 // Per-item review with an env overlay, a restricted output pane and a slack reply (Cluster K).
-// Verbatim from workflows-spec 03 §3.2 (j) (WF-215 / WF-223 — the spec is normative).
+// From workflows-spec 03 §3.2 (j) (WF-215 / WF-223 — the spec is normative). LUA-635: the approval `title` is a plain string
+// (03 §3.1 `approval(id, { title: string; details?: TemplateBinding })`); the listing's `template(…)` title moved into `details`.
+// The listing's `.foreach('pay', 'payInvoice', …)` is not the builder's `foreach(step, opts)` (03 §3.1) and declared no `payInvoice`
+// anywhere — the body is the `payInvoice` code step below.
 import { z } from 'zod';
 import { createStep, createWorkflow, env, fromInit, fromKnowledge, fromStep, template } from 'lua-cli';
 
-const invoiceSchema = z.object({ vendorId: z.string(), approverEmail: z.string().email(), amount: z.number(), pdf: z.object({ __artefactRef: z.string() }) });
+const invoiceSchema = z.object({
+  vendorId: z.string(),
+  approverEmail: z.string().email(),
+  amount: z.number(),
+  pdf: z.object({ __artefactRef: z.string() }),
+});
 
-const loadInvoices = createStep({ id: 'loadInvoices', inputSchema: z.object({ batchId: z.string() }), outputSchema: z.object({ invoices: z.array(invoiceSchema) }),
+const loadInvoices = createStep({
+  id: 'loadInvoices',
+  inputSchema: z.object({ batchId: z.string() }),
+  outputSchema: z.object({ invoices: z.array(invoiceSchema) }),
   async execute(ctx) {
-    const src = await ctx.artefacts.get(ctx.inputData.batchId);                                   // B40: a multi-GB NDJSON batch — page it, never buffer it
-    const invoices = []; for (let offset = 0; ; offset += 1000) { const page = await src.rows({ offset, limit: 1000 }); invoices.push(...page.rows); if (page.nextOffset == null) break; }
+    const src = await ctx.artefacts.get(ctx.inputData.batchId); // B40: a multi-GB NDJSON batch — page it, never buffer it
+    const invoices = [];
+    for (let offset = 0; ; offset += 1000) {
+      const page = await src.rows({ offset, limit: 1000 });
+      invoices.push(...page.rows);
+      if (page.nextOffset == null) break;
+    }
     return { invoices };
-  } });
+  },
+});
+
+const payInvoice = createStep({
+  id: 'payInvoice',
+  inputSchema: invoiceSchema,
+  outputSchema: z.object({ vendorId: z.string(), paid: z.boolean() }),
+  sideEffects: 'external',
+  onError: 'park', // a payment is an external effect: a platform-fault reclaim PARKS it, never auto-retries (06 §6.3.5)
+  async execute({ inputData: inv, once }) {
+    // one approved row per iteration — the foreach body receives the raw item
+    await once(`pay:${inv.vendorId}:${inv.amount}`, () =>
+      Payments.transfer({ vendorId: inv.vendorId, amount: inv.amount })
+    ); // exactly-once per {occurrenceId, key}; `Payments` stands for your payment rail
+    return { vendorId: inv.vendorId, paid: true };
+  },
+});
 
 export const vendorInvoices = createWorkflow({
-  name: 'vendor-invoices', inputSchema: z.object({ batchId: z.string() }),
-  outputVisibility: { roles: ['finance', 'org-admin'] },                                          // B44: invoice payloads are readable by finance only; owner bypass on (default)
-  schedule: { cron: '0 6 * * 1-5', timezone: env.template('FINANCE_TZ') },                        // B33: one file, per-env timezone resolved at push
+  name: 'vendor-invoices',
+  inputSchema: z.object({ batchId: z.string() }),
+  outputVisibility: { roles: ['finance', 'org-admin'] }, // B44: invoice payloads are readable by finance only; owner bypass on (default)
+  schedule: { cron: '0 6 * * 1-5', timezone: env.template('FINANCE_TZ') }, // B33: one file, per-env timezone resolved at push
+  scheduleInput: { batchId: 'latest' }, // the 06:00 run reads the standing `latest` batch alias; a required input without a `scheduleInput` is `schedule-input-required`, a publish blocker. An ad-hoc run passes its own batch id
 })
   .then(loadInvoices, { batchId: fromInit('batchId') })
-  .agentStep('policyCheck', { agentId: env.template('FINANCE_AGENT_ID'),                          // B33: staging and prod route to different sub-agents; same graphHash
+  .agentStep('policyCheck', {
+    agentId: env.template('FINANCE_AGENT_ID'), // B33: staging and prod route to different sub-agents; same graphHash
     prompt: template('Flag any invoice that breaks policy.\n${knowledge.policy}\n${stepResults.loadInvoices.invoices}'),
     outputSchema: z.object({ flagged: z.array(z.string()) }),
-    input: { policy: fromKnowledge({ source: 'connection', connectionId: env.template('FINANCE_DRIVE_CONNECTION'), query: 'vendor payment policy', maxChars: 6000 }) },   // B41
-    toolScope: { connectionIds: [] } })                                                           // tainted by the connection knowledge ⇒ `toolScope` mandatory (P1-16); the knowledge connection is added by the compiler's overlay pass
-  .approval('reviewInvoices', { title: template('${stepResults.loadInvoices.invoices.length} vendor invoices'), details: template('Flagged: ${stepResults.policyCheck.flagged}'),
-    approver: { role: 'finance' }, itemsPath: 'invoices', itemApprover: { fromItem: 'approverEmail' },   // B20: every invoice goes to ITS approver; the parent link is the finance role's overview
-    itemTimeout: { timeoutHours: 48 }, editable: true, editablePaths: ['invoices[*].amount'], timeoutHours: 96 })
-  .foreach('pay', 'payInvoice', { items: fromStep('reviewInvoices', 'items'), concurrency: 4 })   // consumes `resumeData.items[]` — approved rows only
+    input: {
+      policy: fromKnowledge({
+        source: 'connection',
+        connectionId: env.template('FINANCE_DRIVE_CONNECTION'),
+        query: 'vendor payment policy',
+        maxChars: 6000,
+      }),
+    }, // B41
+    toolScope: { connectionIds: [] },
+  }) // tainted by the connection knowledge ⇒ `toolScope` mandatory (P1-16); the knowledge connection is added by the compiler's overlay pass
+  .approval('reviewInvoices', {
+    title: 'Vendor invoices to review',
+    details: template(
+      '${stepResults.loadInvoices.invoices.length} invoices; flagged: ${stepResults.policyCheck.flagged}'
+    ),
+    approver: { role: 'finance' },
+    itemsPath: 'invoices',
+    itemApprover: { fromItem: 'approverEmail' }, // B20: every invoice goes to ITS approver; the parent link is the finance role's overview
+    itemTimeout: { timeoutHours: 48 },
+    editable: true,
+    editablePaths: ['invoices[*].amount'],
+    timeoutHours: 96,
+  })
+  .foreach(payInvoice, { items: fromStep('reviewInvoices', 'items'), concurrency: 4 }) // `foreach(step, opts)`: consumes `resumeData.items[]` — approved rows only
   .commit();

package/template/package.json

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