@intentius/chant 0.124.48 → 0.124.50

package/src/workspace/checks/gate-approval.ts

@@ -0,0 +1,121 @@
+/**
+ * WSP153 (#4404): an Op gate's `approval` block that `identity.gates` does
+ * not back at base.
+ *
+ * A run reads a gate's `quorum`, `policy`, `mode` and `context` from
+ * `identity.gates.<gate>` in the declaration at base (#4324, #4404). A field
+ * the entry leaves out is read from the Op being run, which the change under
+ * review can edit, so a pull request can lower a quorum or switch a policy to
+ * `log-only` and be judged by its own edit. The Op-side fallback stays so an
+ * existing Op does not drop to one approval overnight. This check names each
+ * gate that still leans on it, and the fields it leans on.
+ *
+ * It reads each member's built Ops (`dist/ops/<name>/op.json`) and runs
+ * nothing. An Op that has not been built is not seen.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import { joinPath } from "../tree";
+import { read } from "./security";
+
+export const WSP_GATE_APPROVAL_UNBASED = "WSP153";
+
+/** The finding code WSP153 reports. */
+export const GATE_APPROVAL_FINDING_CODES = ["gate-approval-unbased"] as const;
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+type Fields = "quorum" | "policy" | "mode" | "context";
+
+interface GateUse {
+  gate: string;
+  /** What the Op's `approval` block sets. Context is the keys it sets. */
+  quorum: boolean;
+  policy: boolean;
+  mode: boolean;
+  context: string[];
+}
+
+interface StepJson {
+  kind?: string;
+  gate?: string;
+  signalName?: string;
+  approval?: { quorum?: unknown; policy?: unknown; mode?: unknown; context?: Record<string, unknown> };
+  steps?: StepJson[];
+}
+
+/** The gates of a built Op that declare an `approval` block, with the fields it sets. A gate that asks a decision point has none. */
+export function gateUses(op: { phases?: { steps?: StepJson[] }[]; onFailure?: { steps?: StepJson[] }[] }): GateUse[] {
+  const out: GateUse[] = [];
+  const visit = (step: StepJson): void => {
+    if (step.kind === "gate" && step.approval && typeof step.approval === "object") {
+      const a = step.approval;
+      out.push({
+        gate: step.gate ?? step.signalName ?? "",
+        quorum: a.quorum !== undefined,
+        policy: a.policy !== undefined,
+        mode: a.mode !== undefined,
+        context: a.context && typeof a.context === "object" ? Object.keys(a.context) : [],
+      });
+    }
+    if (step.kind === "effect") (step.steps ?? []).forEach(visit);
+  };
+  for (const p of [...(op.phases ?? []), ...(op.onFailure ?? [])]) (p.steps ?? []).forEach(visit);
+  return out;
+}
+
+/** The fields of `use` that `entry` (the gate's `identity.gates` entry, or undefined) does not set, as phrases. Empty when base backs every one. */
+export function unbasedFields(use: GateUse, entry: { quorum: unknown; policy: unknown; mode: unknown; context: Record<string, unknown> | null } | undefined): string[] {
+  const out: string[] = [];
+  const has = (f: Exclude<Fields, "context">): boolean => entry?.[f] !== null && entry?.[f] !== undefined;
+  for (const f of ["quorum", "policy", "mode"] as const) if (use[f] && !has(f)) out.push(f);
+  const loose = use.context.filter((k) => !(k in (entry?.context ?? {})));
+  if (loose.length > 0) out.push(`context (${loose.join(", ")})`);
+  return out;
+}
+
+export const GATE_APPROVAL_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_GATE_APPROVAL_UNBASED,
+    name: "gate-approval-unbased",
+    description: "An Op gate declares an approval block whose quorum, policy, mode or context identity.gates does not set at base, so the change being run can edit it.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      const gates = ctx.declaration.identity?.gates ?? {};
+      for (const member of ctx.declaration.members) {
+        const opsDir = joinPath(memberDir(member.dir), "dist", "ops");
+        for (const entry of ctx.tree.list(opsDir) ?? []) {
+          if (entry.type !== "dir") continue;
+          const path = joinPath(opsDir, entry.name, "op.json");
+          const text = read(ctx.tree, path);
+          if (text === null) continue;
+          let op: Parameters<typeof gateUses>[0] & { name?: string };
+          try {
+            op = JSON.parse(text);
+          } catch {
+            continue;
+          }
+          for (const use of gateUses(op)) {
+            const base = gates[use.gate];
+            const missing = unbasedFields(use, base);
+            if (missing.length === 0) continue;
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: GATE_APPROVAL_FINDING_CODES[0],
+              message: `WSP153: gate "${use.gate}" in Op ${op.name ?? entry.name} sets ${missing.join(", ")} in its approval block, and ${base ? `identity.gates.${use.gate}` : "identity.gates"} sets ${base ? "none of them" : `no entry for it`} at base, so a change can edit ${missing.length === 1 ? "it" : "them"} for its own run; declare ${base ? "them" : `identity.gates.${use.gate}`} in chant.workspace.json`,
+              pointer: base ? base.pointer : "/identity",
+              entity: use.gate,
+              treeFile: path,
+              line: 1,
+              column: 1,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+];

package/src/workspace/checks.ts

@@ -40,6 +40,7 @@
  * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
  * | WSP151 | what a member under `ci.workflow` still lacks (#4168 step 6) |
  * | WSP152 | a member's generated pipeline targets the branch `ci.branches` routes it to (#4325) |
+ * | WSP153 | an Op gate's approval block that `identity.gates` does not set at base (#4404) |
  * | WSP161 to WSP165 | the security groups the declaration opts into: what each still lacks (#4168 step 7) |
  */
 
@@ -65,6 +66,7 @@ import { DIAGRAM_CHECKS } from "./checks/diagrams";
 import { SECURITY_CHECKS } from "./checks/security";
 import { CI_WORKFLOW_CHECKS } from "./checks/ci-workflow";
 import { CI_BRANCH_CHECKS } from "./checks/ci-branch";
+import { GATE_APPROVAL_CHECKS } from "./checks/gate-approval";
 import { ORG_CHECKS, type ForgeRepoList } from "./checks/org";
 import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 import { resolveBoxIntents, type ResolvedBoxIntent } from "./box-intent";
@@ -425,6 +427,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...CI_WORKFLOW_CHECKS,
   // A member's pipeline targets the branch ci.branches routes it to (#4325), WSP152.
   ...CI_BRANCH_CHECKS,
+  // An Op gate's approval block that identity.gates does not set at base (#4404), WSP153.
+  ...GATE_APPROVAL_CHECKS,
   // The security groups the declaration opts into (#4168 step 7), WSP161 to WSP165.
   ...SECURITY_CHECKS,
 ];

package/src/workspace/declaration.schema.json

@@ -175,6 +175,26 @@
                   { "$ref": "#/$defs/gateQuorumRule" },
                   { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/gateQuorumRule" } }
                 ]
+              },
+              "policy": {
+                "$ref": "#/$defs/gatePolicyRef",
+                "description": "The policy set an Op gate of this name takes (#4404), in place of the Op's own approval.policy. Read at base, so a change can't swap in a permissive policy for its own run. Build the object with the owning lexicon's helper (the cedar lexicon's gatePolicy()) and paste it here. Added in schema 1 by chant 0.124.49, so a declaration that uses it sets minReader to 0.124.49 or newer."
+              },
+              "mode": {
+                "enum": ["log-only", "enforce"],
+                "description": "Whether the policy's decision binds the gate (#4404), in place of the Op's own approval.mode: log-only records it next to the approval, enforce passes the gate only on a permit. Read at base, so a change can't switch its own gate to a mode that passes it. Added in schema 1 by chant 0.124.49, so a declaration that uses it sets minReader to 0.124.49 or newer."
+              },
+              "context": {
+                "type": "object",
+                "description": "Plan attributes handed to the policy (#4404), over the Op's own approval.context, key by key: a change can't edit a key declared here, and a key only the Op declares still reaches the policy. A value is a plain one, since a step output reference is resolved at run time and a declaration can't hold one. plan is reserved. Added in schema 1 by chant 0.124.49, so a declaration that uses it sets minReader to 0.124.49 or newer.",
+                "additionalProperties": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" },
+                    { "type": "array", "items": { "type": "string" } }
+                  ]
+                }
               }
             }
           }
