@intentius/chant 0.124.13 → 0.124.14

package/dist/lifecycle/teardown.js

@@ -0,0 +1,255 @@
+/**
+ * Teardown planning (#1222) — the enumeration half of
+ * `chant lifecycle teardown <env>`.
+ *
+ * Answers one question: which live resources carry THIS project's ownership
+ * marker for THIS environment? Selection is marker-scoped by construction —
+ * managed-by present, stack equal to the project's `ownership.stack`, env
+ * equal to the argument — so a foreign stack's resources, another env's
+ * resources, and unmarked resources are out of scope by shape, not by
+ * filtering discipline someone has to remember.
+ *
+ * Stateless: live markers only. No build, no snapshot, no ledger — the
+ * ownership record lives on the cloud resource (see ../ownership.ts), and this
+ * module reads it back from there.
+ *
+ * Two paths per lexicon:
+ * - the `teardownOwned` capability, where the lexicon enumerates its own
+ *   would-delete set (and can use a read shaped for deletion — aws's
+ *   stack-level path, k8s's prune selector);
+ * - a fallback over `describeResources` + the {@link ResourceMetadata.marker}
+ *   field (#1222 PR 1), for lexicons that have not implemented the capability
+ *   yet. Best-effort: a lexicon whose thin read only resolves declared names
+ *   returns nothing here, which the plan reports as a skip, not as clean.
+ *
+ * Whichever path ran, core re-checks every candidate's marker and drops
+ * mismatches — an implementation bug can narrow the set, never widen it.
+ *
+ * The execution half is {@link executeTeardown}: it drives each lexicon's
+ * `executeTeardown` capability over the planned set, then runs one bounded
+ * retry pass over the failures. Both halves are exported as functions —
+ * #1224's test-env harness calls them in-process, not only through the verb.
+ */
+import { normalizeObservation, unobservedAll } from "../observation.js";
+/** True when `marker` is exactly the identity this plan selects on. */
+function markerMatches(marker, stack, env) {
+    return marker !== undefined && marker.stack === stack && marker.env === env;
+}
+/**
+ * Enumerate what `chant lifecycle teardown <env>` would delete. Read-only —
+ * this function never deletes and never will; execution composes on top of the
+ * plan it returns.
+ */
+export async function planTeardown(opts) {
+    const marker = { stack: opts.stack, env: opts.environment };
+    const entries = [];
+    const holes = [];
+    const skipped = [];
+    for (const plugin of opts.plugins) {
+        if (plugin.teardownOwned) {
+            let enumeration;
+            try {
+                enumeration = await plugin.teardownOwned({
+                    environment: opts.environment,
+                    marker,
+                    ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+                    ...(opts.region ? { region: opts.region } : {}),
+                    ...(opts.deployedStacks && opts.deployedStacks.length > 0 ? { stacks: opts.deployedStacks } : {}),
+                });
+            }
+            catch (err) {
+                // A failed enumeration is a hole over the whole lexicon, not a clean
+                // lexicon (#1089): nothing was read, so nothing is known.
+                holes.push({
+                    lexicon: plugin.name,
+                    name: "*",
+                    reason: "read-failed",
+                    detail: err instanceof Error ? err.message : String(err),
+                });
+                continue;
+            }
+            for (const candidate of enumeration.candidates) {
+                // Defense in depth: the contract says every candidate carries the
+                // requested identity; a candidate that does not is dropped here so an
+                // implementation bug cannot widen the delete set.
+                if (!markerMatches(candidate.marker, opts.stack, opts.environment))
+                    continue;
+                entries.push({ lexicon: plugin.name, ...candidate });
+            }
+            for (const hole of enumeration.holes ?? []) {
+                holes.push({ lexicon: plugin.name, ...hole });
+            }
+            continue;
+        }
+        if (plugin.describeResources) {
+            let observed;
+            try {
+                observed = normalizeObservation(await plugin.describeResources({
+                    environment: opts.environment,
+                    buildOutput: "",
+                    entityNames: [],
+                    entities: new Map(),
+                    owned: true,
+                    ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+                    ...(opts.region ? { region: opts.region } : {}),
+                }));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                observed = {
+                    resources: {},
+                    unobserved: unobservedAll(["*"], "read-failed", message),
+                    queried: {},
+                    notes: [],
+                };
+            }
+            for (const [name, meta] of Object.entries(observed.resources)) {
+                // Marker-scoped by construction: no marker, foreign stack, or foreign
+                // env means not a candidate — a resource with no readable identity is
+                // never promoted to a delete.
+                if (!markerMatches(meta.marker, opts.stack, opts.environment))
+                    continue;
+                entries.push({
+                    lexicon: plugin.name,
+                    name,
+                    type: meta.type,
+                    ...(meta.physicalId ? { physicalId: meta.physicalId } : {}),
+                    marker: meta.marker,
+                });
+            }
+            for (const [name, u] of Object.entries(observed.unobserved)) {
+                holes.push({
+                    lexicon: plugin.name,
+                    name,
+                    ...(u.type ? { type: u.type } : {}),
+                    reason: u.reason,
+                    ...(u.detail ? { detail: u.detail } : {}),
+                });
+            }
+            continue;
+        }
+        skipped.push(plugin.name);
+    }
+    entries.sort((a, b) => a.lexicon.localeCompare(b.lexicon) || a.name.localeCompare(b.name));
+    return { environment: opts.environment, stack: opts.stack, entries, holes, skipped };
+}
+/**
+ * Run one execution pass over a lexicon's candidates and return exactly one
+ * outcome per candidate: what the lexicon reported, `failed` for anything it
+ * stayed silent about, and `failed` across the board when the call threw.
+ * Outcomes the lexicon volunteers for names core never asked about are
+ * dropped — an implementation cannot widen the set by reporting on it.
+ */
+async function executePass(plugin, candidates, opts, marker) {
+    const byName = new Map();
+    let reported;
+    try {
+        const execution = await plugin.executeTeardown({
+            environment: opts.environment,
+            marker,
+            candidates,
+            ...(opts.deployedStack ? { stack: opts.deployedStack } : {}),
+            ...(opts.region ? { region: opts.region } : {}),
+            ...(opts.deployedStacks && opts.deployedStacks.length > 0 ? { stacks: opts.deployedStacks } : {}),
+        });
+        reported = execution.outcomes;
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        for (const candidate of candidates) {
+            byName.set(candidate.name, { name: candidate.name, outcome: "failed", detail });
+        }
+        return byName;
+    }
+    const asked = new Set(candidates.map((c) => c.name));
+    for (const outcome of reported) {
+        if (!asked.has(outcome.name))
+            continue;
+        byName.set(outcome.name, outcome);
+    }
+    for (const candidate of candidates) {
+        if (byName.has(candidate.name))
+            continue;
+        byName.set(candidate.name, {
+            name: candidate.name,
+            outcome: "failed",
+            detail: "the lexicon reported no outcome for this candidate",
+        });
+    }
+    return byName;
+}
+/**
+ * Execute a teardown: delete every planned candidate through its lexicon's
+ * `executeTeardown`, then retry the failures once. Per-lexicon ordering only —
+ * each lexicon deletes its own set in the order its target requires (k8s
+ * deletes namespaces last, fly deletes apps last); there is no global
+ * reverse-dependency ordering in v1, the bounded retry pass covers the
+ * cross-lexicon cases it would.
+ *
+ * Every planned entry comes back with an outcome. A lexicon that enumerates
+ * but implements no execution reports its candidates as `skipped` — loudly,
+ * never as clean. Failures that survive the retry stay `failed` in the
+ * report; nothing here ever swallows one.
+ */
+export async function executeTeardown(opts) {
+    const marker = { stack: opts.stack, env: opts.environment };
+    const plan = opts.plan ?? (await planTeardown(opts));
+    const byLexicon = new Map();
+    for (const entry of plan.entries) {
+        const list = byLexicon.get(entry.lexicon) ?? [];
+        list.push(entry);
+        byLexicon.set(entry.lexicon, list);
+    }
+    const outcomes = [];
+    const unimplemented = [];
+    // Plugin registration order, so a project's lexicon ordering is stable.
+    for (const plugin of opts.plugins) {
+        const entries = byLexicon.get(plugin.name);
+        if (!entries)
+            continue;
+        byLexicon.delete(plugin.name);
+        if (!plugin.executeTeardown) {
+            unimplemented.push(plugin.name);
+            for (const entry of entries) {
+                outcomes.push({
+                    ...entry,
+                    outcome: "skipped",
+                    detail: `the ${plugin.name} lexicon does not implement teardown execution yet`,
+                });
+            }
+            continue;
+        }
+        const candidates = entries.map(({ lexicon: _lexicon, ...candidate }) => candidate);
+        const first = await executePass(plugin, candidates, opts, marker);
+        // One bounded retry pass over this lexicon's failures — transient errors
+        // and ordering hiccups get a second chance, nothing gets an infinite one.
+        const failedNames = new Set([...first.values()].filter((o) => o.outcome === "failed").map((o) => o.name));
+        const retried = failedNames.size > 0
+            ? await executePass(plugin, candidates.filter((c) => failedNames.has(c.name)), opts, marker)
+            : new Map();
+        for (const entry of entries) {
+            const second = retried.get(entry.name);
+            const outcome = second ?? first.get(entry.name);
+            outcomes.push({
+                ...entry,
+                outcome: outcome.outcome,
+                ...(outcome.detail !== undefined ? { detail: outcome.detail } : {}),
+                ...(second !== undefined ? { retried: true } : {}),
+            });
+        }
+    }
+    // A planned entry attributed to a lexicon that is not in `plugins` at
+    // execution time (a plan handed in from elsewhere). Nobody can delete it,
+    // and silence is never success.
+    for (const entries of byLexicon.values()) {
+        for (const entry of entries) {
+            outcomes.push({
+                ...entry,
+                outcome: "skipped",
+                detail: `no loaded lexicon named "${entry.lexicon}" to execute this candidate`,
+            });
+        }
+    }
+    outcomes.sort((a, b) => a.lexicon.localeCompare(b.lexicon) || a.name.localeCompare(b.name));
+    return { environment: opts.environment, stack: opts.stack, plan, outcomes, unimplemented };
+}

