@intentius/chant-lexicon-terraform 0.124.31 → 0.124.32

package/dist/op/activity-contracts.js

@@ -0,0 +1,162 @@
+/**
+ * Activity contracts for this lexicon's own `op/activities` (chant #2101).
+ *
+ * The schema-shaped sibling of `./activities/index.ts`: that module is
+ * resolved by convention at `@intentius/chant-lexicon-terraform/op/activities`
+ * for the run-time registry, and this one at
+ * `@intentius/chant-lexicon-terraform/op/activity-contracts` for build-time
+ * validation. `loadActivityContracts`
+ * (`packages/core/src/op/activity-contract-registry.ts`) merges what it finds
+ * here into the map core's own OPS012 and OPS013 validate every `Chant::Op`
+ * step against. Since #2122 moved those checks into core they fire on every
+ * project that declares an Op, so an Op built out of terraform steps is
+ * checked wherever it is built. Before this existed, both examples that carry
+ * an Op had to keep it outside `src/` where `chant dev check-lexicon`'s
+ * example build could not see it.
+ *
+ * Each contract's `args` schema mirrors the corresponding `*Args` interface in
+ * `./activities/terraform.ts`, and each `returns` schema the corresponding
+ * `*Result`. Authored with `z.strictObject(...)`, never `z.object(...)`: the
+ * default form silently drops an unrecognized key instead of rejecting it, so
+ * a misspelled `planfile` would vanish rather than fail the build. The
+ * `returns` schemas are the half OPS013 needs — `plan.out.planFile` feeding an
+ * Apply step, `plan.out.text` feeding a `reconcilePr` body — so a field a step
+ * references has to be spelled here for the reference to validate.
+ *
+ * `json` is `z.unknown()` throughout: it is terraform's own `-json` document,
+ * whose shape is the provider's, not chant's. A dot-path reference into it
+ * therefore does not resolve, which is deliberate. Reference `text`, or one of
+ * the counts projected out of the document, instead of reaching into
+ * terraform's JSON from an Op.
+ */
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+/** `root` and `cwd`, the two fields every activity in this lexicon takes ({@link TerraformRootArgs}). */
+const rootArgs = { root: z.string(), cwd: z.string().optional() };
+/**
+ * `adds`/`changes`/`destroys`, the counts projected out of a plan's
+ * `resource_changes` ({@link PlanChangeCounts}).
+ */
+const planChangeCounts = { adds: z.number(), changes: z.number(), destroys: z.number() };
+/**
+ * One adoption candidate as `../adoption.ts` models it. Loose on purpose: an
+ * Op never reaches into a candidate's fields, it hands the whole array from a
+ * live-plan step to `choudoufuAdopt`, and a whole-value reference is validated
+ * without walking the shape.
+ */
+const adoptionCandidate = z.object({}).loose();
+/**
+ * The `root` arg names the terraform root module the step acts on — the
+ * estate-side thing every activity here touches — so op.json's IR resolves it
+ * into the step's `entities` (#2022) and a renderer can join the step to the
+ * root instead of guessing off `cwd`, which is only where the config search
+ * starts.
+ */
+const rootEntity = { entities: ["root"] };
+export const terraformInitContract = activityContract("terraformInit", z.strictObject({
+    ...rootArgs,
+    upgrade: z.boolean().optional(),
+    reconfigure: z.boolean().optional(),
+}), z.object({ dir: z.string(), workspace: z.string().optional() }), rootEntity);
+export const terraformPlanContract = activityContract("terraformPlan", z.strictObject({
+    ...rootArgs,
+    planFile: z.string().optional(),
+    destroy: z.boolean().optional(),
+    vars: z.record(z.string(), z.unknown()).optional(),
+}), z.object({
+    ...planChangeCounts,
+    changed: z.boolean(),
+    planFile: z.string(),
+    dir: z.string(),
+    json: z.unknown(),
+    text: z.string(),
+    planDigest: z.string(),
+    /** The root's change-set part (#3181); its shape is `@intentius/chant/change-set`'s `ChangeSetPart`. */
+    changeSet: z.object({ member: z.object({ member: z.string(), planDigest: z.string().nullable() }).passthrough(), entries: z.array(z.unknown()) }),
+}), rootEntity);
+export const terraformApplyContract = activityContract("terraformApply", z.strictObject({ ...rootArgs, planFile: z.string().optional() }), z.object({
+    planFile: z.string().optional(),
+    dir: z.string(),
+    applied: z.boolean(),
+    refused: z.enum(["approval-mismatch", "wrong-estate"]).optional(),
+    refusal: z.string().optional(),
+}), rootEntity);
+export const terraformShowContract = activityContract("terraformShow", z.strictObject({ ...rootArgs, planFile: z.string().optional() }), z.object({
+    ...planChangeCounts,
+    source: z.enum(["plan", "state"]),
+    json: z.unknown(),
+    text: z.string(),
+    dir: z.string(),
+    planFile: z.string().optional(),
+}), rootEntity);
+export const choudoufuLivePlanContract = activityContract("choudoufuLivePlan", z.strictObject({
+    ...rootArgs,
+    estate: z.string().optional(),
+    adoptionOnly: z.boolean().optional(),
+}), z.object({
+    ...planChangeCounts,
+    unowned: z.number(),
+    adoptable: z.number(),
+    drift: z.boolean(),
+    json: z.unknown(),
+    text: z.string(),
+    ledger: z.string(),
+    finding: z.string(),
+    adoptions: z.array(adoptionCandidate),
+    contested: z.array(adoptionCandidate),
+    ambiguous: z.number(),
+    dir: z.string(),
+    documentPath: z.string(),
+    estate: z.string(),
+}), rootEntity);
+export const choudoufuLiveLsContract = activityContract("choudoufuLiveLs", z.strictObject({
+    ...rootArgs,
+    estate: z.string().optional(),
+    consistent: z.boolean().optional(),
+}), z.object({ json: z.unknown(), dir: z.string(), estate: z.string() }), rootEntity);
+export const choudoufuLiveCheckContract = activityContract("choudoufuLiveCheck", z.strictObject({ ...rootArgs }), z.object({ refused: z.boolean(), json: z.unknown(), text: z.string(), dir: z.string() }), rootEntity);
+export const choudoufuAdoptContract = activityContract("choudoufuAdopt", z.strictObject({
+    ...rootArgs,
+    adoptions: z.array(adoptionCandidate),
+    contested: z.array(adoptionCandidate).optional(),
+}), z.object({
+    mechanism: z.literal("tag-write"),
+    adopted: z.array(z.string()),
+    adoptedCount: z.number(),
+    refused: z.array(z.object({ addr: z.string(), identity: z.string(), reason: z.string() })),
+    ambiguous: z.number(),
+    dir: z.string(),
+}), rootEntity);
+/** One root of a pin-bump rollout ({@link PinRoot} in `../pin/waves.ts`). */
+const pinRoot = z.strictObject({ root: z.string(), dependsOn: z.array(z.string()).optional(), tsSource: z.string().optional() });
+/**
+ * `terraformPinRollout` (#3189). It names no `terraform.roots` key: a rollout
+ * moves a module's pin across many roots, found by directory, so it carries no
+ * `rootEntity`. `status` and `summary` are the fields an Op reads: the run's
+ * outcome and a body for a report step.
+ */
+export const terraformPinRolloutContract = activityContract("terraformPinRollout", z.strictObject({
+    module: z.string(),
+    from: z.string(),
+    to: z.string(),
+    roots: z.array(pinRoot).optional(),
+    canaries: z.array(z.string()).optional(),
+    wavesFrom: z.string().optional(),
+    wavesPrefix: z.string().optional(),
+    mode: z.enum(["report", "pull-request"]).optional(),
+    base: z.string().optional(),
+    remote: z.string().optional(),
+    appliedCheck: z.string().optional(),
+    cwd: z.string().optional(),
+}), z.object({
+    module: z.string(),
+    from: z.string(),
+    to: z.string(),
+    mode: z.enum(["report", "pull-request"]),
+    base: z.string(),
+    status: z.enum(["complete", "opened", "would-open", "waiting", "stopped"]),
+    roots: z.array(z.object({}).loose()),
+    waves: z.array(z.object({}).loose()),
+    stop: z.string().optional(),
+    summary: z.string(),
+}));