@@ -460,6 +480,19 @@
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]{0,39}$"
     },
+    "gatePolicyRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "lexicon", "name", "version", "text"],
+      "description": "A gate policy set a lexicon rendered (#2508), as plain data.",
+      "properties": {
+        "kind": { "const": "gate-policy" },
+        "lexicon": { "type": "string", "minLength": 1, "description": "The lexicon whose gate-policy module evaluates text." },
+        "name": { "type": "string", "minLength": 1, "description": "A name for the policy set, carried into every recorded decision." },
+        "version": { "type": "string", "minLength": 1, "description": "sha256: and the hex digest of text. A recorded permit counts only under the version it was evaluated against." },
+        "text": { "type": "string", "minLength": 1, "description": "The policy set, in the lexicon's own language." }
+      }
+    },
     "gateQuorumRule": {
       "type": "object",
       "additionalProperties": false,

package/src/workspace/declaration.ts

@@ -31,6 +31,7 @@ import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
 import { assertPrLoopHooks, type OpWaveHooks } from "../op/op-waves";
 import { quorumProblems, type GateQuorumSpec } from "../op/gate-quorum";
+import { gateBaseApprovalProblems, type GateApprovalMode, type GatePolicyRef } from "../op/gate-approval";
 import { assertGatePolicySettings, type GatePolicySettings } from "../gate-policy";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
@@ -167,6 +168,12 @@ export interface SignedGate {
    * the Op's own `approval.quorum` then applies.
    */
   quorum: GateQuorumSpec | null;
+  /** The policy an Op gate of this name takes in place of its own `approval.policy` (#4404). Null when the entry sets none. */
+  policy: GatePolicyRef | null;
+  /** The mode an Op gate of this name runs its policy in, in place of its own `approval.mode` (#4404). Null when the entry sets none. */
+  mode: GateApprovalMode | null;
+  /** The context an Op gate of this name hands its policy, in place of its own `approval.context` (#4404). Null when the entry sets none. */
+  context: Record<string, string | number | boolean | string[]> | null;
   pointer: string;
 }
 
@@ -1247,7 +1254,7 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
  */
 function identityOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): IdentityPolicy | null {
   if (raw === undefined) return null;
-  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string; quorum?: GateQuorumSpec }> };
+  const block = raw as { attribution?: "any" | "identified"; gates?: Record<string, { class?: string; quorum?: GateQuorumSpec; policy?: GatePolicyRef; mode?: GateApprovalMode; context?: Record<string, string | number | boolean | string[]> }> };
   const gates: Record<string, SignedGate> = {};
   for (const [gate, entry] of Object.entries(block.gates ?? {})) {
     const pointer = `/identity/gates/${gate.replace(/~/g, "~0").replace(/\//g, "~1")}`;
@@ -1255,7 +1262,17 @@ function identityOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorL
       const [problem] = quorumProblems(entry.quorum, `identity.gates.${gate}.quorum`, { notAuthor: false });
       if (problem) throw new WorkspaceReadError("declaration-invalid", problem.replace(/`/g, ""), at(`${pointer}/quorum`));
     }
-    gates[gate] = { gate, class: entry.class ?? null, quorum: entry.quorum !== undefined ? structuredClone(entry.quorum) : null, pointer };
+    const [rest] = gateBaseApprovalProblems(entry, `identity.gates.${gate}`);
+    if (rest) throw new WorkspaceReadError("declaration-invalid", rest.replace(/`/g, ""), at(pointer));
+    gates[gate] = {
+      gate,
+      class: entry.class ?? null,
+      quorum: entry.quorum !== undefined ? structuredClone(entry.quorum) : null,
+      policy: entry.policy !== undefined ? structuredClone(entry.policy) : null,
+      mode: entry.mode ?? null,
+      context: entry.context !== undefined ? structuredClone(entry.context) : null,
+      pointer,
+    };
   }
   return { attribution: block.attribution ?? "any", gates };
 }

