@intentius/chant 0.124.13 → 0.124.15

package/dist/op/activities/decide.js

@@ -0,0 +1,211 @@
+/**
+ * The `decide` Op activity (ws-058, #2740): ask a decision point for one set
+ * of inputs, calling the backend its model decider names, and record the
+ * answer. Core's own since #2828, next to the decision points it asks; the
+ * typed step builder is `decide` in `../builders.ts`.
+ *
+ * The point is asked through core's `askPointInRun` (#2749), which writes the
+ * answer with `askPoint` (`points ask`, #2739), the same path `chant workspace
+ * points ask --response` takes. So the chain, the threshold, a model's answer
+ * being `proposed` and never `answered`, the reuse of an answer the same point,
+ * declaration and inputs already have, the escalation to people, and what an
+ * open question does to the run all come from core:
+ *
+ * - an answered question (a table row, or a person) is the step's result, and
+ *   the Op goes on;
+ * - an escalated or proposed question is open, so the step throws core's
+ *   `PointWait` and the run ends `waiting`. A person answers with `points
+ *   answer` or through hud, and the next run reads the answer from the record.
+ *
+ * This activity adds three things: reading the inputs through the read
+ * contract (`../decide-read-inputs.ts`), the call to a `POST /v1/systemone`
+ * backend (`../decide-backend.ts`), and refusing a misconfigured backend before
+ * anything is asked or written. The backends are the step's own `backends`, or
+ * `decide.backends` in chant.config (`../decide-config.ts`).
+ *
+ * With the backend unreachable, the point's `unreachable` decides: `escalate`
+ * (the default) records the question open for people with the reason, and
+ * `fail` writes nothing and fails the step.
+ *
+ * In a steward's turn the model call goes through the broker (#2749): core
+ * makes it only through a capability the steward declares, and a backend whose
+ * key is an environment variable is not called, since that key would be a
+ * credential the steward holds.
+ *
+ * chant's reads never call a model (ws-052): this runs only as an Op step.
+ *
+ * The workspace code, the client and the read-contract reads load on first
+ * call, so importing core's activities loads nothing under `workspace/`
+ * (#2525 rule 5).
+ */
+import { loadChantConfig } from "../../config.js";
+import { askPointInRun, brokeredModelAsk, isPointWait } from "../steward-points.js";
+import { currentStewardTurn } from "../steward-turn.js";
+import { backendSchema } from "../decide-config.js";
+/** The step failed: what core refused, or a configuration this activity refuses. */
+export class DecideError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DecideError";
+    }
+}
+/** The backends the args give, or `decide.backends` from the chant.config in `cwd`. Each is checked; a literal key is refused. */
+async function backendsFor(args, cwd) {
+    const { checkKey, DecideConfigError } = await import("../decide-backend.js");
+    let raw = args.backends;
+    if (raw === undefined) {
+        const { config } = await loadChantConfig(cwd);
+        raw = config.decide?.backends ?? {};
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new DecideConfigError("backends must be an object of backend name to { url, key? }");
+    const out = {};
+    for (const [name, b] of Object.entries(raw)) {
+        checkKey(b?.key, `backend ${name}'s key`, cwd);
+        const parsed = backendSchema.safeParse(b);
+        if (!parsed.success)
+            throw new DecideConfigError(`backend ${name} is not { url, key?, timeoutMs? }: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(backend)"} ${i.message}`).join("; ")}`);
+        out[name] = parsed.data;
+    }
+    return out;
+}
+/** The point as `points --json` lists it, or a refusal. */
+async function pointFor(args, cwd) {
+    const { workspacePoints } = await import("../../workspace/points-cli.js");
+    const doc = await workspacePoints({ cwd, ...(args.kind !== undefined ? { kind: args.kind } : {}) });
+    if ("error" in doc)
+        throw new DecideError(doc.error.code, doc.error.message);
+    const point = doc.points.find((p) => p.name === args.point);
+    if (!point) {
+        const bad = doc.sources.find((s) => s.reason);
+        throw new DecideError("point-unknown", `no points file declares ${JSON.stringify(args.point)}${bad ? ` (${bad.kind}: ${bad.reason.message})` : doc.points.length ? ` (the points are ${doc.points.map((p) => p.name).join(", ")})` : ""}`);
+    }
+    return point;
+}
+function result(q, missing) {
+    const decider = typeof q.decider.kind === "string" ? q.decider.kind : "quorum";
+    const byModel = decider === "model";
+    return {
+        id: q.id,
+        path: q.path,
+        state: q.state,
+        open: q.open,
+        answer: q.answer,
+        decider,
+        model: byModel ? (q.model?.model ?? null) : null,
+        backend: byModel ? (q.model?.backend ?? null) : null,
+        confidence: byModel ? q.confidence : null,
+        threshold: byModel ? q.threshold : null,
+        reason: byModel ? q.reason : null,
+        answeredBy: q.answeredBy,
+        escalations: q.escalations,
+        missing,
+    };
+}
+/** Run the activity with its seams. {@link decide} is this with the real ones. */
+export async function runDecide(args, deps = {}, signal) {
+    if (typeof args?.point !== "string" || args.point === "")
+        throw new DecideError("write-usage-invalid", "decide needs the point's name");
+    const cwd = args.cwd ?? process.cwd();
+    const { backendAsk, brokeredCapability, checkKey, DecideConfigError } = await import("../decide-backend.js");
+    const configError = (f) => {
+        try {
+            return f();
+        }
+        catch (err) {
+            if (err instanceof DecideConfigError)
+                throw new DecideError("backend-invalid", err.message);
+            throw err;
+        }
+    };
+    let backends;
+    try {
+        backends = await backendsFor(args, cwd);
+    }
+    catch (err) {
+        if (err instanceof DecideConfigError)
+            throw new DecideError("backend-invalid", err.message);
+        throw err;
+    }
+    const point = await pointFor(args, cwd);
+    // Every model decider's backend is configured, and a brokered key's
+    // capability is declared with a broker, before anything is asked. The first
+    // brokered one names the capability a steward's call goes through.
+    let via;
+    for (const d of point.deciders) {
+        if (d.kind !== "model")
+            continue;
+        const backend = backends[d.backend];
+        if (!backend) {
+            throw new DecideError("backend-invalid", `${args.point}'s model decider names the backend ${d.backend}, and none is configured (decide.backends${Object.keys(backends).length ? `: ${Object.keys(backends).join(", ")}` : " is empty"})`);
+        }
+        configError(() => checkKey(backend.key, `backend ${d.backend}'s key`, cwd));
+        if (via === undefined && backend.key && "capability" in backend.key) {
+            const key = backend.key;
+            via = { capability: key.capability, broker: configError(() => brokeredCapability(key, cwd)).broker };
+        }
+    }
+    let read = { inputs: {}, missing: [] };
+    if (args.read && Object.keys(args.read).length > 0) {
+        try {
+            const { readInputs } = await import("../decide-read-inputs.js");
+            read = await readInputs(point.inputs.map((i) => i.name), args.read, cwd);
+        }
+        catch (err) {
+            throw new DecideError("point-inputs-invalid", err instanceof Error ? err.message : String(err));
+        }
+    }
+    const inputs = { ...read.inputs, ...(args.inputs ?? {}) };
+    const missing = read.missing.filter((m) => !(m in inputs));
+    const call = backendAsk({ backends, cwd, ...(deps.transport ? { transport: deps.transport } : {}), ...(deps.env ? { env: deps.env } : {}), ...(signal ? { signal } : {}), ...(deps.onResponse ? { onResponse: deps.onResponse } : {}) });
+    const turn = currentStewardTurn();
+    const ask = async (request) => {
+        const key = backends[request.backend]?.key;
+        if (turn && key && !("capability" in key)) {
+            throw new Error(`in the steward ${turn.steward}'s turn a model call goes through the broker, and backend ${request.backend}'s key is the environment variable ${key.env}, a credential the steward would hold`);
+        }
+        return call(request);
+    };
+    const common = {
+        cwd,
+        point: args.point,
+        inputs,
+        ...(args.subject !== undefined ? { subject: args.subject } : {}),
+        ...(args.kind !== undefined ? { kind: args.kind } : {}),
+        ...(args.store !== undefined ? { store: args.store } : {}),
+        ...(deps.on ? { on: deps.on } : {}),
+    };
+    if (args.dryRun) {
+        const { askPoint } = await import("../../workspace/decide.js");
+        const doc = await askPoint({
+            ...common,
+            ask: await brokeredModelAsk(ask, { ...(via ? via : {}), turn: turn ?? null, cwd }),
+            ...(turn ? { steward: { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } } : { client: { name: "chant decide" } }),
+            dryRun: true,
+        });
+        if ("error" in doc)
+            throw new DecideError(doc.error.code, `${doc.error.code}: ${doc.error.message}`);
+        return result(doc.question, missing);
+    }
+    try {
+        const { question } = await askPointInRun({ ...common, ask, ...(via ? { capability: via.capability, broker: via.broker } : {}), turn: turn ?? null });
+        return result(question, missing);
+    }
+    catch (err) {
+        // An open question is not a failure: the run waits on it (#2749).
+        if (isPointWait(err))
+            throw err;
+        const coded = err instanceof Error ? /^decision point [^:]+: ([a-z0-9-]+): /.exec(err.message) : null;
+        if (coded)
+            throw new DecideError(coded[1], err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+}
+/**
+ * Ask a decision point and record the answer. The Op activity: an answered
+ * question is the step's result, and an open one stops the run `waiting`.
+ */
+export async function decide(args, signal) {
+    return runDecide(args, {}, signal);
+}

package/dist/op/activities/env-teardown.js

@@ -0,0 +1,110 @@
+/**
+ * `envTeardown` — the durable form of `chant lifecycle teardown <env> --yes`
+ * (#1222).
+ *
+ * Wraps core's {@link executeTeardown}: enumerate the live resources whose
+ * ownership marker carries this project's `ownership.stack` + the requested
+ * environment, delete them through each lexicon's `executeTeardown`
+ * capability, run core's one bounded retry pass, and fail the activity loudly
+ * when any candidate is still `failed` afterwards. Selection is marker-scoped
+ * by construction — the same engine the CLI verb drives, reached in-process
+ * rather than through a shell.
+ *
+ * The guards are the CLI's guards, unchanged:
+ * - an environment the project does not declare is refused;
+ * - a project with no `ownership.stack` is refused — teardown has nothing to
+ *   select on;
+ * - a production-like environment name (`prod`, `production`, `prod-eu`, ...)
+ *   is refused unless the step's args carry an explicit `confirmProd: true`.
+ *   An Op is non-interactive, so there is no re-type-the-name prompt to fall
+ *   back to — the confirmation must be authored into the Op.
+ *
+ * All three refusals throw before any live read, so a refused teardown
+ * touches nothing at all. They are configuration errors, not transient ones —
+ * no retry can make `prod` stop looking like production.
+ *
+ * Distinct from {@link chantTeardown} (`npm run teardown`), which runs
+ * whatever script a project wired under that name. This activity is
+ * product-agnostic: it imports core only, and core reaches each product
+ * through the lexicons the project configures.
+ */
+import { resolve } from "node:path";
+import { loadChantConfig, resolveOwnershipStack } from "../../config.js";
+import { unknownEnvError, isProdLikeEnvironment } from "../../env.js";
+import { applyLiveEndpoint } from "../../live-endpoint.js";
+import { executeTeardown } from "../../lifecycle/teardown.js";
+/**
+ * Load the project's lexicon plugins through core's own resolution: the
+ * `lexicons` list in chant.config, falling back to source-file detection.
+ * A dynamic import so this module does not pull the whole CLI surface in at
+ * load time — the registry imports every activity module eagerly.
+ */
+async function loadProjectPlugins(projectPath) {
+    const { loadPlugins, resolveProjectLexicons } = await import("../../cli/plugins.js");
+    return loadPlugins(await resolveProjectLexicons(projectPath));
+}
+/**
+ * Tear down one environment's marker-owned resources through the core
+ * teardown engine. Uses the `longInfra` profile — deletion waits on the
+ * target's own pace. Safe to retry: the engine re-plans from live markers on
+ * every run, and a resource already gone is simply no longer a candidate.
+ */
+export async function envTeardown(args, _signal, deps) {
+    const projectPath = resolve(args.path ?? ".");
+    const config = deps?.config ?? (await loadChantConfig(projectPath)).config;
+    // Refuse an env the project does not declare — a typo here is the
+    // difference between tearing down `dev` and tearing down `prod`.
+    const envErr = unknownEnvError(args.env, config.environments);
+    if (envErr)
+        throw new Error(`envTeardown: ${envErr}`);
+    // Teardown selects on the ownership marker; a project that stamps none has
+    // nothing to key on, and "delete what looks like mine" is not a fallback.
+    const stack = resolveOwnershipStack(config);
+    if (stack === undefined) {
+        throw new Error("envTeardown: this project declares no ownership.stack — teardown is marker-scoped and has nothing to select on. " +
+            'Set `ownership: { stack: "<name>" }` in chant.config.ts and deploy, so resources carry the marker teardown keys on.');
+    }
+    // The prod guard (#1222). Checked before any live read, so a refused
+    // teardown touches nothing at all.
+    if (isProdLikeEnvironment(args.env) && args.confirmProd !== true) {
+        throw new Error(`envTeardown: "${args.env}" looks like a production environment — ` +
+            "add `confirmProd: true` to the envTeardown step's args to tear it down from an Op.");
+    }
+    const plugins = deps?.plugins ?? (await loadProjectPlugins(projectPath));
+    // #1166 — teardown is a live read and a live write, so an environment's
+    // declared endpoint applies here too, unless the ambient shell already set it.
+    const reading = plugins.filter((p) => p.teardownOwned || p.describeResources || p.executeTeardown);
+    const endpoint = applyLiveEndpoint(config.environments, args.env, reading);
+    if (endpoint.notice)
+        console.log(endpoint.notice);
+    let report;
+    try {
+        report = await executeTeardown({ environment: args.env, stack, plugins });
+    }
+    finally {
+        endpoint.restore();
+    }
+    const count = (outcome) => report.outcomes.filter((o) => o.outcome === outcome).length;
+    const deleted = count("deleted");
+    const failed = report.outcomes.filter((o) => o.outcome === "failed");
+    const notPrunable = count("not-prunable");
+    const skipped = count("skipped");
+    console.log(`envTeardown ${args.env} (stack ${stack}): ${deleted} deleted, ${failed.length} failed, ` +
+        `${notPrunable} not-prunable, ${skipped} skipped, ${report.plan.holes.length} hole(s)`);
+    // Failures that survived core's bounded retry pass fail the activity —
+    // silence is never success. A failed step is what the executor aborts the
+    // phase on and what the Op's `onFailure` compensation runs for.
+    if (failed.length > 0) {
+        const names = failed.map((o) => `${o.lexicon}/${o.name}${o.detail ? ` (${o.detail})` : ""}`).join(", ");
+        throw new Error(`envTeardown: ${failed.length} of ${report.outcomes.length} candidate(s) still failed after the retry pass: ${names}`);
+    }
+    return {
+        environment: args.env,
+        stack,
+        deleted,
+        notPrunable,
+        skipped,
+        holes: report.plan.holes.length,
+        report,
+    };
+}