package/dist/op/adoption.js

@@ -0,0 +1,272 @@
+/**
+ * The adoption ledger: which live resources this estate's markers can claim,
+ * read off `live-plan -json`'s document and rendered as text (#2105, #2241).
+ *
+ * Pure. No filesystem, no child process, no HCL parse — everything here is a
+ * projection of two sections of choudoufu's document, which between them state
+ * both halves of the answer: the live resource an adoption would claim, and
+ * the `tofu-estate`/`tofu-address` pair that claims it. Two tags is the whole
+ * ownership contract (choudoufu's `live/MARKERS.md`), so those two values are
+ * the whole of what an adoption needs to know.
+ *
+ * ## The two sections, and why there are two
+ *
+ * `unowned[]` (choudoufu issue #788) is a live resource read at an identity
+ * the configuration itself declares: a log group's name is in the block, so an
+ * unmarked live one with that name is found by reading it.
+ *
+ * `adoptable[]` (choudoufu issue #962, shipped in v0.15.0) is a live resource
+ * the estate-wide sweep matched to a declared instance by content, for a
+ * declaration that carries no identity at all: EC2 assigns a VPC's id, so a
+ * declared `aws_vpc` lands in `omissions[]` as `NEEDS_DISCOVERY` and the live
+ * VPC standing at its `cidr_block` is found by comparing arguments. Each row
+ * carries `matched[]`, the arguments that agreed, and `adopt_command`, the
+ * paste-ready tagging command, so nothing on this path parses the human
+ * render any more. Before v0.15.0 the document had no row for that match at
+ * all and chant read the two regexes {@link parseAdoptionCommands} still
+ * holds, which is what chant #2168 measured and filed.
+ *
+ * The two sections are disjoint by construction, so this reads both and keys
+ * the union by declared address.
+ *
+ * ## What the empty ledger means
+ *
+ * `adoptable[]` and `swept[]` are populated only on a run that asked the
+ * estate-wide sweep the account-bounded question (`-adoption-only`, or
+ * `TOFU_LIVE_COLLECT_UNCLAIMED=1` on a `-json` run). {@link AdoptionLedger}
+ * carries `swept` for exactly that reason: an empty `adoptions` under an empty
+ * `swept` is "this run did not look", not "there is nothing to adopt", and
+ * {@link renderAdoptionLedger} says which.
+ *
+ * ## Why chant renders a ledger at all
+ *
+ * choudoufu prints its own, under `live-plan -adoption-only`, and it is the
+ * better report for a human at a terminal: it counts the marker-carrying and
+ * the identity-by-declaration halves of the declared population separately and
+ * says why each unadoptable instance is unadoptable. But `-adoption-only` and
+ * `-json` are refused together (`internal/command/live_plan.go`: "this run
+ * cannot produce both reports at once"), and an Op that reports adoptables
+ * needs the machine-readable document anyway, for the counts it publishes as
+ * outcome attributes and for the addresses an adoption step acts on. So the
+ * ledger below is rendered from the document that run already has, in the row
+ * form `-adoption-only` prints, rather than paying for a third live read.
+ *
+ * ## Ambiguity
+ *
+ * Both sections are one entry per live resource, keyed by the declared
+ * instance the resource was matched to, so two live resources at one
+ * declaration are two entries carrying the same `addr`. That is the ambiguous
+ * case: no single tag write claims the address, and picking one of the two is
+ * a decision about the estate rather than something a tool infers.
+ * {@link readAdoptionLedger} separates those into `contested` and never lets
+ * them into `adoptions`, and `TerraformAdoptOp` passes the contested list to
+ * its Adopt step so the Op's result names what it refused as well as what it
+ * wrote.
+ */
+const str = (v) => (typeof v === "string" ? v : "");
+/** `matched[]` as choudoufu writes it, dropping anything that is not a pair of strings. */
+function readMatched(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        const m = (item ?? {});
+        const attribute = str(m.attribute);
+        if (attribute)
+            out.push({ attribute, value: str(m.value) });
+    }
+    return out;
+}
+/** `swept[]` as choudoufu writes it: resource type names, and nothing else. */
+function readSwept(document) {
+    const swept = document?.swept;
+    return Array.isArray(swept) ? swept.filter((t) => typeof t === "string") : [];
+}
+/**
+ * Project a `live-plan -json` document's `unowned` and `adoptable` sections
+ * into the adoptable and the contested sets.
+ *
+ * An entry counts as a candidate only when choudoufu offered both marker
+ * values. Both empty means adoption was not this run's to offer: the resource
+ * belongs to another estate (`tofu_estate` names it), or the run had no estate
+ * name of its own, and such an entry is neither adoptable nor contested here,
+ * because there is no tag write to refuse.
+ *
+ * `commands` maps a declared address to the paste-ready tagging command
+ * choudoufu printed for it, from {@link parseAdoptionCommands}. An
+ * `adoptable[]` row carries its own command in the document and never needs
+ * the map; omit the map entirely when the run had no `-adoption-only` render
+ * to read one out of.
+ */
+export function readAdoptionLedger(document, commands) {
+    const doc = (document ?? {});
+    const swept = readSwept(document);
+    const byAddr = new Map();
+    const add = (candidate) => {
+        const at = byAddr.get(candidate.addr);
+        if (at)
+            at.push(candidate);
+        else
+            byAddr.set(candidate.addr, [candidate]);
+    };
+    for (const raw of Array.isArray(doc.unowned) ? doc.unowned : []) {
+        const e = (raw ?? {});
+        const markerEstate = str(e.adopt_tofu_estate);
+        const markerAddress = str(e.adopt_tofu_address);
+        if (!markerEstate && !markerAddress)
+            continue;
+        const addr = str(e.addr);
+        const command = commands?.get(addr);
+        add({
+            addr,
+            type: str(e.type),
+            identity: str(e.identity),
+            markerEstate,
+            markerAddress,
+            ...(command ? { command } : {}),
+        });
+    }
+    for (const raw of Array.isArray(doc.adoptable) ? doc.adoptable : []) {
+        const e = (raw ?? {});
+        const markerEstate = str(e.adopt_tofu_estate);
+        const markerAddress = str(e.adopt_tofu_address);
+        if (!markerEstate && !markerAddress)
+            continue;
+        const addr = str(e.addr);
+        const command = str(e.adopt_command) || commands?.get(addr);
+        const matched = readMatched(e.matched);
+        add({
+            addr,
+            type: str(e.type),
+            identity: str(e.identity),
+            markerEstate,
+            markerAddress,
+            ...(command ? { command } : {}),
+            ...(matched.length > 0 ? { matched } : {}),
+        });
+    }
+    const adoptions = [];
+    const contested = [];
+    let ambiguous = 0;
+    for (const candidates of byAddr.values()) {
+        if (candidates.length === 1) {
+            adoptions.push(candidates[0]);
+        }
+        else {
+            ambiguous++;
+            contested.push(...candidates);
+        }
+    }
+    return { adoptions, contested, ambiguous, swept };
+}
+/**
+ * Pair each declared address in a `live-plan -adoption-only` render with the
+ * tagging command choudoufu printed under it.
+ *
+ * The render's "Adoptable now" rows are `  <addr> <- <type> <identity>`
+ * followed by indented detail lines, one of which is `      adopt with: <cmd>`
+ * (`internal/command/views/live_adoption.go`). choudoufu builds that command
+ * to be pasted verbatim: every interpolated value is shell-quoted, the tagging
+ * verb comes from its own botocore-derived table rather than a guess, and the
+ * provider configuration's region and endpoint ride along as `--region` and
+ * `--endpoint-url`, so the write lands where the resource is rather than
+ * wherever an operator's AWS CLI profile points. Re-deriving any of that from
+ * the two marker values alone would be a worse command, so this reads the one
+ * choudoufu already wrote.
+ *
+ * An address the render offered no command for is simply absent from the map.
+ *
+ * ## Which caller still needs this (#2241)
+ *
+ * One: the `unowned[]` half of {@link readAdoptionLedger}. choudoufu's
+ * `views.StatelessUnowned` has no command field, so a live resource found at
+ * an identity the configuration declares still gets its paste-ready command
+ * from the human render and from nowhere else. The `adoptable[]` half no
+ * longer reads a line of text: those rows carry `adopt_command` in the
+ * document itself since v0.15.0 (choudoufu #962), which is what made the
+ * adopt path stop resting on two regexes over a render nobody promised to
+ * keep stable.
+ */
+export function parseAdoptionCommands(ledgerText) {
+    const commands = new Map();
+    let current;
+    for (const line of ledgerText.split("\n")) {
+        const row = /^ {2}(\S+) <- \S+ /.exec(line);
+        if (row) {
+            current = row[1];
+            continue;
+        }
+        const cmd = /^ {6}(?:or )?adopt with: (.+)$/.exec(line);
+        if (cmd && current) {
+            commands.set(current, cmd[1].trim());
+            continue;
+        }
+        // A blank line ends a row's detail block; a non-indented line ends the
+        // section. Either way the next "adopt with:" belongs to nobody until the
+        // next row line names an address.
+        if (line.trim() === "" || !line.startsWith("    "))
+            current = undefined;
+    }
+    return commands;
+}
+const plural = (n, one, many) => (n === 1 ? one : many);
+/**
+ * Render {@link readAdoptionLedger}'s answer as the text an issue or PR body
+ * carries under the plan.
+ *
+ * One line per adoptable match, naming the declared address, the live resource
+ * it binds, and the two tag values that adopt it, in the token forms
+ * `-adoption-only` prints them in (`<addr> <- <type> <identity>`,
+ * `tofu-estate=`, `tofu-address=`). A content match adds the arguments it
+ * rested on under its row, in the same `matched on:` form the human render
+ * uses, because "these two agreed on this cidr" is the whole evidence for a
+ * match nobody read an identity for. Contested addresses follow, listed and
+ * not offered.
+ *
+ * An empty ledger still renders a line: "nothing adoptable" is a result a
+ * reader wants, and a section that vanishes reads as one that was never
+ * computed. Which of the two empties it is comes from `swept`: a run that
+ * asked no estate-wide sweep found nothing because it did not look, and
+ * saying so is the difference between a report and a silence.
+ */
+export function renderAdoptionLedger(ledger, estate) {
+    const where = estate ? `, estate ${JSON.stringify(estate)}` : "";
+    const lines = [];
+    if (ledger.adoptions.length === 0) {
+        lines.push(`Adoptable now: nothing${where}`, "");
+        lines.push(ledger.swept.length === 0
+            ? "No estate-wide sweep ran on this plan, so nothing here says whether an unmarked live " +
+                "resource exists for any declared instance. This is silence, not a finding: ask the " +
+                "account-bounded question with an adoption run."
+            : "No live resource this run could claim was found, across " +
+                `${ledger.swept.length} swept resource ${plural(ledger.swept.length, "type", "types")} ` +
+                `(${ledger.swept.join(", ")}). Anything the plan proposes creating, it proposes ` +
+                "creating for real.");
+    }
+    else {
+        lines.push(`Adoptable now: ${ledger.adoptions.length} live ${plural(ledger.adoptions.length, "resource", "resources")}${where}`, "");
+        lines.push("Each line is a live resource this estate could claim, found either at a declared resource's " +
+            "own identity or by matching a declaration's arguments, and carrying no marker for this " +
+            "estate. Writing the two tags shown adopts it; nothing is bound until they are written, " +
+            "because ownership is the tofu-estate and tofu-address pair and nothing else.", "");
+        for (const c of ledger.adoptions) {
+            lines.push(`  ${c.addr} <- ${c.type} ${c.identity}  write: ` +
+                `tofu-estate=${c.markerEstate} tofu-address=${c.markerAddress}`);
+            if (c.matched?.length) {
+                lines.push(`      matched on: ${c.matched.map((m) => `${m.attribute}=${m.value}`).join(", ")}`);
+            }
+        }
+    }
+    if (ledger.contested.length > 0) {
+        lines.push("");
+        lines.push(`Ambiguous: ${ledger.ambiguous} declared ${plural(ledger.ambiguous, "address", "addresses")} ` +
+            "with more than one candidate", "");
+        lines.push("More than one live resource sits at each of these declared identities, so no single tag write " +
+            "claims the address. None of them is adopted. Resolve it by deleting the duplicate or by " +
+            "writing the marker onto the one you mean.", "");
+        for (const c of ledger.contested) {
+            lines.push(`  ${c.addr} <- ${c.type} ${c.identity}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/op/builders.js

@@ -0,0 +1,125 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities, copied from
+ * `lexicons/k3s/src/op/builders.ts` (chant #1288 Stage 2). `opts`'s type in
+ * each wrapper below IS the activity's own `*Args` interface, via
+ * `Omit`/`WithStepRefs`, never restated: rename a field on the activity and
+ * the builder's callers stop compiling.
+ *
+ * The `root` key is positional in every wrapper, because naming the root is
+ * the one thing a terraform step cannot be authored without.
+ *
+ * `id` routes to the step's `id` field rather than into `args`. That matters
+ * here more than anywhere else in the lexicon: `.out` throws without an id
+ * (`packages/core/src/op/builders.ts`), and `.out` is how an Apply step names
+ * the Plan step's `planFile` as a `StepOutputRef` instead of guessing the
+ * path a second time.
+ */
+import { activity, takeProfileAndId, } from "@intentius/chant/op";
+/**
+ * `terraform init` in the named root — the fully typed twin of the
+ * `terraformInit` activity. `opts` is {@link TerraformInitArgs} itself, minus
+ * the positional `root`. Defaults to the `longInfra` profile: init downloads
+ * providers.
+ */
+export const terraformInit = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("terraformInit", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * `terraform plan` in the named root, writing a saved plan. `opts` is
+ * {@link TerraformPlanArgs} itself, minus the positional `root`. Defaults to
+ * the `longInfra` profile: plan refreshes every resource against its provider.
+ *
+ * Give this step an `id` when a later step applies its plan — `plan.out.planFile`
+ * is the reference an Apply step takes.
+ */
+export const terraformPlan = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("terraformPlan", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * `terraform apply <planFile>` in the named root, the fully typed twin of the
+ * `terraformApply` activity. `opts` is {@link TerraformApplyArgs} itself,
+ * minus the positional `root`. `planFile` is optional in the type and
+ * required in practice, on a live root as much as a stock one: the activity
+ * refuses a missing one, and on a live root the file is the approval artifact
+ * choudoufu v0.13.0 re-plans against and refuses on a mismatch (choudoufu
+ * #878). Defaults to the `longInfra` profile.
+ */
+export const terraformApply = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("terraformApply", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * `choudoufu live-plan -detailed-exitcode -json` in the named root, plus the
+ * human render. The fully typed twin of the `choudoufuLivePlan` activity
+ * (#2103). `opts` is {@link ChoudoufuLivePlanArgs} itself, minus the
+ * positional `root`; `estate` is optional, auto-detected from the root's
+ * `live` block or `estate.chdf.hcl` sidecar when omitted, and a root that
+ * declares one is run with no `-estate` at all, which is the only form
+ * choudoufu admits there (choudoufu #894, fixed in v0.14.0).
+ * Defaults to the `longInfra` profile: like `terraformPlan`, this reads the
+ * live system in full (the estate-wide sweep).
+ *
+ * Give this step an `id` to read `.out.drift`, `.out.unowned`,
+ * `.out.adoptable` or `.out.documentPath` from a later step.
+ */
+export const choudoufuLivePlan = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("choudoufuLivePlan", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * `choudoufu live-ls -estate=<estate> -json [-consistent]` in the named root,
+ * the fully typed twin of the `choudoufuLiveLs` activity (#2103). `opts` is
+ * {@link ChoudoufuLiveLsArgs} itself, minus the positional `root`. Defaults to
+ * the `fastIdempotent` profile: `live-ls` reads a tagging-API listing and
+ * calls no other provider.
+ */
+export const choudoufuLiveLs = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("choudoufuLiveLs", { root, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * `choudoufu live-check -json` in the named root, the fully typed twin of the
+ * `choudoufuLiveCheck` activity (#2103). `opts` is {@link ChoudoufuLiveCheckArgs}
+ * itself, minus the positional `root`. Defaults to the `fastIdempotent`
+ * profile: no cloud calls, no state.
+ */
+export const choudoufuLiveCheck = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("choudoufuLiveCheck", { root, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Write the ownership markers that claim an adoption ledger's matches, in the
+ * named root. The fully typed twin of the `choudoufuAdopt` activity (#2105).
+ * `opts` is {@link ChoudoufuAdoptArgs} itself, minus the positional `root`, so
+ * `adoptions` is required at the call site — an adopt step with nothing to
+ * adopt is an authoring mistake, not a no-op worth defaulting to. Defaults to
+ * the `longInfra` profile: one tagging round trip per resource, against the
+ * cloud.
+ */
+export const choudoufuAdopt = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("choudoufuAdopt", { root, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * `terraform show` in the named root, over state or over a saved plan. `opts`
+ * is {@link TerraformShowArgs} itself, minus the positional `root`. Defaults
+ * to the `fastIdempotent` profile: show reads an artifact and calls no
+ * provider.
+ */
+export const terraformShow = (root, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("terraformShow", { root, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * One run of a pin-bump rollout (#3189). `opts` is
+ * {@link TerraformPinRolloutArgs} itself. It names no root: the rollout finds
+ * the roots that call the module. Defaults to the `fastIdempotent` profile: a
+ * repeated run reads the forge again and finds the PR an earlier attempt
+ * opened.
+ */
+export const terraformPinRollout = (opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("terraformPinRollout", args, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};

package/dist/op/resolve-root-mode.js

@@ -0,0 +1,77 @@
+/**
+ * Best-effort, synchronous read of whether a named `terraform.roots` entry is
+ * live: `terraform.binary` is `"choudoufu"` and the root's directory declares
+ * an estate, either a `live { }` block or an `estate.chdf.hcl` sidecar (#2103).
+ *
+ * Three callers decide something at build time, before any activity runs, and
+ * none can afford the async work `../op/activities/terraform.ts`'s own
+ * `resolveRoot` does (`loadChantConfigUpward`, a full `chant.config.ts`/`.json`
+ * walk):
+ *
+ *   - `TerraformApplyOp` (`../composites/terraform-apply-op.ts`) reads the
+ *     mode to word the Gate phase's approval description, and to refuse a
+ *     root whose `policy` block sets `undeclared_untagged = "delete"`. The
+ *     mode no longer picks a phase shape: #2157 made the live and stock Apply
+ *     steps one step, so both roots build the same phases.
+ *   - `TerraformWatchOp` (`../composites/terraform-watch-op.ts`) cross-checks
+ *     its hand-set `live` flag against the root's real mode and refuses a
+ *     mismatch (#2216).
+ *   - TF101 (`../lint/rules/plan-before-apply.ts`) decides whether a
+ *     `terraformApply` call it is statically inspecting is exempt from the
+ *     plan-file pairing it otherwise enforces.
+ *
+ * All three run in the build process (`chant build`/`chant lint`) rather than
+ * in an activity at run time, so a synchronous read is available, but only the
+ * cheap half of it: `findProjectConfig` (`@intentius/chant/project-root`) is a
+ * plain, already-synchronous upward filesystem walk, but a `chant.config.ts`
+ * is project-authored code, and evaluating it synchronously outside chant's
+ * own config-sandbox machinery is more than any caller's best-effort question
+ * is worth. So this reads `chant.config.json` only; a project on a `.ts`
+ * config, or with no config discoverable at all, or naming no matching root,
+ * resolves to `undefined`, and "unknown" reads as "stock" to every caller.
+ *
+ * That default is conservative for the two callers that only ever add a
+ * requirement by knowing more: TF101 keeps enforcing the plan-file pairing,
+ * and the watch Op keeps accepting the flag it was given. It is the
+ * permissive direction for the apply Op's policy refusal and for the watch
+ * Op's mismatch, which is why neither refusal is left to this function alone:
+ * TF027 and TF028 (`../lint/post-synth/`) ask the same questions of the
+ * parsed HCL the build already stamped `mode` onto, whatever the config file
+ * is written in, and those checks are the guarantee (#2216). Every project in
+ * this repository is on a `chant.config.ts`, so a refusal that resolves the
+ * mode through this function alone never fires for anyone.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { findProjectConfig } from "@intentius/chant/project-root";
+import { detectLiveEstate } from "./activities/live-detect.js";
+/**
+ * Resolve `rootName`'s mode against the nearest `chant.config.json` found by
+ * walking up from `cwd` (default `process.cwd()`, matching every other
+ * `cwd`-defaulting option in this lexicon). `undefined` when that cannot be
+ * done with a plain, synchronous read: no config found, the config found is
+ * `chant.config.ts`, the config declares no such root, or the root's
+ * directory does not exist.
+ */
+export function resolveRootModeSync(rootName, cwd) {
+    const { dir: projectRoot, configPath } = findProjectConfig(resolve(cwd ?? process.cwd()));
+    if (!configPath || !configPath.endsWith(".json"))
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    const terraform = raw?.terraform;
+    const root = terraform?.roots?.[rootName];
+    if (!terraform || !root || typeof root.dir !== "string")
+        return undefined;
+    const dir = resolve(projectRoot, root.dir);
+    if (terraform.binary !== "choudoufu")
+        return { mode: "state", dir };
+    if (!existsSync(dir))
+        return undefined;
+    return { mode: detectLiveEstate(dir) !== undefined ? "live" : "state", dir };
+}

package/dist/package-cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./codegen/generate.js";
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const srcDir = dirname(fileURLToPath(import.meta.url));
+// 1. Generate src/generated/ files (writeGeneratedFiles resolves its own target)
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult);
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+const distDir = join(dirname(srcDir), "dist");
+writeBundleSpec(spec, distDir);
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);