package/src/workspace/exit-cli.ts

@@ -0,0 +1,219 @@
+/**
+ * `chant workspace exit [<member>...] [--dry-run] [--drill] [--output <file>] [--json]`
+ * (#3177).
+ *
+ * Stages the exit in a git worktree (see ./exit.ts), checks the staged tree
+ * with the same static checks the exit drill uses, then decides a gate. The
+ * gate is `workspace-exit/<scope>` on the gate ledger and binds the digest of
+ * the patch, as `workspace upgrade` does: the first run records the pending
+ * fact and exits 3; after `chant approve workspace-exit <scope>` the same
+ * command stages the same patch and applies it to the tree.
+ *
+ * `--drill` skips the worktree and the gate: it runs the exit on a scratch
+ * copy and prints the per-member result, the check CI runs on every commit.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { approveCommand, describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { WORKSPACE_EXIT_GATE_OP } from "../op/gate-name";
+import { findWorkspaceRoot } from "../project-root";
+import { describeDrill, ExitError, exitInDir, planExit, runExitDrill, verifyExit, type DrillReport, type ExitBuildRunner, type ExitResult } from "./exit";
+import { spawnChant } from "./lineage-upgrade";
+
+const USAGE = "chant workspace exit [<member>...] [--member <name>] [--dry-run] [--drill] [--output <patch file>] [--json]";
+
+/** The exit code of a gated exit: the same as `chant run`'s gated run. */
+export const EXIT_GATED = 3;
+
+const EXIT_DIR = ".chant/exit";
+
+export interface ExitCommandOptions {
+  root: string;
+  members?: string[];
+  dryRun?: boolean;
+  drill?: boolean;
+  output?: string;
+  json?: boolean;
+  /** For tests. */
+  runBuild?: ExitBuildRunner;
+  ledger?: GateLedgerPort;
+  now?: string;
+}
+
+export type ExitOutcome = "drill" | "nothing-to-exit" | "checks-failed" | "dry-run" | "gated" | "applied";
+
+export interface ExitCommandResult {
+  outcome: ExitOutcome;
+  exitCode: number;
+  result?: ExitResult;
+  report?: DrillReport;
+  digest?: string;
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+
+const defaultBuild: ExitBuildRunner = (command, cwd, args) => spawnChant(command, cwd, args);
+
+export async function exitCommand(opts: ExitCommandOptions): Promise<ExitCommandResult> {
+  const runBuild = opts.runBuild ?? defaultBuild;
+  const names = opts.members ?? [];
+  const print = (lines: string[]) => {
+    if (!opts.json) console.log(lines.join("\n"));
+  };
+
+  if (opts.drill) {
+    const report = await runExitDrill({ root: opts.root, members: names, runBuild });
+    if (opts.json) console.log(JSON.stringify({ outcome: "drill", ...report }, null, 2));
+    else print(describeDrill(report));
+    return { outcome: "drill", exitCode: report.ok ? 0 : 1, report };
+  }
+
+  let repo: string;
+  let head: string;
+  try {
+    repo = git(opts.root, ["rev-parse", "--show-toplevel"]).trim();
+    head = git(opts.root, ["rev-parse", "HEAD"]).trim();
+  } catch {
+    throw new ExitError("chant workspace exit stages its change in a git worktree, so the project must be in a git repository with at least one commit");
+  }
+  const dirty = git(repo, ["status", "--porcelain", "--untracked-files=all"])
+    .split("\n")
+    .filter(Boolean)
+    .filter((l) => !l.slice(3).includes(`${EXIT_DIR}/`));
+  if (dirty.length > 0) {
+    throw new ExitError(`the tree has uncommitted changes (${dirty.slice(0, 5).map((l) => l.slice(3)).join(", ")}${dirty.length > 5 ? ", ..." : ""}). Commit them: the exit stages from HEAD and applies its patch to the tree.`);
+  }
+  const rel = relative(repo, opts.root).split(sep).join("/");
+  const holder = join(opts.root, EXIT_DIR);
+  mkdirSync(holder, { recursive: true });
+  const worktree = mkdtempSync(join(holder, "wt-"));
+  rmSync(worktree, { recursive: true, force: true });
+  git(repo, ["worktree", "add", "--detach", "-q", worktree, head]);
+  const dispose = () => {
+    try {
+      git(repo, ["worktree", "remove", "--force", worktree]);
+    } catch {
+      rmSync(worktree, { recursive: true, force: true });
+    }
+  };
+  try {
+    const project = rel ? join(worktree, rel) : worktree;
+    const plan = planExit(project, names);
+    const result = await exitInDir(plan, runBuild);
+    const report = verifyExit(project, result);
+    git(worktree, ["add", "-A"]);
+    const patch = git(worktree, ["diff", "--cached", "--binary", "HEAD"]);
+    const digest = `sha256:${createHash("sha256").update(patch).digest("hex").slice(0, 16)}`;
+
+    if (opts.json) {
+      // printed once, below
+    } else {
+      print(describeExit(result, digest));
+      print(describeDrill(report));
+    }
+    const out = (outcome: ExitOutcome, exitCode: number, extra: Record<string, unknown> = {}): ExitCommandResult => {
+      if (opts.json) console.log(JSON.stringify({ outcome, digest, ...result, report, ...extra }, null, 2));
+      return { outcome, exitCode, result, report, digest };
+    };
+
+    if (opts.output) writeFileSync(resolve(opts.output), patch);
+    if (!patch) {
+      if (!opts.json) console.error(formatInfo("nothing to exit: no member changed"));
+      return out("nothing-to-exit", 0);
+    }
+    if (!report.ok) {
+      if (!opts.json) console.error(formatError({ message: "the exit was not gated: its checks must pass first. The tree is unchanged." }));
+      return out("checks-failed", 1);
+    }
+    if (opts.dryRun) {
+      if (!opts.json) console.error(formatInfo("--dry-run: staged and checked; no gate recorded, the tree is unchanged"));
+      return out("dry-run", 0);
+    }
+
+    const gate = names.length > 0 ? names.join("+") : "workspace";
+    const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: repo }), {
+      op: WORKSPACE_EXIT_GATE_OP,
+      gate,
+      description: `leave chant: ${gate}`,
+      planDigest: digest,
+      ...(opts.now ? { now: opts.now } : {}),
+    });
+    if (!check.satisfied) {
+      if (!opts.json) {
+        const sealed = await gateIsSealed(gate);
+        if (check.mismatch) console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_EXIT_GATE_OP, gate, check.mismatch, sealed) }));
+        console.error(
+          formatInfo(
+            `Gated: the patch ${digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_EXIT_GATE_OP, gate, undefined, undefined, sealed)}\` and repeat this command to apply it.`,
+          ),
+        );
+      }
+      return out("gated", EXIT_GATED, { pending: check.pending });
+    }
+    applyPatch(repo, patch);
+    if (!opts.json) console.error(formatSuccess(`applied the approved exit (${digest}), approved by ${check.resolution.resolvedBy}. Review and commit it.`));
+    return out("applied", 0, { approvedBy: check.resolution.resolvedBy });
+  } finally {
+    dispose();
+  }
+}
+
+function applyPatch(repo: string, patch: string): void {
+  const dir = mkdtempSync(join(tmpdir(), "chant-exit-patch-"));
+  const file = join(dir, "exit.patch");
+  try {
+    writeFileSync(file, patch);
+    git(repo, ["apply", "--binary", "--whitespace=nowarn", file]);
+  } catch (err) {
+    const stderr = (err as { stderr?: Buffer | string }).stderr?.toString().trim();
+    throw new ExitError(`the approved patch no longer applies to the tree${stderr ? `: ${stderr}` : ""}`);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** One line per member, for the terminal. */
+export function describeExit(result: ExitResult, digest: string): string[] {
+  const lines: string[] = [];
+  for (const m of result.members) {
+    lines.push(`${m.name}  ${m.kind}  ${m.status}${m.detail ? ` (${m.detail})` : ""}`);
+    for (const n of m.native) lines.push(`  native: ${n}`);
+    for (const d of m.deploy) lines.push(`  deploy: ${d}`);
+    for (const c of m.ci) lines.push(`  ci: ${c}`);
+    for (const o of m.ops) lines.push(`  kept: ${o}`);
+    for (const s of m.steps) lines.push(`  step: ${s}`);
+  }
+  lines.push(`  patch: ${digest}`);
+  return lines;
+}
+
+export async function runWorkspaceExit(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  // positionals are ["exit", <member>...]
+  const named = [...(args.positionals ?? []).slice(1), ...(args.members ?? [])];
+  const root = findWorkspaceRoot(process.cwd())?.dir ?? process.cwd();
+  try {
+    const result = await exitCommand({
+      root,
+      members: [...new Set(named)],
+      dryRun: args.dryRun,
+      drill: args.drill,
+      output: args.output,
+      json: args.json,
+    });
+    return result.exitCode;
+  } catch (err) {
+    if (!(err instanceof ExitError)) throw err;
+    console.error(formatError({ message: err.message, hint: USAGE }));
+    return 1;
+  }
+}
+