@intentius/chant 0.57.0 → 0.59.0

package/src/audit/terraform-state.ts

@@ -0,0 +1,131 @@
+/**
+ * TF023 (#2110): Terraform state, or the `.terraform/` working directory,
+ * committed to the repository.
+ *
+ * Every other rule in the TF family is a post-synth check over a parsed root
+ * module, contributed by the terraform lexicon. This one is not about HCL at
+ * all: the finding is that a path exists in version control, so there is
+ * nothing for `chant build` to check and nothing for the lexicon's parser to
+ * read. It therefore takes the shape `secrets.ts` established and `wrangler.ts`
+ * and `nginx.ts` copied, a path detector plus a check over the discovered file
+ * list, called from the audit CLI beside `scanForSecrets`, with its catalog
+ * entry in core's own `RULE_CATALOG` (./catalog.ts) rather than a lexicon's.
+ * It runs whether or not the terraform lexicon is installed.
+ *
+ * A state file is a committed secret store: it records every attribute of every
+ * managed resource, including the ones providers mark sensitive, in plaintext
+ * JSON. `.terraform/` is milder (providers and vendored modules) but is still
+ * hundreds of megabytes of machine-generated content, and it can hold a
+ * `terraform.tfstate` of its own for the workspace-local backend.
+ *
+ * Pure: no fs, no network, no Node-only global, so it is Workers-safe (epic #350). The
+ * walk that decides which paths reach here is `discover.ts`'s
+ * `collectCandidates`, which is also where a locally ignored path is dropped:
+ * see `isTerraformStatePath` there and `gitignoreCoversTerraformState` below.
+ */
+
+import type { AuditFinding } from "./core";
+
+/** The minimal file shape the check needs (matches `discover.ts`'s `RepoFile`). */
+export interface ScannableFile {
+  path: string;
+  content: string;
+}
+
+/** `terraform.tfstate`, `terraform.tfstate.backup`, and any other `*.tfstate`. */
+export function isTerraformStateFile(path: string): boolean {
+  const name = path.split("/").pop() ?? path;
+  return /\.tfstate(\.backup)?$/i.test(name);
+}
+
+/** The `.terraform` working directory itself, or anything inside it. */
+export function isTerraformWorkDir(path: string): boolean {
+  const parts = path.split("/");
+  return parts.includes(".terraform");
+}
+
+/** Either of the two shapes TF023 reports. */
+export function isTerraformStatePath(path: string): boolean {
+  return isTerraformStateFile(path) || isTerraformWorkDir(path);
+}
+
+/**
+ * Does a `.gitignore` body already exclude Terraform state? Deliberately
+ * narrow: it recognises the handful of patterns the style guide's own
+ * `.gitignore` section and `github/gitignore`'s `Terraform.gitignore` use
+ * (`*.tfstate`, `*.tfstate.*`, `.terraform/`, `.terraform*`, with an optional
+ * leading slash or a leading double-star), not the whole gitignore grammar. A repository that
+ * writes something more exotic gets a finding it can suppress; the alternative,
+ * a partial gitignore engine, would be wrong in quieter ways.
+ *
+ * Used by the local walk only (`discover.ts`), where "on disk" and "tracked by
+ * git" are different questions and nearly every Terraform working tree has an
+ * ignored `.terraform/` in it. A fetched repository's file list is already
+ * exactly the tracked files, so nothing filters it.
+ */
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function gitignoreCoversTerraformState(gitignore: string, path: string): boolean {
+  const name = path.split("/").pop() ?? path;
+  for (const raw of gitignore.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith("!")) continue;
+    const pattern = line.replace(/^\*\*\//, "").replace(/^\//, "").replace(/\/$/, "");
+    if (pattern === "" || pattern.includes("/")) continue;
+    // `*` matches within one path segment, as git's own glob does. The pattern
+    // is compared against the file's own name and against every segment of its
+    // path, which is what makes `.terraform/` match `infra/prod/.terraform`.
+    const re = new RegExp(`^${pattern.split("*").map(escapeRegExp).join("[^/]*")}$`);
+    if (re.test(name) || path.split("/").some((segment) => re.test(segment))) return true;
+  }
+  return false;
+}
+
+/**
+ * Report TF023 for every committed state file and `.terraform/` directory in
+ * the file list. One finding per path, and one for the `.terraform` directory
+ * as a whole rather than per file inside it: a vendored provider binary is not
+ * a separate finding from the directory that holds it.
+ */
+export function auditTerraformState(files: ScannableFile[]): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  const workDirs = new Set<string>();
+
+  for (const file of files) {
+    if (isTerraformWorkDir(file.path)) {
+      const parts = file.path.split("/");
+      const dir = parts.slice(0, parts.indexOf(".terraform") + 1).join("/");
+      if (workDirs.has(dir)) continue;
+      workDirs.add(dir);
+      findings.push({
+        checkId: "TF023",
+        severity: "warning",
+        message:
+          `\`${dir}\` is committed to the repository. Terraform's working directory holds downloaded ` +
+          "providers and vendored child modules, and the local backend keeps its state there too. " +
+          "Delete it from version control and add `.terraform/` to .gitignore.",
+        file: dir,
+        lexicon: "terraform",
+        entity: ".terraform",
+      });
+      continue;
+    }
+    if (!isTerraformStateFile(file.path)) continue;
+    findings.push({
+      checkId: "TF023",
+      severity: "error",
+      message:
+        `\`${file.path}\` is committed to the repository. A state file records every attribute of every ` +
+        "managed resource in plaintext, including the ones providers mark sensitive, so a committed " +
+        "state file is a committed secret store. Remove it from version control, add `*.tfstate` and " +
+        "`*.tfstate.backup` to .gitignore, move the state to a remote backend, and rotate anything it held.",
+      file: file.path,
+      lexicon: "terraform",
+      entity: file.path.split("/").pop() ?? file.path,
+    });
+  }
+
+  return findings;
+}

