@intentius/chant 0.90.0 → 0.93.0

package/src/cli/handlers/components.test.ts

@@ -49,6 +49,16 @@ vi.mock("../../lifecycle/build-ledger-store", () => ({
   readBuildManifest: (...args: unknown[]) => readBuildManifestMock(...args),
 }));
 
+const persistReleasePlanMock = vi.fn();
+
+vi.mock("../../lifecycle/plan-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/plan-ledger")>("../../lifecycle/plan-ledger");
+  return {
+    ...actual,
+    persistReleasePlan: (...args: unknown[]) => persistReleasePlanMock(...args),
+  };
+});
+
 vi.mock("../../lifecycle/release-ledger", async () => {
   const actual = await vi.importActual<typeof import("../../lifecycle/release-ledger")>("../../lifecycle/release-ledger");
   return {
@@ -137,6 +147,7 @@ describe("components handlers", () => {
     discoverComponentsMock.mockReset().mockResolvedValue({ components: new Map(), sourceFiles: [], errors: [] });
     findBuildManifestByArtifactDigestMock.mockReset().mockResolvedValue(undefined);
     readBuildManifestMock.mockReset().mockResolvedValue(null);
+    persistReleasePlanMock.mockReset().mockResolvedValue({ commit: "a".repeat(40), written: true });
 
     delete process.env.GITHUB_RUN_ID;
     delete process.env.CI_PIPELINE_ID;
@@ -222,6 +233,88 @@ describe("components handlers", () => {
       await runComponentsReleaseRecord(ctx);
       expect(JSON.parse(stdoutBuf.join(""))).toMatchObject(record);
     });
+
+    describe("--plan (ws-055, #2733)", () => {
+      let planDir: string;
+
+      beforeEach(async () => {
+        planDir = await mkdtemp(join(tmpdir(), "chant-plan-"));
+      });
+
+      afterEach(async () => {
+        await rm(planDir, { recursive: true, force: true });
+      });
+
+      test("persists the plan and records its own digest, when --digest is omitted", async () => {
+        const planPath = join(planDir, "plan.json");
+        await writeFile(planPath, JSON.stringify({ digest: "sha256:fromplan", release: "r-1", units: [] }));
+        appendReleaseRecordMock.mockResolvedValue({
+          commit: "a".repeat(40),
+          record: { version: 1, component: "svc", env: "prod", digest: "sha256:fromplan", gitSha: "abc123headsha", runId: "local-123", timestamp: "2026-01-01T00:00:00.000Z", actor: "alice" },
+        });
+
+        const ctx = { args: makeArgs({ extraPositional: "prod", component: "svc", releasePlanFile: planPath, actor: "alice" }), plugins: [], serializers: [] };
+        const exit = await runComponentsReleaseRecord(ctx);
+
+        expect(exit).toBe(0);
+        expect(persistReleasePlanMock).toHaveBeenCalledTimes(1);
+        expect(persistReleasePlanMock.mock.calls[0][0]).toEqual({ digest: "sha256:fromplan", release: "r-1", units: [] });
+        const [input] = appendReleaseRecordMock.mock.calls[0];
+        expect(input).toMatchObject({ digest: "sha256:fromplan" });
+        // The plan is persisted before the release record is appended, so the
+        // record's digest always names a plan this checkout can resolve.
+        expect(persistReleasePlanMock.mock.invocationCallOrder[0]).toBeLessThan(appendReleaseRecordMock.mock.invocationCallOrder[0]);
+      });
+
+      test("--digest agreeing with the plan's own digest is accepted", async () => {
+        const planPath = join(planDir, "plan.json");
+        await writeFile(planPath, JSON.stringify({ digest: "sha256:agree", release: "r-1" }));
+        appendReleaseRecordMock.mockResolvedValue({ commit: "a".repeat(40), record: { version: 1, component: "svc", env: "prod", digest: "sha256:agree", gitSha: "x", runId: "y", timestamp: "z", actor: "alice" } });
+
+        const ctx = { args: makeArgs({ extraPositional: "prod", component: "svc", digest: "sha256:agree", releasePlanFile: planPath, actor: "alice" }), plugins: [], serializers: [] };
+        const exit = await runComponentsReleaseRecord(ctx);
+        expect(exit).toBe(0);
+      });
+
+      test("--digest disagreeing with the plan's own digest is refused", async () => {
+        const planPath = join(planDir, "plan.json");
+        await writeFile(planPath, JSON.stringify({ digest: "sha256:plandigest" }));
+
+        const ctx = { args: makeArgs({ extraPositional: "prod", component: "svc", digest: "sha256:other", releasePlanFile: planPath, actor: "alice" }), plugins: [], serializers: [] };
+        const exit = await runComponentsReleaseRecord(ctx);
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("does not match --release-plan");
+        expect(persistReleasePlanMock).not.toHaveBeenCalled();
+        expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+      });
+
+      test("a plan file with no digest field is refused", async () => {
+        const planPath = join(planDir, "plan.json");
+        await writeFile(planPath, JSON.stringify({ release: "r-1" }));
+
+        const ctx = { args: makeArgs({ extraPositional: "prod", component: "svc", releasePlanFile: planPath, actor: "alice" }), plugins: [], serializers: [] };
+        const exit = await runComponentsReleaseRecord(ctx);
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("missing its own \"digest\" field");
+      });
+
+      test("a plan file that is not valid JSON is refused", async () => {
+        const planPath = join(planDir, "plan.json");
+        await writeFile(planPath, "{not json");
+
+        const ctx = { args: makeArgs({ extraPositional: "prod", component: "svc", releasePlanFile: planPath, actor: "alice" }), plugins: [], serializers: [] };
+        const exit = await runComponentsReleaseRecord(ctx);
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("is not valid JSON");
+      });
+
+      test("a --plan path that can't be read is refused", async () => {
+        const ctx = { args: makeArgs({ extraPositional: "prod", component: "svc", releasePlanFile: join(planDir, "missing.json"), actor: "alice" }), plugins: [], serializers: [] };
+        const exit = await runComponentsReleaseRecord(ctx);
+        expect(exit).toBe(1);
+        expect(stderrBuf.join("\n")).toContain("Could not read --release-plan");
+      });
+    });
   });
 
   describe("runComponentsStatus", () => {

package/src/cli/handlers/components.ts

@@ -38,6 +38,7 @@ import {
   resolveRunId,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
+import { persistReleasePlan, InvalidReleasePlanError, type ReleasePlan } from "../../lifecycle/plan-ledger";
 import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence, type EntityLiveRead } from "../../lifecycle/status";
 import { commandBuildParams } from "../build-params-cli";
 import { buildChangeSet } from "../../lifecycle/change-set";
@@ -75,6 +76,14 @@ import { withoutReadFlags } from "../../lifecycle/legacy-digest";
  * never threaded in from elsewhere and never mocked in production code, per
  * #568: "the session cannot call Date.now() in some contexts; take the
  * timestamp from the environment/CLI at record time."
+ *
+ * `--release-plan <file>` (ws-055, #2733) takes `--digest`'s place: the file is a
+ * release plan JSON object naming its own `digest` field, persisted
+ * content-addressed to `_plans/<digest>.json` (../../lifecycle/plan-
+ * ledger.ts) before the release record is appended, so the record's digest
+ * always names a plan this checkout can resolve. Passing both requires them
+ * to agree — a plan is content-addressed by its own digest, so a caller
+ * naming a different one is a mistake, not an override.
  */
 export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
@@ -87,11 +96,42 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   }
 
   const component = args.component;
-  const digest = args.digest;
+  let digest = args.digest;
+  let plan: ReleasePlan | undefined;
+  if (args.releasePlanFile) {
+    let raw: string;
+    try {
+      raw = await readFile(args.releasePlanFile, "utf-8");
+    } catch (err) {
+      console.error(formatError({ message: `Could not read --release-plan ${args.releasePlanFile}: ${err instanceof Error ? err.message : String(err)}` }));
+      return 1;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      console.error(formatError({ message: `--release-plan ${args.releasePlanFile} is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }));
+      return 1;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.error(formatError({ message: `--release-plan ${args.releasePlanFile} must be a JSON object` }));
+      return 1;
+    }
+    plan = parsed as ReleasePlan;
+    if (typeof plan.digest !== "string" || plan.digest.length === 0) {
+      console.error(formatError({ message: `--release-plan ${args.releasePlanFile} is missing its own "digest" field — a release plan is content-addressed by its own digest` }));
+      return 1;
+    }
+    if (digest !== undefined && digest !== plan.digest) {
+      console.error(formatError({ message: `--digest ${digest} does not match --release-plan ${args.releasePlanFile}'s own digest ${plan.digest}` }));
+      return 1;
+    }
+    digest = plan.digest;
+  }
   if (!component || !digest) {
     console.error(formatError({
       message: "--component and --digest are required",
-      hint: "chant components release <env> --component <name> --digest <sha256:...> [--git-sha <sha>] [--run-id <id>] [--actor <name>] [--approver <name>]",
+      hint: "chant components release <env> --component <name> --digest <sha256:...> [--release-plan <file>] [--git-sha <sha>] [--run-id <id>] [--actor <name>] [--approver <name>]",
     }));
     return 1;
   }
@@ -121,6 +161,7 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   const timestamp = new Date().toISOString();
 
   try {
+    if (plan) await persistReleasePlan(plan);
     const { commit, record } = await appendReleaseRecord({
       component,
       env: environment,
@@ -142,7 +183,7 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
     }
     return 0;
   } catch (err) {
-    if (err instanceof InvalidReleaseRecordError) {
+    if (err instanceof InvalidReleaseRecordError || err instanceof InvalidReleasePlanError) {
       console.error(formatError({ message: err.message }));
       return 1;
     }

package/src/cli/handlers/graph.test.ts

@@ -3,6 +3,7 @@ import type { ParsedArgs } from "../registry";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
 import { AttrRef } from "../../attrref";
 import { GRAPH_IR_VERSION } from "../../graph-ir";
+import { NO_LEXICON_DETECTED_MESSAGE } from "../../detectLexicon";
 
 /**
  * The aws emulator capability, as the real plugin declares it. `--live`
@@ -469,6 +470,25 @@ describe("runGraph", () => {
       expect(exit).toBe(1);
       expect(stderrBuf.join("\n")).toContain("boom");
     });
+
+    // #2841 — an Ops-only project (`lexicons: []`, no lexicon import) has no
+    // lexicon to predict with. Detection's sentinel means "none", not a failed
+    // graph, so `chant workspace graph` does not report the member failed.
+    test("--format ir in a project with no lexicon graphs with no plugins", async () => {
+      lintClean(); discovered();
+      resolveLexMock.mockRejectedValue(new Error(NO_LEXICON_DETECTED_MESSAGE));
+      loadPluginsMock.mockResolvedValue([]);
+      const exit = await runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      expect(loadPluginsMock).toHaveBeenCalledWith([]);
+      expect(JSON.parse(stdoutBuf.join("\n")).nodes.length).toBe(3);
+    });
+
+    test("--format ir still fails on a lexicon error other than none detected", async () => {
+      lintClean(); discovered();
+      resolveLexMock.mockRejectedValue(new Error("lexicon @intentius/chant-lexicon-nope is not installed"));
+      await expect(runGraph({ args: makeArgs({ format: "ir" }), plugins: [], serializers: [] })).rejects.toThrow("not installed");
+    });
   });
 
   describe("component DAG view (--components --format ir|layout)", () => {

package/src/cli/handlers/graph.ts

@@ -21,6 +21,7 @@ import { toDot } from "../../graph-dot";
 import { getLayoutEngine, toLayoutInput, type NodeSize } from "../../graph-layout";
 import { lintCommand } from "../commands/lint";
 import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "../plugins";
+import { isNoLexiconDetected } from "../../detectLexicon";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext, ParsedArgs } from "../registry";
@@ -31,6 +32,19 @@ import type { BuildParamProvenance } from "../../provenance";
 import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 
+/**
+ * The project's lexicons, or none for a project that declares none and imports
+ * none (an Ops-only member, `lexicons: []`): detection's NO_LEXICON_DETECTED
+ * sentinel means "no lexicon", as `chant lint` reads it, not a failed graph (#2841).
+ */
+async function projectLexiconsOrNone(projectPath: string): Promise<string[]> {
+  try {
+    return await resolveProjectLexicons(projectPath);
+  } catch (err) {
+    if (isNoLexiconDetected(err)) return [];
+    throw err;
+  }
+}
 
 /**
  * Resolve this invocation's declared build-time parameters, the same way
@@ -223,7 +237,7 @@ async function runGraphLive(
   // `graph` is not `requiresPlugins` (Op/source-graph modes must work without a
   // lexicon), so `ctx.plugins` is empty. The live path needs the project's
   // observation plugins — load them here, mirroring the lifecycle handlers.
-  const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await resolveProjectLexicons(projectPath));
+  const plugins = ctx.plugins.length > 0 ? ctx.plugins : await loadPlugins(await projectLexiconsOrNone(projectPath));
   const declaredEnvNames = environmentNames(config.environments);
   if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
     console.error(formatError({
@@ -828,7 +842,7 @@ async function runGraphView(
   {
     const plugins = ctx.plugins.length > 0
       ? ctx.plugins
-      : await loadPlugins(await resolveProjectLexicons(projectPath));
+      : await loadPlugins(await projectLexiconsOrNone(projectPath));
     const predicted = await predictOntoIr(ir, plugins as LexiconPlugin[], ctx.args, {
       // No environment on the declared path: the file is not deployed anywhere
       // yet, and naming one would claim it was.

package/src/cli/handlers/operator.ts

@@ -11,7 +11,8 @@ import { loadChantConfig } from "../../config";
 import { build } from "../../build";
 import { isResourceDeclarable } from "../../declarable";
 import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins";
-import { discoverOps } from "../../op/discover";
+import { discoverOps, discoverStewards } from "../../op/discover";
+import { pickSteward, stewardFormFor, stewardLeaseName, DEFAULT_STEWARD_ENV } from "../../op/steward";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { parseDuration } from "../../op/local-executor";
 import {
@@ -21,13 +22,14 @@ import {
   formatRoundLine,
   formatSignalLine,
   DEFAULT_OPERATOR_INTERVAL_MS,
+  acquireStewardLease,
   type ChangeSubscriber,
   type OperatorSignalEvent,
   type OperatorTickEvent,
 } from "../../op/operator";
-import { readLease, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease";
+import { readLease, releaseLease, currentHolderId, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease";
 import { readConvergeLedger, type ConvergeTickRecord } from "../../lifecycle/converge-ledger";
-import { readRunLedger } from "../../lifecycle/run-ledger";
+import { readRunLedger, runEnvOf } from "../../lifecycle/run-ledger";
 import type { OpRunRecord } from "../../op/runtime";
 import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger";
 import {
@@ -141,6 +143,7 @@ async function collectOperatorSubscribers(
  * leaving the daemon running); omitted, the daemon loops until Ctrl-C.
  */
 export async function runOperator(ctx: CommandContext): Promise<number> {
+  if (ctx.args.steward !== undefined) return runStewardOperator(ctx);
   const { ops, errors } = await discoverConvergeOps({ env: ctx.args.env });
   for (const err of errors) console.error(formatWarning({ message: err }));
 
@@ -205,6 +208,108 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
   }
 }
 
+// ── chant operator --steward ────────────────────────────────────────────────
+
+/**
+ * `chant operator --steward [<name>] [--env <env>] [--interval] [--lease-ttl]
+ * [--once]` (#2731) — a steward's local form. The same Ops the steward runs on
+ * Fountain, on the same crons, one at a time, each under its operator lease,
+ * and the whole process under the steward's own lease.
+ *
+ * Refuses, before ticking anything:
+ * - an environment whose form is `fountain`, because there the composite's
+ *   Agent and Teammate are the steward and this process would be a second
+ *   writer beside them;
+ * - a steward whose lease another live process holds (a second local
+ *   operator for it).
+ */
+export async function runStewardOperator(ctx: CommandContext): Promise<number> {
+  const { stewards, errors, conflicts } = await discoverStewards();
+  for (const err of errors) console.error(formatWarning({ message: err }));
+  for (const conflict of conflicts) console.error(formatError({ message: conflict }));
+
+  const picked = pickSteward(stewards, ctx.args.steward ?? "");
+  if (typeof picked === "string") {
+    console.error(formatError({ message: picked }));
+    return 1;
+  }
+  const steward = picked;
+  const env = ctx.args.env ?? DEFAULT_STEWARD_ENV;
+  const form = stewardFormFor(steward, env);
+  if (form !== "local") {
+    console.error(formatError({
+      message: `steward "${steward.name}" runs on ${form} in environment "${env}", so a local operator for it would be a second writer`,
+      hint: `Its turns run on the fountain teammate "${steward.name}". Run this in an environment the declaration's form makes local, or change the form.`,
+    }));
+    return 1;
+  }
+
+  let activities, profiles;
+  try {
+    [activities, profiles] = await loadOperatorActivities();
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+
+  const intervalMs = ctx.args.interval ? parseDuration(ctx.args.interval) : DEFAULT_OPERATOR_INTERVAL_MS;
+  const leaseTtlMs = ctx.args.leaseTtl ? parseDuration(ctx.args.leaseTtl) : DEFAULT_LEASE_TTL_MS;
+  const holder = currentHolderId();
+
+  // Refuse a second local operator up front rather than letting it loop on
+  // `steward-busy` rounds: one steward is one writer.
+  const first = await acquireStewardLease(steward.name, holder, { ttlMs: leaseTtlMs });
+  if (!first.acquired) {
+    console.error(formatError({
+      message: `steward "${steward.name}" is already running (lease held by ${first.heldBy?.holder ?? "another process"} until ${first.heldBy?.expiresAt ?? "?"})`,
+      hint: "One steward is one writer. Stop the other operator, or wait for its lease to expire.",
+    }));
+    return 1;
+  }
+
+  const controller = new AbortController();
+  const onSigint = () => {
+    console.error(formatWarning({ message: "interrupted — stopping steward" }));
+    controller.abort();
+  };
+  process.once("SIGINT", onSigint);
+  process.once("SIGTERM", onSigint);
+
+  const printRound = (events: OperatorTickEvent[]) => {
+    for (const event of events) console.error(formatInfo(formatRoundLine(event)));
+  };
+
+  const scheduled = steward.ops.filter((op) => op.schedule !== undefined);
+  try {
+    if (ctx.args.once) {
+      const events = await runOperatorRound({ steward, holder, leaseTtlMs, activities, profiles, signal: controller.signal });
+      printRound(events);
+      return events.some((e) => e.kind === "tick-failed" || e.kind === "steward-busy") ? 1 : 0;
+    }
+    console.error(formatInfo(
+      `chant operator: steward ${steward.name} (local) runs ${scheduled.length} scheduled Op(s) of ${steward.ops.length}, ` +
+        `checking every ${intervalMs}ms (Ctrl-C to stop)`,
+    ));
+    await runOperatorForever({
+      steward,
+      holder,
+      intervalMs,
+      leaseTtlMs,
+      activities,
+      profiles,
+      signal: controller.signal,
+      onRound: printRound,
+    });
+    return 0;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+    process.removeListener("SIGTERM", onSigint);
+    // A courtesy: the lease expires on its own if this never runs.
+    const { record } = await readLease(stewardLeaseName(steward.name)).catch(() => ({ record: undefined }));
+    if (record?.holder === holder) await releaseLease(stewardLeaseName(steward.name), holder, record.token).catch(() => false);
+  }
+}
+
 // ── chant operator status ───────────────────────────────────────────────────
 
 interface OpStatusLine {
@@ -308,6 +413,12 @@ async function statusFor(opName: string, env: string, cwd?: string): Promise<OpS
 export interface StandaloneGateLine {
   op: string;
   gate: string;
+  /**
+   * The Op whose newest run stopped at this gate, when the gate is a
+   * command's own rather than the Op's (#2779): a step running `chant
+   * workspace upgrade` stops its run at `workspace-upgrade` / `<scope>`.
+   */
+  run?: string;
   description?: string;
   expiresAt: string;
   url?: string;
@@ -353,6 +464,32 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
     }
   }
 
+  // A gate a command decided inside an Op's step (#2779) is recorded under
+  // the command's op, which is not an `*.op.ts`, so the loop above never
+  // reads it. The Op's newest run names it; list it against that Op while it
+  // still stands.
+  for (const [opName, discovered] of [...allOps.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    let newest: OpRunRecord | undefined;
+    try {
+      newest = (await readRunLedger(runEnvOf(discovered.config), opName)).records.at(-1);
+    } catch {
+      continue;
+    }
+    const gateOp = newest?.status === "gated" ? newest.gate?.op : undefined;
+    if (!newest?.gate || !gateOp || gateOp === opName) continue;
+    const record = (await pendingGatesFor(gateOp)).find((r) => r.gate === newest.gate!.name);
+    if (!record || covered.has(`${gateOp} ${record.gate}`)) continue;
+    covered.add(`${gateOp} ${record.gate}`);
+    standalone.push({
+      op: gateOp,
+      gate: record.gate,
+      run: opName,
+      expiresAt: record.expiresAt,
+      ...(record.description ? { description: record.description } : {}),
+      ...(record.url ? { url: record.url } : {}),
+    });
+  }
+
   if (ops.length === 0 && standalone.length === 0) {
     console.error(formatWarning({ message: "No ConvergeOp declarations found" }));
     return 0;
@@ -389,7 +526,7 @@ export async function runOperatorStatus(ctx: CommandContext): Promise<number> {
   if (standalone.length > 0) {
     console.log(formatBold("pending gates (no converge tick)"));
     for (const g of standalone) {
-      console.log(`  - ${g.op} gate "${g.gate}" — resolve: chant approve ${g.op} ${g.gate}`);
+      console.log(`  - ${g.op} gate "${g.gate}"${g.run ? ` (Op ${g.run}'s run stopped here)` : ""} — resolve: chant approve ${g.op} ${g.gate}`);
       if (g.description) console.log(`    ${g.description}`);
       console.log(`    expires: ${g.expiresAt}`);
       if (g.url) console.log(`    approve at: ${g.url}`);