package/dist/lifecycle/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lifecycle/unobserved-gate.js

@@ -0,0 +1,33 @@
+import { unobservedReasonText } from "../observation.js";
+/**
+ * Evaluate a `ChangeSet`'s unobserved set against `policy`. Pure — reads only
+ * `cs.entries`, no I/O. Defaults to `"refuse"`.
+ */
+export function evaluateUnobservedGate(cs, policy = "refuse") {
+    const allowed = typeof policy === "object" ? new Set(policy.allow) : undefined;
+    const findings = [];
+    for (const e of cs.entries) {
+        if (e.action !== "unobserved" || e.unobservedReason === undefined)
+            continue;
+        if (allowed?.has(e.unobservedReason))
+            continue;
+        findings.push({
+            name: e.name,
+            ...(e.type ? { type: e.type } : {}),
+            reason: e.unobservedReason,
+            ...(e.unobservedDetail ? { detail: e.unobservedDetail } : {}),
+        });
+    }
+    if (findings.length === 0) {
+        return { pass: true, escalate: false, findings: [] };
+    }
+    const detail = `plan contains ${findings.length} unobserved ${findings.length === 1 ? "entity" : "entities"} — ` +
+        findings
+            .map((f) => `${f.name}${f.type ? ` (${f.type})` : ""}: ${unobservedReasonText(f.reason)}${f.detail ? ` (${f.detail})` : ""}`)
+            .join(", ");
+    if (policy === "escalate") {
+        return { pass: true, escalate: true, findings, detail };
+    }
+    // "refuse" (default) and `{ allow }` both fail closed on anything not allowed.
+    return { pass: false, escalate: false, findings, detail };
+}