package/src/build.ts

@@ -3,12 +3,14 @@ import type { Serializer, SerializerResult } from "./serializer";
 import type { OwnershipMarker } from "./ownership";
 import type { BuildError, DiscoveryErrorType } from "./errors";
 import type { IntrinsicDef, BuildRootContribution, BuildRootContributor } from "./lexicon";
-import type { BuildParamProvenance } from "./provenance";
+import { getProvenance, type BuildParamProvenance } from "./provenance";
+import { foldProvenanceOfEntities, type FoldProvenance } from "./fold-provenance";
 import { DiscoveryError, BuildError as BuildErrorClass } from "./errors";
 import { LexiconOutput, isLexiconOutput } from "./lexicon-output";
 import { isSecretDeclaration } from "./secret-provenance";
 import { splitReceiptEntities } from "./effect-receipt";
 import { isScenario } from "./lifecycle/scenario";
+import { isOpEntity } from "./op/resource";
 import { AttrRef } from "./attrref";
 import { isAttrRefLike } from "./utils";
 import { isChildProject, type ChildProjectInstance } from "./child-project";
@@ -282,6 +284,22 @@ export interface BuildResult {
    * supplies none.
    */
   buildParams: BuildParamProvenance[];
+
+  /**
+   * chant #2161 — emitted property path to origin, per entity: which composite
+   * parameter produced the field, which literal the composite fixes, which the
+   * author declared directly, and which this build could not attribute.
+   *
+   * Beside the output on purpose, and never inside it. Nothing here is passed
+   * to a serializer, so it cannot reach the document an applier writes; see
+   * ./fold-provenance.ts's module doc and `fold-provenance-exclusion.test.ts`.
+   *
+   * Every entity with properties appears. The origins are as fine as the build
+   * managed: a run build, or a fold build over a factory outside the
+   * interpretable subset, records `unknown` for a composite's fields rather
+   * than guessing.
+   */
+  foldProvenance: FoldProvenance;
 }
 
 /**
@@ -308,6 +326,13 @@ export function partitionByLexicon(
     // Plan scenarios (#1292) are serializer-neutral the same way: a checkable
     // expectation the CLI reads off the entity map, never output.
     if (isScenario(entity)) continue;
+    // Op declarations (#2118) too. An Op's build output is its `op.json` IR,
+    // and core writes that itself from the entity map (`./cli/commands/build.ts`)
+    // rather than routing it through a lexicon serializer — the Op model, the
+    // executor and the IR are all core's, and no lexicon renders an Op entity
+    // into its own manifest. Keeping them out of every partition means no
+    // "No serializer found" warning fires for core's own `chant` lexicon.
+    if (isOpEntity(entity)) continue;
     const lexicon = entity.lexicon;
     if (!partitions.has(lexicon)) {
       partitions.set(lexicon, new Map());
@@ -852,6 +877,11 @@ async function buildFromDiscoveryResult(
     foldDecisions: discoveryResult.foldDecisions,
     lexiconVersions: { ...(options?.lexiconVersions ?? {}) },
     buildParams: options?.buildParams ?? [],
+    // chant #2161 — read off the entities AFTER every step that can change
+    // them (the shared-props merge in `expandComposite`, the build-root merge
+    // above), and deliberately after Step 7, so nothing about computing it can
+    // reach a serializer.
+    foldProvenance: foldProvenanceOfEntities(discoveryResult.entities, getProvenance),
   };
 }
 

package/src/claimed-fields.test.ts

@@ -0,0 +1,145 @@
+import { describe, test, expect } from "vitest";
+import {
+  NO_CLAIMED_FIELDS,
+  claimedFieldPaths,
+  claimedFieldsFromPaths,
+  claimedFieldsOfProps,
+  claimedFieldsOfTree,
+  classifyLiveField,
+  heldBy,
+  isClaimed,
+} from "./claimed-fields";
+import { UNRESOLVED, type DeepNormalizationHooks } from "./deep-observation";
+
+describe("claimedFieldsOfProps", () => {
+  test("walks props to leaf paths in the diff's grammar", () => {
+    const claimed = claimedFieldsOfProps(
+      { spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } } },
+      { entityType: "K8s::Apps::Deployment" },
+    );
+    expect(claimedFieldPaths(claimed)).toEqual([
+      "spec.replicas",
+      "spec.template.spec.containers[0].image",
+      "spec.template.spec.containers[0].name",
+    ]);
+  });
+
+  test("addresses set-like arrays by the lexicon's own order key", () => {
+    const hooks: DeepNormalizationHooks = {
+      orderKey: (el) => (el.pattern === "Tags" ? String((el.element as { Key: string }).Key) : undefined),
+    };
+    const claimed = claimedFieldsOfProps(
+      { Tags: [{ Key: "env", Value: "prod" }] },
+      { entityType: "AWS::S3::Bucket", hooks },
+    );
+    expect(claimedFieldPaths(claimed)).toEqual(["Tags[#env].Key", "Tags[#env].Value"]);
+  });
+
+  test("a pruned property is not claimed", () => {
+    // The hooks decide what is even in the tree, so the claim inherits them
+    // rather than second-guessing them: a field the lexicon subtracts on both
+    // sides is not a field chant is asserting anything about.
+    const hooks: DeepNormalizationHooks = { prune: (node) => node.pattern.startsWith("status") };
+    const claimed = claimedFieldsOfProps(
+      { spec: { replicas: 2 }, status: { readyReplicas: 2 } },
+      { entityType: "T", hooks },
+    );
+    expect(claimedFieldPaths(claimed)).toEqual(["spec.replicas"]);
+  });
+
+  test("an unevaluated intrinsic is still claimed", () => {
+    // chant set the field; it just cannot say what the reference resolves to.
+    const claimed = claimedFieldsOfProps({ BucketName: UNRESOLVED }, { entityType: "T" });
+    expect(isClaimed(claimed, "BucketName")).toBe(true);
+  });
+
+  test("an empty declaration claims nothing", () => {
+    expect(claimedFieldPaths(claimedFieldsOfProps({}, { entityType: "T" }))).toEqual([]);
+    expect(claimedFieldPaths(NO_CLAIMED_FIELDS)).toEqual([]);
+  });
+
+  test("agrees with the tree form on an already-normalized tree", () => {
+    const props = { spec: { replicas: 2 } };
+    expect(claimedFieldPaths(claimedFieldsOfProps(props, { entityType: "T" }))).toEqual(
+      claimedFieldPaths(claimedFieldsOfTree(props, { entityType: "T" })),
+    );
+  });
+});
+
+describe("isClaimed", () => {
+  const claimed = claimedFieldsFromPaths(["Tags[0].Value", "spec.replicas"]);
+
+  test("matches exactly", () => {
+    expect(isClaimed(claimed, "spec.replicas")).toBe(true);
+  });
+
+  test("does not match by index-erased pattern", () => {
+    // A pattern match would answer "declared" for a path with no declared value
+    // to compare against, which is neither of the two declared classifications.
+    expect(isClaimed(claimed, "Tags[3].Value")).toBe(false);
+  });
+
+  test("does not match an ancestor's claim", () => {
+    // Declaring `spec.replicas` says nothing about `spec.strategy.type`.
+    expect(isClaimed(claimed, "spec.strategy.type")).toBe(false);
+  });
+
+  test("an absent claim claims nothing", () => {
+    expect(isClaimed(undefined, "spec.replicas")).toBe(false);
+  });
+});
+
+describe("classifyLiveField", () => {
+  const claimed = claimedFieldsFromPaths(["spec.replicas"]);
+
+  test("declared and equal", () => {
+    expect(
+      classifyLiveField({ claimed, path: "spec.replicas", declaredValue: 2, liveValue: 2 }),
+    ).toBe("declared-equal");
+  });
+
+  test("declared and different", () => {
+    expect(
+      classifyLiveField({ claimed, path: "spec.replicas", declaredValue: 2, liveValue: 5 }),
+    ).toBe("declared-changed");
+  });
+
+  test("undeclared", () => {
+    expect(
+      classifyLiveField({ claimed, path: "metadata.labels.team", declaredValue: undefined, liveValue: "platform" }),
+    ).toBe("undeclared");
+  });
+
+  test("structural equality, not identity", () => {
+    const shaped = claimedFieldsFromPaths(["spec.selector"]);
+    expect(
+      classifyLiveField({
+        claimed: shaped,
+        path: "spec.selector",
+        declaredValue: { app: "web" },
+        liveValue: { app: "web" },
+      }),
+    ).toBe("declared-equal");
+  });
+});
+
+describe("heldBy", () => {
+  test("the substrate's manager answers where it has one", () => {
+    expect(heldBy({ "spec.replicas": "hpa-controller" }, "spec.replicas")).toEqual({
+      holder: "hpa-controller",
+      source: "field-manager",
+    });
+  });
+
+  test("the claim answers where the substrate records nothing", () => {
+    expect(heldBy(undefined, "spec.replicas")).toEqual({ source: "claimed-fields" });
+  });
+
+  test("the claim answers for a path the ownership metadata does not cover", () => {
+    // Kubernetes' own case: a keyed list segment has no `managedFields` entry
+    // under that path, so the declaration is the only witness left.
+    expect(heldBy({ "spec.replicas": "hpa-controller" }, "spec.template.spec.containers[#sidecar].image")).toEqual({
+      source: "claimed-fields",
+    });
+  });
+});

package/src/claimed-fields.ts

@@ -0,0 +1,208 @@
+/**
+ * The claimed-field set (#2160) — which properties this declaration ever set.
+ *
+ * chant's ownership question has always been answered per resource, from a
+ * marker: is this thing mine. The finer question was never asked. A live
+ * property tree carries fields nobody declared — an autoscaler's replica count,
+ * a controller's annotation, a value a person typed into a console — and the
+ * deep diff (./lifecycle/deep-diff.ts) reported every one of them as a
+ * difference, because a difference is all a two-way comparison can produce.
+ *
+ * Every lexicon has been paying for that in hand-written knowledge.
+ * `DeepNormalizationHooks.prune` is where the noise goes, and three of the four
+ * hooks exist because the live tree holds fields the declaration never
+ * mentions. Kubernetes is the one substrate that escapes it: the API server
+ * records a field manager per field (`metadata.managedFields`), so a foreign
+ * write is a fact about the object rather than a rule somebody maintains.
+ * `lexicons/gcp/src/deep-observe.ts` says why nobody else can do that — "a REST
+ * payload carries no field ownership" — and answers with a static per-kind
+ * table instead.
+ *
+ * The declaration is the table they are missing. A `ResourceDeclarable`'s
+ * `props` are exactly the fields chant set, they are available on every
+ * substrate, and they come from the same build that produced the entity.
+ * Nothing has to come back from the provider.
+ *
+ * ## The grammar is the diff's grammar
+ *
+ * A claim is a set of property paths in the form `flattenDeepProperties`
+ * produces: `spec.replicas`, `Tags[#env].Value`, `ingress[0].fromPort`. Same
+ * hooks, same normalization, same flattening — so a path in the claim and a
+ * path in the diff are the same string or they are different fields. Deriving
+ * the claim any other way (walking raw props, say) would give a set that agrees
+ * with the diff for most trees and disagrees for exactly the ones the hooks
+ * were written for.
+ *
+ * ## Membership is exact, deliberately
+ *
+ * A claimed path is matched exactly, never by its index-erased pattern
+ * (`Tags[].Value`). The pattern is the right test for
+ * {@link import("./deep-observation").DeepNode.counterpart}, which asks a
+ * shape question ("did source declare tag values at all") before array order is
+ * canonical. Classification asks a value question, and it pairs a declared
+ * value with a live one at the same path. A pattern match would answer
+ * "declared" for a path that has no declared value to compare against, which is
+ * neither of the two declared classifications and would quietly become a third
+ * meaning of "drift".
+ *
+ * ## What the claim does not decide
+ *
+ * It does not prune. A field chant never declared still reaches the diff, still
+ * appears in the report, and still carries its live value — it is reported as
+ * unclaimed rather than dropped, because chant #1191 already lost a
+ * console-added label by pruning what it could not attribute. What the claim
+ * changes is the verdict: unclaimed is not drift, and drift is the only thing
+ * that may become an update.
+ */
+
+import {
+  deepValueEqual,
+  flattenDeepProperties,
+  normalizeDeepProperties,
+  type DeepNormalizationHooks,
+} from "./deep-observation";
+
+/**
+ * The set of property paths one declaration claims — every path its `props`
+ * flatten to, in the diff's own grammar.
+ *
+ * Opaque on purpose: {@link isClaimed} is the only membership test, so a
+ * consumer cannot accidentally invent a looser one (see the module doc on
+ * pattern matching).
+ */
+export interface ClaimedFieldSet {
+  /** Flattened property paths, exactly as the diff addresses them. */
+  readonly paths: ReadonlySet<string>;
+}
+
+/**
+ * How one LIVE value relates to the claim. Three answers where a two-way diff
+ * had two:
+ *
+ * - `declared-equal` — chant set this field and the cloud agrees. Nothing to say.
+ * - `declared-changed` — chant set this field and the cloud holds something
+ *   else. This is drift, and it is the only classification that may become an
+ *   update.
+ * - `undeclared` — the field has a value and chant never set it. Somebody else
+ *   holds it. Reported, never proposed, never counted as drift.
+ *
+ * A declared path with no live value at all is not in this enumeration: there
+ * is no live value to classify. The diff keeps reporting that case as `absent`.
+ */
+export type FieldClaim = "declared-equal" | "declared-changed" | "undeclared";
+
+/** Which source answered "who holds this field". */
+export type FieldClaimSource =
+  /**
+   * The substrate named the manager. Kubernetes' `metadata.managedFields`, and
+   * nowhere else today — strictly better than the claim, because it says who.
+   */
+  | "field-manager"
+  /**
+   * The declaration answered: the path is not in the claimed-field set, so
+   * chant never set it. Says that it is somebody else's without saying whose,
+   * which is the best any substrate without ownership metadata can do.
+   */
+  | "claimed-fields";
+
+/** An empty claim — a declaration with no props, and the safe default. */
+export const NO_CLAIMED_FIELDS: ClaimedFieldSet = { paths: new Set<string>() };
+
+/**
+ * Build a claim from an already-normalized declared property tree.
+ *
+ * `options` must be the same {@link FlattenDeepOptions} the diff flattens the
+ * declared side with, or the two disagree about keyed list segments.
+ */
+export function claimedFieldsOfTree(
+  declared: Record<string, unknown>,
+  options: { entityType: string; hooks?: DeepNormalizationHooks },
+): ClaimedFieldSet {
+  const flat = flattenDeepProperties(declared, {
+    entityType: options.entityType,
+    side: "declared",
+    ...(options.hooks ? { hooks: options.hooks } : {}),
+  });
+  return { paths: new Set(flat.keys()) };
+}
+
+/**
+ * Build a claim straight from a declaration's raw `props` — the entry point for
+ * a consumer that has an entity and no diff.
+ *
+ * Normalizes with the lexicon's own hooks first, exactly as the diff does, so
+ * pruned and masked paths land the same way on both routes. `livePaths` is the
+ * counterpart set (`deepPathSet` over the live tree) where the caller has one:
+ * without it the pass runs one-sided and any hook gated on
+ * {@link import("./deep-observation").DeepNode.counterpart} sees `"unknown"`,
+ * which is the honest answer and prunes nothing default-related.
+ */
+export function claimedFieldsOfProps(
+  props: Record<string, unknown>,
+  options: {
+    entityType: string;
+    hooks?: DeepNormalizationHooks;
+    livePaths?: ReadonlySet<string>;
+  },
+): ClaimedFieldSet {
+  const normalized = normalizeDeepProperties(props, {
+    entityType: options.entityType,
+    side: "declared",
+    ...(options.hooks ? { hooks: options.hooks } : {}),
+    ...(options.livePaths ? { counterpartPaths: options.livePaths } : {}),
+  });
+  return claimedFieldsOfTree(normalized, options);
+}
+
+/** True when this declaration set the property at `path`. */
+export function isClaimed(claimed: ClaimedFieldSet | undefined, path: string): boolean {
+  return claimed !== undefined && claimed.paths.has(path);
+}
+
+/**
+ * The claim as a sorted array — the wire form, for
+ * {@link import("./deep-observation").DeepResourceObservation.claimedFields}
+ * and for anything serializing a result to JSON.
+ */
+export function claimedFieldPaths(claimed: ClaimedFieldSet): string[] {
+  return [...claimed.paths].sort();
+}
+
+/** Rebuild a claim from its wire form. */
+export function claimedFieldsFromPaths(paths: Iterable<string>): ClaimedFieldSet {
+  return { paths: new Set(paths) };
+}
+
+/**
+ * Classify one live value against the claim.
+ *
+ * `declaredValue` is only read when the path is claimed; pass whatever the
+ * declared tree holds there (including `undefined`, which is a legal declared
+ * value on a claimed path only in the sense that the flattener never emits it).
+ */
+export function classifyLiveField(input: {
+  claimed: ClaimedFieldSet | undefined;
+  path: string;
+  declaredValue: unknown;
+  liveValue: unknown;
+}): FieldClaim {
+  if (!isClaimed(input.claimed, input.path)) return "undeclared";
+  return deepValueEqual(input.declaredValue, input.liveValue) ? "declared-equal" : "declared-changed";
+}
+
+/**
+ * Who holds an undeclared live field, and which source said so.
+ *
+ * The manager wins where the substrate records one: "owned by `hpa-controller`"
+ * and "chant never set it" are the same verdict with very different amounts of
+ * information in them, and an operator can act on the first. The claim is the
+ * fallback, and it answers on every substrate.
+ */
+export function heldBy(fieldOwners: Record<string, string> | undefined, path: string): {
+  holder?: string;
+  source: FieldClaimSource;
+} {
+  const manager = fieldOwners?.[path];
+  if (manager) return { holder: manager, source: "field-manager" };
+  return { source: "claimed-fields" };
+}

