@intentius/chant 0.45.0 → 0.49.0

package/src/okf-read.ts

@@ -0,0 +1,197 @@
+import { readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import type { Declarable } from "./declarable";
+import { splitFrontmatter } from "./okf";
+import { parseYAML } from "./yaml";
+
+/**
+ * OKF bundle reader (#1864, design #1059, epic #1057) — the input half of
+ * `./okf.ts`'s emitter: loads a project-authored knowledge bundle from disk
+ * and binds its concepts to discovered entities.
+ *
+ * Tolerant to the letter of the OKF v0.2 spec (§11), the same posture
+ * `okfConformanceProblems` enforces on the emit side: unknown `type` values
+ * and extra frontmatter keys pass through untouched, a file with unparseable
+ * or missing frontmatter is skipped with a warning, and nothing here ever
+ * rejects the bundle — a missing knowledge directory included.
+ */
+
+const RESERVED_OKF_FILES = new Set(["index.md", "log.md"]);
+
+/**
+ * One authored concept document, parsed from a bundle. Deliberately thinner
+ * than the emit side's internal `Concept` (`./okf.ts`) — this is what a
+ * *reader* trusts, and per the #1059 design that is `type`/`title` plus the
+ * single frontmatter key chant interprets, `binds`. Everything else an
+ * author wrote rides along in {@link frontmatter} unexamined, so a consumer
+ * that needs a project-specific key (a future `category`, say) can still
+ * reach it without a reader change.
+ */
+export interface OkfConcept {
+  /** Bundle-relative path (forward-slash separated), e.g. "decisions/public-assets.md". */
+  path: string;
+  /** The frontmatter `type`. May be empty — the reader never rejects a concept for it, unlike the emitter's conformance check. */
+  type: string;
+  /** Frontmatter `title`, when the author set one. */
+  title?: string;
+  /**
+   * This concept's `binds` frontmatter key, normalized to a list — one name,
+   * several, or `[]` for "declared no binding, and that's legitimate."
+   * Structural-looking keys (`name`, `lexicon`, `kind`) are deliberately
+   * *not* surfaced here or anywhere else on this type: the reader interprets
+   * exactly `binds` (#1059's precedence-by-construction), so authored and
+   * inferred knowledge cannot conflict at the fact level.
+   */
+  binds: string[];
+  /** Every frontmatter key this concept's document carries, `binds` included, verbatim. */
+  frontmatter: Record<string, unknown>;
+  /** Markdown body (everything after the closing `---`), unchanged. */
+  body: string;
+}
+
+/** A loaded OKF knowledge bundle: every authored concept found, reserved files already excluded. */
+export interface OkfBundle {
+  concepts: OkfConcept[];
+}
+
+/** `binds` accepts one name or a list (#1059); anything else is treated as "no binding" rather than rejecting the concept. */
+function normalizeBinds(value: unknown): string[] {
+  if (typeof value === "string") return value.length > 0 ? [value] : [];
+  if (Array.isArray(value)) return value.filter((v): v is string => typeof v === "string" && v.length > 0);
+  return [];
+}
+
+/** Recursively collect every `.md` file under `dir`, as bundle-relative (forward-slash) paths paired with their absolute path. */
+async function findMarkdownFiles(dir: string): Promise<Array<{ relPath: string; fullPath: string }>> {
+  const found: Array<{ relPath: string; fullPath: string }> = [];
+
+  async function scan(current: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return; // unreadable directory: silently skip, same posture as findInfraFiles
+    }
+    for (const entry of entries) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        await scan(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const relPath = relative(dir, fullPath).split(sep).join("/");
+        found.push({ relPath, fullPath });
+      }
+    }
+  }
+
+  await scan(dir);
+  return found;
+}
+
+/**
+ * Load every authored concept from an OKF knowledge bundle directory.
+ * `index.md`/`log.md` are skipped (reserved, by basename, at any depth —
+ * matching `okfConformanceProblems`'s check on the emit side). A directory
+ * that does not exist yields an empty bundle, not an error: the #1059 design
+ * treats a missing `knowledge/` as "this project has none yet," the same
+ * posture as a project with no lexicons configured.
+ *
+ * A file that fails to parse — no frontmatter block, unparseable YAML, or
+ * frontmatter that isn't a mapping — is skipped with a `console.warn` and
+ * does not affect any other file. Nothing here throws.
+ */
+export async function loadOkfBundle(dir: string): Promise<OkfBundle> {
+  if (!existsSync(dir)) return { concepts: [] };
+
+  const concepts: OkfConcept[] = [];
+  for (const { relPath, fullPath } of await findMarkdownFiles(dir)) {
+    if (RESERVED_OKF_FILES.has(relPath.split("/").pop()!)) continue;
+
+    let content: string;
+    try {
+      content = await readFile(fullPath, "utf8");
+    } catch {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" could not be read, skipping`);
+      continue;
+    }
+
+    const split = splitFrontmatter(content);
+    if (!split) {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" has no frontmatter block, skipping`);
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = parseYAML(split.frontmatter);
+    } catch {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" has unparseable frontmatter, skipping`);
+      continue;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" frontmatter is not a mapping, skipping`);
+      continue;
+    }
+
+    const frontmatter = parsed as Record<string, unknown>;
+    concepts.push({
+      path: relPath,
+      type: typeof frontmatter.type === "string" ? frontmatter.type : "",
+      title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+      binds: normalizeBinds(frontmatter.binds),
+      frontmatter,
+      body: split.body,
+    });
+  }
+
+  concepts.sort((a, b) => a.path.localeCompare(b.path));
+  return { concepts };
+}
+
+/** {@link bindConcepts}'s result: bound concepts per entity, plus every binding that resolved nothing. */
+export interface BindConceptsResult {
+  /**
+   * Bound concepts keyed by entity logical name — the same names that key
+   * `DiscoveryResult.entities` (`./discovery/index.ts`). An entity with no
+   * bound concepts is absent from the map, never present with `[]`.
+   */
+  bound: Map<string, OkfConcept[]>;
+  /** Every `binds` entry that named no entity in `entities` — chant's own broken-link posture (#1059): a warning for the caller to surface (COR022, #1865), never a load failure. */
+  unresolved: UnresolvedBinding[];
+}
+
+/** One `binds` entry that resolved to nothing. */
+export interface UnresolvedBinding {
+  /** The concept whose `binds` named this entity. */
+  concept: OkfConcept;
+  /** The unresolved logical name. */
+  name: string;
+}
+
+/**
+ * Resolve every concept's `binds` against a project's discovered entities.
+ * `entities` is the same shape `./okf.ts`'s emitter takes, `DiscoveryResult`'s
+ * own `entities` map — a bare logical name is unambiguous within one
+ * discovery pass (#1059's "Rejected options" on binding ambiguity).
+ *
+ * A concept with no `binds` contributes to neither `bound` nor `unresolved`;
+ * an unbound concept is legitimate, not an omission (a runbook, a decision
+ * about the project as a whole).
+ */
+export function bindConcepts(bundle: OkfBundle, entities: Map<string, Declarable>): BindConceptsResult {
+  const bound = new Map<string, OkfConcept[]>();
+  const unresolved: UnresolvedBinding[] = [];
+
+  for (const concept of bundle.concepts) {
+    for (const name of concept.binds) {
+      if (entities.has(name)) {
+        if (!bound.has(name)) bound.set(name, []);
+        bound.get(name)!.push(concept);
+      } else {
+        unresolved.push({ concept, name });
+      }
+    }
+  }
+
+  return { bound, unresolved };
+}

