@intentius/chant 0.124.13 → 0.124.14

package/dist/lifecycle/replay.js

@@ -0,0 +1,193 @@
+/**
+ * Replay a recorded snapshot as if it had just been observed (#1266, #1279).
+ *
+ * Shared by `chant search --at` and `chant graph --at`. A snapshot already holds
+ * what an observation is — resources with their physical ids and attributes,
+ * and since #1266 the relationships between them — so turning it back into
+ * `LiveObservation[]` lets a replay rejoin the live path at `buildLiveGraphIr`.
+ * Every fold, overlay and edge reconstruction below that point is shared, and
+ * nothing downstream needs to know which source it got.
+ *
+ * That sharing is the reason this is a module rather than a helper inside one
+ * command: `graph` had no `--at` at all, so anyone wanting the raw IR of a
+ * recorded estate had to reach for the live endpoint, and a snapshot could
+ * answer most questions but never all of them.
+ */
+import { readEnvironmentSnapshots } from "./git.js";
+import { unqualifiedKey } from "./identity.js";
+/**
+ * Rebuild observations from a recorded snapshot (#1266).
+ *
+ * A snapshot already holds what an observation is: resources with their
+ * physical ids and attributes, and — since #1266 — the relationships between
+ * them. Turning it back into `LiveObservation[]` means the replay rejoins the
+ * live path at `buildLiveGraphIr`, and every fold, overlay and query below that
+ * is shared. Nothing downstream needs to know which source it got.
+ *
+ * `latest` is the only ref for now. A specific commit is the natural extension
+ * and the storage already supports it (`readSnapshotAt`), but "answer from what
+ * is recorded" is the question worth settling first.
+ */
+/**
+ * Whether this environment has a recording, without reading one.
+ *
+ * Used to turn "the estate could not be read" into "the estate could not be
+ * read, and you already have a recording of it". Cheap and best-effort: a
+ * failure here means the caller says the plain version of the message, never
+ * that the command fails.
+ */
+export async function hasSnapshot(environment) {
+    try {
+        return (await readEnvironmentSnapshots(environment)).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function replaySnapshots(environment, ref, scopedStacks) {
+    if (ref !== "latest" && ref !== "true") {
+        return {
+            error: `chant search --at only accepts "latest" for now, got "${ref}"`,
+            hint: "a specific snapshot commit is not wired up yet",
+        };
+    }
+    const stored = await readEnvironmentSnapshots(environment);
+    if (stored.size === 0) {
+        return {
+            error: `No snapshots found for environment "${environment}"`,
+            hint: `Record one first: chant lifecycle snapshot ${environment}`,
+        };
+    }
+    const observations = [];
+    let commit = "";
+    let timestamp = "";
+    // "deep" when ANY recorded lexicon read that deep — a consumer comparing
+    // against this replay (#1268) needs to know a richer record exists, even
+    // though a replay itself only ever turns `resources` back into identity.
+    let depth = "identity";
+    // Ambient and dependency resources are keyed by physical id and are
+    // account-level: the default security group three stacks each recorded is one
+    // group, not three. Managed resources are stack-qualified below and cannot
+    // collide, so only the unqualified ones need this.
+    //
+    // "Account-level" is the part that needed qualifying (#1416): a resource that
+    // records a region is regional, and two regions' copies are two resources
+    // however equal their ids look. `unqualifiedKey` keys those by region, so the
+    // set below still collapses one region's resource seen from two stacks and no
+    // longer collapses two regions'.
+    const seenUnqualified = new Set();
+    // One recorded stack is one region, so there is nothing to merge and nothing
+    // to disambiguate — its ids stay exactly what they were recorded as, which is
+    // also what `chant search --live` gives that project.
+    const merging = stored.size > 1;
+    // A stack's snapshot could only exclude what THAT stack manages, so a stack
+    // declaring no security groups reported the neighbouring stack's as ambient.
+    // The union is only knowable here, with every snapshot in hand.
+    const managedPhysicalIds = new Set();
+    // Where a managed resource ends up, by physical id. A duplicate is dropped
+    // below rather than rendered twice, and anything that pointed at the
+    // duplicate has to be re-pointed at the survivor — dropping the node alone
+    // would take its edges with it, since `buildLiveGraphIr` discards an edge
+    // whose endpoints were not both observed.
+    const managedKeyOf = new Map();
+    for (const content of stored.values()) {
+        const snap = JSON.parse(content);
+        const snapStack = snap.stack;
+        const snapQualifies = snapStack !== undefined && scopedStacks.has(snapStack);
+        for (const [id, meta] of Object.entries(snap.resources ?? {})) {
+            if (!meta.ambient && !meta.referencedBy?.length && meta.physicalId) {
+                managedPhysicalIds.add(meta.physicalId);
+                managedKeyOf.set(meta.physicalId, snapQualifies ? `${snapStack}::${id}` : id);
+            }
+        }
+    }
+    for (const [key, content] of stored) {
+        const snapshot = JSON.parse(content);
+        // The storage key is `<stack>__<lexicon>` for a multi-stack project; the
+        // snapshot carries its own lexicon, which is the one to trust.
+        const lexicon = snapshot.lexicon ?? key;
+        // A scoped stack's ids are qualified `${stack}::${id}` on the live path
+        // (#1162), because the same bare LogicalResourceId exists in every region's
+        // stack. A snapshot stores them bare, so a replay has to re-apply the same
+        // rule — otherwise `server` from us-west-1 and `server` from us-west-2
+        // collide, and none of them join the declared canvas, which qualifies.
+        const stack = snapshot.stack;
+        const qualify = stack !== undefined && scopedStacks.has(stack);
+        // Dependencies (#1273) and ambient resources (#1278) are keyed by physical
+        // id and are NOT stack-qualified: the default VPC's route table is one
+        // resource however many stacks route through it, and qualifying it would
+        // split it per stack and break the edges into it.
+        const unqualifiedByNature = (meta) => Boolean(meta.ambient) || Boolean(meta.referencedBy && meta.referencedBy.length > 0);
+        // Region qualification (#1416) applies to exactly those, and never to a
+        // managed resource: an unscoped project's declared canvas joins on bare
+        // ids, so re-keying `web` to `us-east-1::web` would unjoin it from its own
+        // declaration.
+        const keyOf = (id, meta) => {
+            if (unqualifiedByNature(meta))
+                return merging ? unqualifiedKey(id, meta) : id;
+            return qualify ? `${stack}::${id}` : id;
+        };
+        const resources = {};
+        // Duplicates dropped here, and where they went, so edges can follow.
+        const merged = new Map();
+        for (const [id, meta] of Object.entries(snapshot.resources ?? {})) {
+            const key = keyOf(id, meta);
+            if (!qualify || unqualifiedByNature(meta)) {
+                // Ambient means "nothing manages this", and being referenced means "the
+                // estate reaches this" — neither stops it being managed. When a stack
+                // manages the same physical resource, this entry is that resource seen
+                // from outside, and rendering both inflates any count over it.
+                //
+                // The dependency half of that was missing, and it was not cosmetic: a
+                // subnet declared by its stack was also recorded as `subnet-9af06b90`
+                // with `referencedBy`, so an estate with 13 subnets replayed as 16 and
+                // "which subnets have no network interfaces" answered 11 where the
+                // truth was 8. The three extra were occupied subnets whose second copy
+                // had no interface pointing at it — a duplicate reads as empty, because
+                // the edges resolved to the other one.
+                const duplicate = Boolean(meta.ambient) || Boolean(meta.referencedBy && meta.referencedBy.length > 0);
+                if (duplicate && meta.physicalId && managedPhysicalIds.has(meta.physicalId)) {
+                    const survivor = managedKeyOf.get(meta.physicalId);
+                    if (survivor && survivor !== key)
+                        merged.set(id, survivor);
+                    continue;
+                }
+                // Unqualified: one resource per key, so first sighting wins and the
+                // rest are the same resource seen again from another stack's snapshot.
+                // The key carries the region when there is one, so "the same resource"
+                // no longer spans regions.
+                if (seenUnqualified.has(key))
+                    continue;
+                seenUnqualified.add(key);
+            }
+            resources[key] = meta;
+        }
+        const known = new Set(Object.keys(snapshot.resources ?? {}));
+        const requalify = (id) => {
+            // A dropped duplicate's edges belong to the resource that survived it.
+            const survivor = merged.get(id);
+            if (survivor)
+                return survivor;
+            const meta = (snapshot.resources ?? {})[id];
+            return known.has(id) && meta ? keyOf(id, meta) : id;
+        };
+        const edges = (snapshot.edges ?? []).map((e) => ({ ...e, from: requalify(e.from), to: requalify(e.to) }));
+        observations.push({
+            lexicon,
+            resources,
+            ...(edges.length > 0 ? { edges } : {}),
+            ...(snapshot.stackExports && Object.keys(snapshot.stackExports).length > 0
+                ? { stackExports: snapshot.stackExports }
+                : {}),
+        });
+        commit || (commit = snapshot.commit ?? "");
+        // Report the OLDEST timestamp across stacks: a caller asking how stale this
+        // answer is wants the weakest link, not the freshest one.
+        if (!timestamp || (snapshot.timestamp && snapshot.timestamp < timestamp)) {
+            timestamp = snapshot.timestamp ?? timestamp;
+        }
+        if (snapshot.depth === "deep")
+            depth = "deep";
+    }
+    return { observations, commit, timestamp, depth };
+}

package/dist/lifecycle/rollback.js

@@ -0,0 +1,102 @@
+/**
+ * lifecycle rollback (#873) — open a PR that restores the source to a prior git
+ * revision. Rollback = make an env match a past state of the declared source; the
+ * PR's diff *is* the rollback delta. No cloud mutation here — a human merges, then
+ * the existing gated apply rolls the env back.
+ *
+ * Runs entirely in an isolated `git worktree` (like {@link ./affected}), so the
+ * caller's working branch/tree is never touched — important because the consumer
+ * (behold) serves a live checkout.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ghHostEnv } from "../op/activities/gh-host.js";
+import { restPullRequestForge } from "../op/activities/forge-pull-request.js";
+const execFileAsync = promisify(execFile);
+/** Branch name for a rollback PR. Pure. */
+export function rollbackBranchName(env, shortRef) {
+    return `chant/rollback-${env ?? "src"}-${shortRef}`;
+}
+/** PR title for a rollback. Pure. */
+export function rollbackTitle(env, ref) {
+    return `rollback ${env ? env + " " : ""}source to ${ref}`;
+}
+/** PR body — explains that merging + applying completes the rollback. Pure. */
+export function rollbackBody(env, ref, sourceDir) {
+    const target = env ? `the ${env} environment` : "the environment";
+    return (`Restores \`${sourceDir}\` to its state at \`${ref}\`.\n\n` +
+        `The diff below is the rollback delta. Merge this PR, then apply (Sync) to roll ${target} back — ` +
+        `a destructive apply still passes through its approval gate. No cloud change was made by opening this PR.`);
+}
+/**
+ * Open a rollback PR restoring `sourceDir` to `ref`. Isolated worktree; the
+ * caller's branch is untouched. Throws on an unknown ref or a git/gh failure.
+ *
+ * `dryRun` computes the same delta and returns it as a diff without pushing a
+ * branch or opening a PR, leaving the repository exactly as it found it.
+ *
+ * That mode exists because the PR path needs a GitHub remote and an
+ * authenticated `gh` — reasonable for the operator flow this was built for
+ * (#873), and impossible for a hermetic acceptance run. chant#1208's CC
+ * round-trip has to demonstrate rollback offline, on an emulator, with no
+ * remote in the picture; without this it could only assert the `noop` case,
+ * which exercises none of the interesting work.
+ */
+export async function rollbackToRevision(opts) {
+    const { ref, env, sourceDir, cwd, dryRun } = opts;
+    const git = (args, wd) => execFileAsync("git", args, { cwd: wd });
+    const repoRoot = (await git(["rev-parse", "--show-toplevel"], cwd)).stdout.trim();
+    // Verify the ref resolves to a commit (throws with a clear message otherwise).
+    await execFileAsync("git", ["rev-parse", "--verify", `${ref}^{commit}`], { cwd: repoRoot });
+    const shortRef = (await git(["rev-parse", "--short", ref], repoRoot)).stdout.trim();
+    const branch = rollbackBranchName(env, shortRef);
+    const wt = join(tmpdir(), `chant-rollback-${shortRef}-${process.pid}`);
+    await git(["worktree", "add", wt, "-b", branch, "HEAD"], repoRoot);
+    try {
+        // Restore the source tree to the target revision (stages the changes).
+        //
+        // `git checkout <ref> -- <dir>` alone is a PER-PATH checkout, not a tree
+        // replacement: it restores the paths that exist at `ref` and leaves
+        // everything else untouched, so a file added since `ref` survives. That
+        // made rollback report "nothing to roll back" whenever the only difference
+        // was added files (#1327) — which is exactly what a reconcile produces,
+        // since `chant import --from <env>` writes NEW files rather than editing
+        // the authored ones. Clearing the directory first makes this a real
+        // restore, so the deletions show up in the delta.
+        await git(["rm", "-rq", "--ignore-unmatch", "--", sourceDir], wt);
+        await git(["checkout", ref, "--", sourceDir], wt);
+        const staged = (await git(["status", "--porcelain", "--", sourceDir], wt)).stdout.trim();
+        if (!staged)
+            return { noop: true };
+        // The delta, before committing: `git diff` against the index shows exactly
+        // what restoring the source to `ref` changes. A dry run stops here.
+        if (dryRun) {
+            const { stdout } = await git(["diff", "--cached", "--", sourceDir], wt);
+            return { noop: false, branch, diff: stdout };
+        }
+        await git(["commit", "-m", rollbackTitle(env, ref)], wt);
+        await git(["push", "-u", "origin", branch], wt);
+        // `gh pr` speaks GraphQL, which Forgejo does not serve: a Forgejo or
+        // GitLab job opens the pull request over REST (#3798).
+        const forge = await restPullRequestForge(process.env, { cwd: wt });
+        if (forge) {
+            const pr = await forge.openPullRequest({ head: branch, title: rollbackTitle(env, ref), body: rollbackBody(env, ref, sourceDir) });
+            return { noop: false, branch, prUrl: pr.url ?? "" };
+        }
+        // `gh pr create` names no host: tell it the one `origin` is on, or the
+        // CI job's forge, so a GitHub Enterprise Server checkout is not sent to
+        // github.com (#3780).
+        const { stdout } = await execFileAsync("gh", ["pr", "create", "--title", rollbackTitle(env, ref), "--body", rollbackBody(env, ref, sourceDir), "--head", branch], { cwd: wt, env: await ghHostEnv(process.env, wt) });
+        return { noop: false, branch, prUrl: stdout.trim() };
+    }
+    finally {
+        await git(["worktree", "remove", "--force", wt], repoRoot).catch(() => { });
+        // Removing the worktree leaves its branch behind. For the PR path that is
+        // correct — the branch is the PR. A dry run must leave nothing, or a repo
+        // accumulates a `chant/rollback-*` branch per inspection.
+        if (dryRun)
+            await git(["branch", "-D", branch], repoRoot).catch(() => { });
+    }
+}

package/dist/lifecycle/run-ledger.js

@@ -0,0 +1,183 @@
+/**
+ * Op run ledger (#2118, epic #2114) — one immutable record per Op run, on the
+ * `chant/lifecycle` orphan branch, modelled on `./converge-ledger.ts` down to
+ * the CAS-retry loop and the "skip a malformed line, count it" reader.
+ *
+ * ## Why an Op run leaves a record at all
+ *
+ * `OpConfig` used to carry `searchAttributes`, and the generated orchestrator
+ * code upserted `Phase`, `Drift`, `Approver` and `RollbackFailed` into them as
+ * it ran. Those are not properties of the declaration — they are facts about
+ * one run, and they only existed while a cluster held the run's history. Ops
+ * now run on whatever runtime `chant run --on`
+ * selects (#2121), including the plain in-process one, so the outcome has to
+ * be durable somewhere chant owns. Here. What stayed on the declaration is
+ * `OpConfig.labels`, the discovery half of the same field, and it is copied
+ * onto every record so a reader can filter runs the way it filters
+ * declarations.
+ *
+ * The record shape itself lives in `../op/runtime.ts`, beside the provider
+ * contract that reads it back: this is the ledger, not the vocabulary.
+ *
+ * ## Storage
+ *
+ * `<env>/runs__<op>.jsonl`, beside `<env>/converge.jsonl`. The `runs__`
+ * prefix folds what would read as a `runs/` subdirectory into one path
+ * segment: `writeBlobToPath` (./git.ts) builds the orphan branch's tree with
+ * `git mktree` over a flat `<env>/<file>` layout, and mktree rejects a slash
+ * in an entry name outright, so a genuine third level would mean rewriting
+ * that function's tree assembly. `__` is the same separator `./git.ts`'s
+ * `snapshotKey` already uses to fold a stack name into a flat blob name.
+ *
+ * Per-op rather than one file per env because a run ledger's reader almost
+ * always wants one op's history (`chant run <op>`'s own record, the local
+ * runtime's `status`/`log`), and an env with a busy op should not make every
+ * other op's read proportional to it.
+ */
+import { randomUUID } from "node:crypto";
+import { sortedJsonReplacer } from "../utils.js";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git.js";
+/** Prefix folding the per-op run ledgers into one flat name under `<env>/`. See the module doc. */
+const PREFIX = "runs__";
+/** Read-modify-append retry budget, same shape and reasoning as `appendConvergeRecord`'s. */
+const APPEND_RETRY_ATTEMPTS = 5;
+/** The env a run records against when its Op declares no `labels.Env`. */
+export const DEFAULT_RUN_ENV = "local";
+function fileFor(op) {
+    return `${PREFIX}${op}.jsonl`;
+}
+/** The env a run records against: the Op's own `labels.Env`, else {@link DEFAULT_RUN_ENV}. */
+export function runEnvOf(config) {
+    return config.labels?.Env ?? DEFAULT_RUN_ENV;
+}
+function phaseStatus(steps) {
+    if (steps.some((s) => s.status === "fail"))
+        return "fail";
+    if (steps.length > 0 && steps.every((s) => s.status === "skipped"))
+        return "skipped";
+    return "ok";
+}
+/**
+ * Fold a run's step records into the ledger shape, pure — no clock, no git.
+ * `started`/`ended` are supplied by the caller for the same reason
+ * `ConvergeTickRecord.timestamp` is: library code here never calls
+ * `Date.now()` itself.
+ *
+ * Phases are grouped by `StepRecord.phase` in first-seen order, which is
+ * execution order for the sequential path and the authored order for a
+ * parallel one. A compensation (`onFailure`) phase appears after the phase
+ * that failed, exactly where the executor emitted its records.
+ */
+export function buildRunRecord(config, records, times) {
+    const phases = [];
+    const byName = new Map();
+    const outcomes = {};
+    for (const record of records) {
+        let phase = byName.get(record.phase);
+        if (!phase) {
+            phase = { name: record.phase, status: "ok", steps: [] };
+            byName.set(record.phase, phase);
+            phases.push(phase);
+        }
+        phase.steps.push({
+            fn: record.fn,
+            status: record.status,
+            durationMs: record.durationMs,
+            ...(record.outcome ? { outcome: record.outcome } : {}),
+            ...(record.approval ? { approval: record.approval } : {}),
+            ...(record.error !== undefined ? { error: record.error } : {}),
+            ...(record.refusal !== undefined ? { refusal: record.refusal } : {}),
+            ...(record.point ? { point: record.point } : {}),
+            ...(record.gate ? { gate: record.gate } : {}),
+        });
+        if (record.outcome)
+            outcomes[record.outcome.name] = record.outcome.value;
+    }
+    for (const phase of phases) {
+        phase.status = phaseStatus(phase.steps);
+        const ms = times.phaseDurations?.[phase.name];
+        if (ms !== undefined)
+            phase.durationMs = ms;
+    }
+    return {
+        ...(times.id !== undefined ? { id: times.id } : {}),
+        op: config.name,
+        env: runEnvOf(config),
+        started: times.started,
+        ended: times.ended,
+        status: times.status,
+        labels: { ...(config.labels ?? {}) },
+        outcomes,
+        phases,
+        ...(times.gate ? { gate: times.gate } : {}),
+        ...(times.point ? { point: times.point } : {}),
+        ...(times.steward ? { steward: times.steward } : {}),
+    };
+}
+/**
+ * Append one immutable run record. Does not push to the remote — call
+ * `pushLifecycle` (./git.ts) afterward, the two-step shape every ledger here
+ * uses.
+ *
+ * Mints `record.id` when the input carries none, and retries the whole
+ * read-modify-write on `RefCASConflictError` re-reading fresh each attempt —
+ * see `appendConvergeRecord`'s doc for why both of those live in the append
+ * function rather than in its callers.
+ */
+export async function appendRunRecord(input, opts) {
+    const record = { version: 1, ...input, id: input.id ?? randomUUID() };
+    const json = JSON.stringify(record, sortedJsonReplacer);
+    const filename = fileFor(record.op);
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const priorSha = await readPathSha(record.env, filename, opts);
+            const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+            const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${json}\n`;
+            const commit = await writeBlobToPath(record.env, filename, content, `Op run record: ${record.op}`, {
+                ...opts,
+                expectPriorPathSha: priorSha,
+            });
+            return { commit, record };
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Read every run record for `op` in `environment`, oldest first. Malformed
+ * lines are skipped and counted, never thrown on — a hand-edited or truncated
+ * ledger degrades to a shorter history, the stance every ledger here takes.
+ */
+export async function readRunLedger(environment, op, opts) {
+    const content = await readBlobFromPath(environment, fileFor(op), opts);
+    if (!content)
+        return { records: [], malformed: 0 };
+    const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+    const records = [];
+    let malformed = 0;
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.version !== 1 ||
+                typeof parsed.op !== "string" ||
+                typeof parsed.env !== "string" ||
+                typeof parsed.started !== "string" ||
+                typeof parsed.ended !== "string" ||
+                typeof parsed.status !== "string" ||
+                !Array.isArray(parsed.phases)) {
+                malformed++;
+                continue;
+            }
+            records.push(parsed);
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { records, malformed };
+}