package/src/cli/build-params-cli.ts

@@ -9,8 +9,8 @@ import { formatError, formatInfo } from "./format";
  * out (chant #1108) so every command that discovers project source before
  * running it resolves `chant.config.ts`'s declared `buildParams` the exact
  * same way: `chant build` (`../commands/build.ts`'s `buildCommand`), the
- * component deploy driver (`./handlers/run.ts`'s `chant run --components`
- * local + `--temporal` paths), and generate mode (`./handlers/build.ts`'s
+ * component deploy driver (`./handlers/run.ts`'s `chant run --components`),
+ * and generate mode (`./handlers/build.ts`'s
  * `chant build --components --generate <lexicon>`).
  *
  * Before #1108, only `buildCommand` ran this sequence — `chant run

package/src/cli/command-group.ts

@@ -57,6 +57,20 @@ export interface CommandGroup {
   description: string;
   /** Verbs in this group. */
   commands: CommandGroupCommand[];
+  /**
+   * The verb to run when the group name is given on its own — `chant acp`
+   * rather than `chant acp serve` (#2125). Named here rather than assumed to
+   * be the first verb, because a group whose bare form should be a usage
+   * error (`chant kube`) must stay one: omitting this field is how a group
+   * says it has no default.
+   *
+   * The token after the group name decides which reading applies, and that
+   * decision belongs to the caller that still holds the raw argv
+   * (`../cli/main.ts`'s `tryPluginCommand`): with a default verb, `chant acp
+   * --durable-requests` has no verb token to consume, so the flag is the
+   * default verb's argument rather than a verb it does not have.
+   */
+  defaultVerb?: string;
 }
 
 /**

package/src/cli/commands/__fixtures__/audit-terraform/infra/.terraform/providers/lock.txt

@@ -0,0 +1 @@
+pretend-provider-lock-metadata

package/src/cli/commands/__fixtures__/audit-terraform/infra/main.tf

@@ -0,0 +1 @@
+resource "null_resource" "root" {}

package/src/cli/commands/__fixtures__/audit-terraform/infra/modules/foo/main.tf

@@ -0,0 +1 @@
+resource "null_resource" "foo" {}

package/src/cli/commands/__fixtures__/audit-terraform/infra/variables.tf

@@ -0,0 +1,3 @@
+variable "region" {
+  type = string
+}

package/src/cli/commands/__fixtures__/init-lexicon-output/package.json

@@ -8,8 +8,16 @@
     "dist/"
   ],
   "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*",
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./src/*.ts"
+    },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
     "./types": "./dist/types/index.d.ts"
@@ -18,8 +26,9 @@
     "generate": "npx tsx src/codegen/generate-cli.ts",
     "validate": "npx tsx src/validate-cli.ts",
     "docs": "npx tsx src/codegen/docs-cli.ts",
-    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
-    "prepack": "npm run generate && npm run validate && npm run build"
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
+    "bundle": "tsx src/package-cli.ts"
   },
   "devDependencies": {
     "@intentius/chant": "*",

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });

package/src/cli/commands/__fixtures__/init-lexicon-output/src/codegen/package.ts

@@ -15,6 +15,7 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
     buildManifest: (genResult) => ({
       name: "fixture",
       version: "0.0.1",
+      chantVersion: ">=0.1.0",
     }),
     srcDir,
     collectSkills: () => new Map(),

package/src/cli/commands/__fixtures__/init-lexicon-output/src/package-cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+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}`);