package/src/op/builders.ts

@@ -1,5 +1,7 @@
 import { OpResource } from "./resource";
-import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
+import { receiptCheckInput } from "./receipt-store";
 
 // ── Core builders ─────────────────────────────────────────────────────────────
 
@@ -58,6 +60,62 @@ export function gate(
   };
 }
 
+/**
+ * Wrap nested steps in read-compare-run-write over an effect receipt (#1834,
+ * epic #1703). At run: read the live receipt through the receipt store,
+ * compare it against the resolved expectation, and on a match skip the nested
+ * steps ("effect already applied"). On a mismatch the nested steps run in
+ * authored order, and ONLY when every one of them succeeds is the receipt
+ * written — last, once. This step is the sole writer of a receipt (decision
+ * 3); a nested-step failure leaves the receipt untouched (stale), so the next
+ * run re-proposes the effect.
+ *
+ * `receipt` is the typed EffectReceipt declaration — import the const from
+ * your receipts module. There is no string form: a receipt named by string
+ * would sever the step from the declaration that lint, plan, and the lexicon
+ * row all key on.
+ *
+ * A gate authored inside `steps` pauses only when the effect will fire (the
+ * matched path never reaches it). The receipt-store activities (`receiptRead`,
+ * `receiptWrite`) are provided by the receipt row's lexicon (#1835, aws).
+ *
+ * @example
+ * ```ts
+ * import { seededReceipt } from "./receipts";
+ * phase("Seed", [
+ *   effect(seededReceipt, [
+ *     shell("npm run db:seed"),
+ *   ]),
+ * ]),
+ * ```
+ */
+export function effect(
+  receipt: EffectReceiptDeclaration,
+  steps: Array<ActivityStep | GateStep>,
+  opts?: { description?: string },
+): EffectStep {
+  if (!isEffectReceipt(receipt)) {
+    throw new Error(
+      "effect(): `receipt` must be the EffectReceipt declaration itself — import the const; there is no string form",
+    );
+  }
+  for (const step of steps) {
+    if ((step as { kind?: unknown }).kind === "effect") {
+      throw new Error(
+        `effect("${receipt.name}"): effect steps do not nest — one receipt witnesses one effect`,
+      );
+    }
+  }
+  const { receipt: ref, expectation } = receiptCheckInput(receipt);
+  return {
+    kind: "effect",
+    receipt: ref,
+    ...(expectation !== undefined ? { expectation } : {}),
+    steps,
+    ...(opts?.description ? { description: opts.description } : {}),
+  };
+}
+
 // ── Pre-built activity shortcuts ──────────────────────────────────────────────
 
 /**
@@ -100,6 +158,22 @@ export const helmInstall = (
   return activity("helmInstall", { name, chart, ...args }, profile ?? "longInfra");
 };
 
+/**
+ * Deploy a recorded pinned render by its `sha256:` content digest (chant
+ * #1242): the helm lexicon's `helmInstall` activity loads the render from
+ * the render store, verifies the digest, and installs those exact bytes as
+ * a structure-preserving wrapper chart — no deploy-time render. Defaults to
+ * the `longInfra` profile (override via `opts.profile`).
+ */
+export const helmInstallPinned = (
+  name: string,
+  contentDigest: string,
+  opts?: { namespace?: string; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("helmInstall", { name, contentDigest, ...args }, profile ?? "longInfra");
+};
+
 /** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Defaults to the `k8sWait` profile (override via `opts.profile`). */
 export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep => {
   const { args, profile } = takeProfile(opts);
@@ -133,10 +207,63 @@ export const shell = (
 ): ActivityStep =>
   activity("shellCmd", { cmd, ...(opts?.env ? { env: opts.env } : {}) }, opts?.profile);
 
+/**
+ * Ensure a `generated-once` secret exists in the target store (#1829, epic
+ * #1365). The op-step surface over the same engine as the `ensure-secret`
+ * capability verb (`ensureSecretMaterialization`, core's
+ * secret-materialization module): read-then-write — if the secret exists, its
+ * declared key-set and any declared `metadata` are verified and the step
+ * stops (present means done); if absent, one value per key is minted at
+ * apply time and written straight to the store. Never mints over an existing
+ * value, never rotates implicitly; a mismatch fails the step loudly, naming
+ * key names and metadata keys — never values. No output of the activity
+ * carries secret material. The backing activity is provided by the store's
+ * lexicon (k8s, #1830).
+ */
+export const ensureSecret = (
+  name: string,
+  keys: string[],
+  opts?: { metadata?: Record<string, string>; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("ensureSecret", { name, keys, ...args }, profile);
+};
+
 /** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
 export const teardown = (path: string): ActivityStep =>
   activity("chantTeardown", { path }, "longInfra");
 
+/**
+ * Tear down one environment's marker-owned resources — the durable form of
+ * `chant lifecycle teardown <env> --yes` (#1222). The activity runs core's
+ * teardown engine in-process: enumerate by ownership marker (this project's
+ * `ownership.stack` + `env`), delete through each lexicon's `executeTeardown`
+ * capability, retry failures once, and fail the step when any candidate is
+ * still failed. Distinct from {@link teardown}, which runs a project's own
+ * `npm run teardown` script.
+ *
+ * The CLI's guards apply unchanged, and a production-like environment name
+ * needs `confirmProd: true` in `opts` — the authored counterpart of
+ * `--confirm-prod`, since an Op never prompts. An ordinary {@link gate} step
+ * placed before this one composes as usual (steps run in authored order), so
+ * a human approval can precede the deletion:
+ *
+ * ```ts
+ * phase("Teardown", [
+ *   gate("approve-teardown", { description: "Release the staging teardown" }),
+ *   envTeardown("staging"),
+ * ]),
+ * ```
+ *
+ * `opts` also accepts `path` (the chant project directory, default the
+ * worker's cwd). Defaults to the `longInfra` profile (override via
+ * `opts.profile`).
+ */
+export const envTeardown = (env: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("envTeardown", { env, ...args }, profile ?? "longInfra");
+};
+
 /**
  * Create a local k3d cluster (vanilla Kubernetes in Docker). Idempotent: skips
  * creation if a cluster of the same name already exists. Defaults to the
@@ -169,6 +296,48 @@ export const k3dDown = (name: string, opts?: Record<string, unknown>): ActivityS
   return activity("k3dDown", { name, ...args }, profile ?? "fastIdempotent");
 };
 
+/**
+ * Run the pinned k3s installer against a reachable host (`role`: `"server"`
+ * or `"agent"`). Idempotent on an already-installed matching version.
+ * Defaults to the `longInfra` profile (the installer downloads and starts
+ * the binary); override via `opts.profile`.
+ *
+ * The implementation lives in the k3s lexicon (chant #1601) — the project's
+ * `chant.config.ts` must list `"k3s"` in `lexicons` for the activity to load.
+ * Bounded exactly as `k3dUp`/`k3dDown` (chant #1410): drives the reachable-host
+ * case only, no host provisioning, no SSH orchestration.
+ *
+ * `opts` accepts `configFile` (required — path to the chant-emitted
+ * config.yaml, passed as `--config`), `version` (overrides the lexicon's
+ * pinned `INSTALL_K3S_VERSION`), and `tokenFile` (path to a file holding the
+ * join token, passed to the installer as `K3S_TOKEN_FILE`). There is no
+ * `token` option — the join secret's value never travels through this step;
+ * only a file path does (the #1601 token boundary, same stance as #1365).
+ */
+export const k3sInstall = (
+  role: "server" | "agent",
+  opts: { configFile: string; version?: string; tokenFile?: string; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("k3sInstall", { role, ...args }, profile ?? "longInfra");
+};
+
+/**
+ * Uninstall k3s from a reachable host (`role`: `"server"` or `"agent"`).
+ * Defaults to the `fastIdempotent` profile (override via `opts.profile`).
+ * Implementation lives in the k3s lexicon (chant #1601) — requires `"k3s"`
+ * in the project's `lexicons`. A host where k3s was never installed is a
+ * no-op success, the same shape as `k3dDown` against an already-gone
+ * cluster.
+ */
+export const k3sUninstall = (
+  role: "server" | "agent",
+  opts?: Record<string, unknown>,
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("k3sUninstall", { role, ...args }, profile ?? "fastIdempotent");
+};
+
 /**
  * Boot a local Floci AWS emulator in Docker and point subsequent steps at it —
  * sets `AWS_ENDPOINT_URL` + test creds in the process env so a following
@@ -279,8 +448,8 @@ export const azDelete = (templatePath: string, opts?: Record<string, unknown>):
  * Deploy a built CloudFormation template by calling the CloudFormation API
  * directly (create-or-update + poll) — the direct twin of {@link azApply} /
  * {@link gcpApply} for AWS, targeting a local Floci emulator or real AWS by
- * endpoint override. Speaks the CFN API over HTTP rather than shelling `aws`
- * (that path is still `nativeApply({ target: "cloudformation" })`). Provided by
+ * endpoint override. Speaks the CFN API over HTTP rather than shelling `aws` —
+ * `nativeApply({ target: "cloudformation" })` routes here too (#1449). Provided by
  * the aws lexicon; loaded when the project lists `aws`. Defaults to the
  * `longInfra` profile. `opts` requires `stackName`; accepts `endpoint`, `region`,
  * `capabilities`, `timeoutMs`, `intervalMs`.
@@ -297,13 +466,15 @@ export const awsDelete = (templatePath: string, opts?: Record<string, unknown>):
 };
 
 /**
- * Apply chant's built GCP (CNRM) resources directly to the GCS REST API,
+ * Apply chant's built GCP (CNRM) resources directly to their GCP REST APIs,
  * targeting a local floci-gcp emulator or real GCP by endpoint override — the
- * native GCP applier (#706 starter #711), currently handling `StorageBucket`.
- * Defaults to the `longInfra` profile (override via `opts.profile`).
+ * native GCP applier (#706 starter #711). `nativeApply({ target: "gcp" })`
+ * routes here too (#1449). Defaults to the `longInfra` profile (override via
+ * `opts.profile`).
  *
- * `opts` accepts `endpoint` (default `STORAGE_EMULATOR_HOST` env / real GCS) and
- * `project` (default `GOOGLE_CLOUD_PROJECT` env / the CNRM project-id annotation).
+ * `opts` accepts `endpoint` (default `GCP_ENDPOINT_URL` env / each kind's
+ * real-GCP host) and `project` (default `GOOGLE_CLOUD_PROJECT` env / the CNRM
+ * project-id annotation).
  */
 export const gcpApply = (manifestPath: string, opts?: Record<string, unknown>): ActivityStep => {
   const { args, profile } = takeProfile(opts);