package/dist/lifecycle/wave-plans.js

@@ -0,0 +1,68 @@
+/** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
+export const HEAD_PLANS_DIR = "_wave-plans";
+export function headPlansPath(name, head) {
+    return { dir: `${HEAD_PLANS_DIR}/${name}`, file: `${head}.json` };
+}
+/**
+ * Parse one record. Null when the text is not JSON or not a version 1 plans
+ * record: a record that cannot be read approves nothing.
+ */
+export function parseHeadPlans(text) {
+    if (!text)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (value === null || typeof value !== "object")
+        return null;
+    const r = value;
+    if (r.version !== 1 || typeof r.name !== "string" || typeof r.head !== "string" || typeof r.timestamp !== "string" || !Array.isArray(r.waves))
+        return null;
+    const waves = [];
+    for (const w of r.waves) {
+        if (w === null || typeof w !== "object")
+            return null;
+        const { wave, name, digest } = w;
+        if (typeof wave !== "number" || typeof name !== "string" || typeof digest !== "string")
+            return null;
+        waves.push({ wave, name, digest });
+    }
+    return { version: 1, name: r.name, head: r.head, timestamp: r.timestamp, waves };
+}
+/** The record for `head` of the spec `name`, or null when none was recorded or it cannot be read. */
+export async function readHeadPlans(port, name, head) {
+    const { dir, file } = headPlansPath(name, head);
+    return parseHeadPlans(await port.read(dir, file));
+}
+/** Every record of the spec `name` by head. A file that is not a record is left out. */
+export async function readAllHeadPlans(port, name) {
+    const out = new Map();
+    const { dir } = headPlansPath(name, "");
+    for (const file of (await port.list(dir)).sort()) {
+        if (!file.endsWith(".json"))
+            continue;
+        const plans = parseHeadPlans(await port.read(dir, file));
+        if (plans)
+            out.set(file.slice(0, -".json".length), plans);
+    }
+    return out;
+}
+/** The digests a record holds by wave number. */
+export function waveDigests(plans) {
+    return new Map(plans.waves.map((w) => [w.wave, w.digest]));
+}
+/** The digests recorded for each head of the spec `name`: head, then wave number, to digest. */
+export async function readHeadPlanDigests(port, name) {
+    const out = new Map();
+    for (const [head, plans] of await readAllHeadPlans(port, name))
+        out.set(head, waveDigests(plans));
+    return out;
+}
+/** The names of the specs that have records: the directories under `_wave-plans/`. */
+export async function listWavePlanSpecs(port) {
+    return (await port.list(HEAD_PLANS_DIR)).sort();
+}

