@intentius/chant 0.124.15 → 0.124.16

package/src/wave-runtime.e2e.test.ts

@@ -0,0 +1,177 @@
+/**
+ * The wave-job runtime runs alone (#3896). `dist/wave-runtime.mjs` is copied
+ * into an empty directory, the way a product's CI image carries it, and run
+ * with plain node, nothing installed beside it, through a gated wave's whole
+ * life: `run wave` waits at a ledger gate, `approve` records the resolution,
+ * `run resume --dry-run` finds it, `run wave` applies; then a wave whose gate
+ * asks a decision point waits, `workspace points` lists the open question,
+ * `workspace points answer` answers it, and `run wave` applies.
+ *
+ * End to end because it builds the bundle and spawns node for each command.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { copyFileSync, cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+// @ts-expect-error: a plain .mjs script with no type declarations
+import { buildWaveRuntime } from "../scripts/build-wave-runtime.mjs";
+import { REPO } from "./workspace/__fixtures__/decide-workspace";
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+const SPEC = {
+  name: "smoke",
+  op: "smoke",
+  plan: ["node", "plan.mjs", "{target}", "{plan}"],
+  apply: ["node", "apply.mjs", "{target}", "{plan}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "always" },
+    { name: "prod", runs: [{ target: "prod" }], gate: "always", point: "prod-apply" },
+  ],
+};
+
+let scratch: string;
+let runtimeDir: string;
+let runtime: string;
+let repo: string;
+
+/** The job's environment: no CI variables, so nothing names a CI job to resume. */
+function jobEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (/^(CI|GITHUB_|GITLAB_|FORGEJO_|GITEA_|CHANT_|NODE_OPTIONS$|VITEST)/.test(k)) continue;
+    env[k] = v;
+  }
+  return env;
+}
+
+function chant(...args: string[]): { status: number | null; stdout: string; stderr: string } {
+  const r = spawnSync(process.execPath, [runtime, ...args], { cwd: repo, env: jobEnv(), encoding: "utf-8" });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr };
+}
+
+const git = (...args: string[]) =>
+  execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd: repo, stdio: "ignore" });
+
+beforeAll(async () => {
+  scratch = realpathSync(mkdtempSync(join(tmpdir(), "chant-wave-runtime-")));
+  const built = join(scratch, "build", "wave-runtime.mjs");
+  mkdirSync(dirname(built), { recursive: true });
+  await buildWaveRuntime({ outfile: built });
+  runtimeDir = join(scratch, "image");
+  mkdirSync(runtimeDir);
+  runtime = join(runtimeDir, "wave-runtime.mjs");
+  copyFileSync(built, runtime);
+
+  repo = join(scratch, "repo");
+  const files: Record<string, string> = {
+    "chant.workspace.json": JSON.stringify({
+      name: "wave-runtime",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+      records: [{ kind: "answers/answer.kind.mjs" }],
+    }),
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/points.json": JSON.stringify(POINTS),
+    "plan.mjs": `import { writeFileSync } from "node:fs";\nwriteFileSync(process.argv[3], JSON.stringify({ planDigest: "sha256:" + (process.argv[2] === "dev" ? "a" : "b").repeat(64) }));\n`,
+    "apply.mjs": `import { appendFileSync } from "node:fs";\nappendFileSync("applied.log", process.argv[2] + "\\n");\n`,
+    "waves.json": JSON.stringify(SPEC),
+  };
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(repo, path)), { recursive: true });
+    writeFileSync(join(repo, path), text);
+  }
+  cpSync(join(REPO, "reference-workspace", "answers", "answer.kind.mjs"), join(repo, "answers", "answer.kind.mjs"));
+  cpSync(join(REPO, "reference-workspace", "answers", "answer.schema.json"), join(repo, "answers", "answer.schema.json"));
+  git("init", "-q", "-b", "main");
+  git("add", "-A");
+  git("commit", "-qm", "spec");
+  // The gate policy is read at HEAD^1, so the spec needs a commit under the head.
+  writeFileSync(join(repo, ".gitignore"), ".chant/\napplied.log\n");
+  git("add", "-A");
+  git("commit", "-qm", "ignore");
+}, 120_000);
+
+afterAll(() => {
+  if (scratch) rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("the wave-job runtime, alone in a directory (#3896)", () => {
+  test("is one file, with no package beside it to resolve", () => {
+    expect(readdirSync(runtimeDir)).toEqual(["wave-runtime.mjs"]);
+    const resolveBeside = createRequire(runtime).resolve;
+    for (const pkg of ["@intentius/chant", "typescript", "esbuild", "tsx", "zod", "ajv"]) {
+      expect(() => resolveBeside(pkg), pkg).toThrow();
+    }
+    const version = (JSON.parse(readFileSync(join(REPO, "packages", "core", "package.json"), "utf-8")) as { version: string }).version;
+    expect(chant("--version").stdout.trim()).toBe(version);
+    const other = chant("build");
+    expect(other.status).toBe(1);
+    expect(other.stderr).toContain("is not part of chant's wave-job runtime");
+  });
+
+  test("a ledger gate: run wave waits, approve, run resume --dry-run, run wave applies", () => {
+    const waiting = chant("run", "wave", "--spec", "waves.json", "--wave", "1", "--json");
+    expect(waiting.status, waiting.stderr).toBe(3);
+    const decision = (JSON.parse(waiting.stdout) as { decision: { status: string; gate: string; digest: string } }).decision;
+    expect(decision).toMatchObject({ status: "waiting", gate: "smoke-wave-1" });
+
+    const approved = chant("approve", "smoke", "smoke-wave-1", "--actor", "alice");
+    expect(approved.status, approved.stderr).toBe(0);
+    expect(approved.stderr).toContain(`Gate "smoke-wave-1" on "smoke" resolved by alice`);
+    expect(approved.stderr).toContain(`This approves the plan ${decision.digest}`);
+
+    const resume = chant("run", "resume", "--dry-run");
+    expect(resume.status, resume.stderr).toBe(0);
+    expect(resume.stderr).toContain("smoke / smoke-wave-1, approved by alice");
+
+    const applied = chant("run", "wave", "--spec", "waves.json", "--wave", "1");
+    expect(applied.status, applied.stderr).toBe(0);
+    expect(applied.stderr).toContain("approved by alice");
+    expect(readFileSync(join(repo, "applied.log"), "utf-8")).toBe("dev\n");
+  });
+
+  test("a gate that asks a decision point: run wave waits, points lists and answers, run wave applies", () => {
+    const waiting = chant("run", "wave", "--spec", "waves.json", "--wave", "2", "--json");
+    expect(waiting.status, waiting.stderr).toBe(3);
+    const id = (JSON.parse(waiting.stdout) as { decision: { point: { question: { id: string } } } }).decision.point.question.id;
+    expect(id).toMatch(/^prod-apply-[0-9a-f]{12}$/);
+
+    const open = chant("workspace", "points", "--open");
+    expect(open.status, open.stderr).toBe(0);
+    expect(open.stdout).toContain(`${id}  escalated`);
+
+    const answered = chant("workspace", "points", "answer", id, "--answer", "true", "--by", "alice");
+    expect(answered.status, answered.stderr).toBe(0);
+    expect(readFileSync(join(repo, "answers", `${id}.md`), "utf-8")).toMatch(/state: "answered"\nanswer: true/);
+
+    const applied = chant("run", "wave", "--spec", "waves.json", "--wave", "2");
+    expect(applied.status, applied.stderr).toBe(0);
+    expect(readFileSync(join(repo, "applied.log"), "utf-8")).toBe("dev\nprod\n");
+
+    // The ledger the runtime wrote is the full CLI's: pending, resolution, pending citing the question, resolution citing the answer.
+    const ledger = execFileSync("git", ["show", "chant/lifecycle:_gates/smoke.jsonl"], { cwd: repo, encoding: "utf-8" })
+      .trim()
+      .split("\n")
+      .map((l) => JSON.parse(l) as { kind?: string; gate: string; resolvedBy?: string; answer?: { id: string } });
+    expect(ledger.map((l) => [l.gate, l.kind ?? "resolution", l.resolvedBy ?? null])).toEqual([
+      ["smoke-wave-1", "pending", null],
+      ["smoke-wave-1", "resolution", "alice"],
+      ["smoke-wave-2", "pending", null],
+      ["smoke-wave-2", "resolution", "alice"],
+    ]);
+    expect(ledger[3]!.answer?.id).toBe(id);
+  });
+});

package/src/wave-runtime.ts

@@ -0,0 +1,104 @@
+/**
+ * The slim wave-job runtime (#3896): the four commands a generated Op waves
+ * pipeline runs, and nothing else.
+ *
+ *   chant run wave --spec <file> --wave <k> [--decide | --share <i> | --record-plans]
+ *   chant run resume [--gate <op>/<gate>] [--dry-run]
+ *   chant approve <op> <gate> [...]
+ *   chant workspace points ask|answer|list|... [...]
+ *
+ * `scripts/build-runtime.mjs` bundles this file with esbuild into
+ * `dist/wave-runtime.mjs`: one self-contained ES module whose only imports are
+ * `node:` builtins, with no TypeScript compiler, esbuild, tsx or zod in it. A
+ * product copies that one file into its CI image and runs it with plain node,
+ * or runs it from an installed `@intentius/chant`
+ * (`node node_modules/@intentius/chant/dist/wave-runtime.mjs run wave ...`).
+ *
+ * The handlers are the full CLI's own (`./cli/main.ts` dispatches to the same
+ * functions), parsed by the same `parseArgs`, so flags, output, exit codes and
+ * the ledgers each command writes are the same. What the runtime does not do:
+ * evaluate `chant.config.ts` (which needs a TypeScript loader). None of the
+ * four commands reads the config; the full CLI loads it only to check `--env`
+ * against the declared `environments`, a check the runtime skips.
+ */
+
+import { parseArgs } from "./cli/parse-args";
+import { resolveCommand, type CommandDef, type ParsedArgs } from "./cli/registry";
+import { formatError } from "./cli/format";
+import { flushAndExit } from "./cli/flush";
+import { CHANT_VERSION } from "./cli/version";
+import { isEntryPoint } from "./cli/is-entry-point";
+import { ENV_VAR } from "./env";
+import { initRuntime } from "./runtime-adapter";
+import { runOpWaveCommand } from "./cli/handlers/run-wave";
+import { runResumeCommand } from "./cli/handlers/gate-resume";
+import { runApprove } from "./cli/handlers/approve";
+import { runWorkspacePoints } from "./workspace/points-cli";
+
+/** The commands the runtime carries, under the names the full CLI registers them by. */
+export const RUNTIME_COMMANDS: CommandDef[] = [
+  { name: "run wave", handler: runOpWaveCommand },
+  { name: "run resume", handler: runResumeCommand },
+  { name: "approve", handler: runApprove },
+  { name: "workspace points", handler: runWorkspacePoints },
+];
+
+const HELP = `
+chant runtime ${CHANT_VERSION} - the wave-job commands of chant, in one file
+
+Usage: node wave-runtime.mjs <command> [options]
+
+Commands:
+  run wave --spec <file> --wave <k>   Plan, gate and apply wave k of an Op waves spec
+                                      (--decide, --share <i>, --record-plans, --base <ref>, --json)
+  run resume                          Start the CI jobs that wait at gates whose approval arrived
+                                      (--gate <op>/<gate>, --dry-run, --json)
+  approve <op> <gate>                 Record a gate's resolution on the lifecycle ledger
+                                      (--actor, --plan, --note, --url, --sign, --expire, --resume, ...)
+  workspace points <verb>             Ask, answer and list decision points
+
+Flags, output, exit codes and ledger formats are the full chant CLI's;
+see "chant --help" in @intentius/chant for every flag. This runtime does
+not evaluate chant.config.ts, so --env is not checked against the
+declared environments.
+`;
+
+/** Parse, dispatch and return the exit code. Exported for tests. */
+export async function runRuntime(argv: string[]): Promise<number> {
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+  const match = resolveCommand(args, RUNTIME_COMMANDS);
+  if (args.version && (!args.command || match)) {
+    console.log(CHANT_VERSION);
+    return 0;
+  }
+  if (args.help || !args.command) {
+    console.log(HELP);
+    return args.help ? 0 : 1;
+  }
+  if (!match) {
+    const name = args.path && args.path !== "." ? `${args.command} ${args.path}` : args.command;
+    console.error(formatError({
+      message: `"${name}" is not part of chant's wave-job runtime`,
+      hint: "It runs run wave, run resume, approve and workspace points. Every other command needs the full @intentius/chant CLI.",
+    }));
+    return 1;
+  }
+  if (args.env) process.env[ENV_VAR] = args.env;
+  initRuntime();
+  return match.def.handler({ args, plugins: [], serializers: [] });
+}
+
+if (isEntryPoint(process.argv[1], import.meta.url)) {
+  runRuntime(process.argv.slice(2)).then(flushAndExit, async (err) => {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    if (verbose && err instanceof Error && err.stack) console.error(err.stack);
+    else console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    await flushAndExit(1);
+  });
+}

package/src/workspace/ajv2020.ts

@@ -0,0 +1,17 @@
+/**
+ * The Ajv 2020-12 validator class, loaded on first use: ajv costs start-up
+ * time, and most commands validate nothing with it. One loader for every
+ * schema check in workspace/, so the slim wave-job runtime (#3896,
+ * `../../scripts/build-wave-runtime.mjs`) can swap in a bundled ajv here
+ * instead of a `require` resolved next to an installed chant.
+ */
+import { createRequire } from "node:module";
+
+export type Ajv2020Class = new (opts: object) => { compile(schema: object): unknown };
+
+export function loadAjv2020(): Ajv2020Class {
+  const require = createRequire(import.meta.url);
+  // ajv is CommonJS; its class is the default export, or that export's own default.
+  const mod = require("ajv/dist/2020") as { default?: unknown };
+  return (mod.default ?? mod) as Ajv2020Class;
+}

package/src/workspace/declaration.ts

@@ -16,15 +16,14 @@
  * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
  */
 
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import type { ReasonCode } from "./reason-codes";
 import { joinPath, type WorkspaceTree } from "./tree";
+import { loadAjv2020 } from "./ajv2020";
+import { readChantPackageVersion } from "../package-version";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
 export const DECLARATION_FILES = ["chant.workspace.json", "chant.workspace.jsonc"] as const;
@@ -601,9 +600,7 @@ let readerVersionCache: string | undefined;
  * well under a millisecond.
  */
 export function readerVersion(): string {
-  readerVersionCache ??= (
-    JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf-8")) as { version: string }
-  ).version;
+  readerVersionCache ??= readChantPackageVersion();
   return readerVersionCache;
 }
 
@@ -638,10 +635,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
   return compiled;
 }

package/src/workspace/kinds.ts

@@ -18,13 +18,13 @@
  */
 
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";
 import { dataExportTarget, findInstalledPackage } from "./class-data";
+import { loadAjv2020 } from "./ajv2020";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -353,10 +353,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
   return compiled;
 }

