lua-cli 3.30.0 → 3.32.1

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

@@ -0,0 +1,137 @@
+// Linear label -> clone -> parallel worktree arms -> merge -> tests -> PR -> review loop -> approval -> merge.
+// 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';
+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)
+    log(r.stdout.slice(-4000));
+    return { passed: r.exitCode === 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 };
+  },
+});
+
+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 };
+  },
+});
+
+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() }),
+  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']]) // 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.'
+    ),
+  })
+  .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' }
+  ) // 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',
+  })
+  .then(mergePr)
+  .commit();

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

@@ -0,0 +1,83 @@
+// Per-item review with an env overlay, a restricted output pane and a slack reply (Cluster K).
+// 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 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;
+    }
+    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
+  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
+    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: '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/lua.skill.yaml

@@ -6,6 +6,7 @@ agent:
 skills: []
 webhooks: []
 jobs: []
+workflows: []
 preprocessors: []
 postprocessors: []
 mcpServers: []

package/template/package.json

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