package/dist/lifecycle/work-item-id.js

@@ -0,0 +1,36 @@
+/**
+ * What a work item id has to be to key a work lease (#2815). The id lands in
+ * refs (`refs/chant/lease/work/<id>`, `refs/chant/kept/.../<item>/<token>`,
+ * the work branch `chant/work/.../<id>`) and in a file name
+ * (`_leases/<id>.jsonl`), so it has to be a valid ref path segment under
+ * `git check-ref-format`, and git's check is stricter than a character class.
+ *
+ * Kept free of imports so `Op()`, `declareSteward` and the CLI can all call it
+ * without loading the lease machinery.
+ */
+/** The characters an id may use: letters, digits, ".", "_" and "-", starting with a letter or digit, at most 100. */
+export const WORK_ITEM_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+/**
+ * Why `id` can't key a work lease, or `undefined` when it can. On top of
+ * {@link WORK_ITEM_ID_PATTERN}, git refuses a ref component that has `..`,
+ * ends in `.`, or ends in `.lock` (git's own lock file for the ref; matched
+ * case-insensitively here since a case-folding filesystem would collide).
+ */
+export function workItemIdProblem(id) {
+    if (typeof id !== "string")
+        return `${JSON.stringify(id)} is not a string`;
+    if (!WORK_ITEM_ID_PATTERN.test(id)) {
+        return `${JSON.stringify(id)} can't key a work lease: use letters, digits, ".", "_" and "-", starting with a letter or digit, at most 100 characters`;
+    }
+    if (id.includes(".."))
+        return `${JSON.stringify(id)} can't key a work lease: git refuses ".." in a ref name`;
+    if (id.endsWith("."))
+        return `${JSON.stringify(id)} can't key a work lease: git refuses a ref name ending in "."`;
+    if (id.toLowerCase().endsWith(".lock"))
+        return `${JSON.stringify(id)} can't key a work lease: git refuses a ref name ending in ".lock"`;
+    return undefined;
+}
+/** Whether `id` can key a work lease. */
+export function isWorkItemId(id) {
+    return workItemIdProblem(id) === undefined;
+}