package/src/workspace/points.ts

@@ -33,12 +33,12 @@
  */
 
 import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import schema from "./decision-points.schema.json" with { type: "json" };
 import type { ReasonCode } from "./reason-codes";
 import type { RecordSource } from "./record-source";
 import type { LoadedRecordKind, ReadRecordsOptions, RecordEntry } from "./records";
+import { loadAjv2020 } from "./ajv2020";
 
 export const DECISION_POINTS_SCHEMA_ID = schema.$id;
 
@@ -200,10 +200,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: false }).compile(schema);
   return compiled;
 }

package/src/workspace/principal-classes.ts

@@ -22,13 +22,13 @@
  * installed package, which must be at the version the base pins.
  */
 
-import { createRequire } from "node:module";
 import { checkClassData, diskFiles, mergePinClasses, readClassFiles, type ClassData, type PackageFiles, type PinClassRead } from "./class-data";
 import { pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
 import schema from "./workspace-principals.schema.json" with { type: "json" };
 import type { TrustPolicy } from "./trust/policy";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, grantedClasses, type PrincipalClass } from "./identity-gate-rule";
+import { loadAjv2020 } from "./ajv2020";
 
 export const PRINCIPALS_SCHEMA_ID = schema.$id;
 
@@ -99,10 +99,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
   return compiled;
 }