@intentius/chant 0.124.45 → 0.124.46

package/src/cli/main.test.ts

@@ -208,9 +208,33 @@ describe("parseArgs", () => {
     expect(() => parseArgs(["build", "--unknown=value"])).toThrow(/Unknown flag: --unknown/);
   });
 
-  test("unknown short flags are still silently ignored (unchanged; out of #1127 scope)", () => {
-    const result = parseArgs(["build", "-x", "value"]);
-    expect(result.command).toBe("build");
+  test("an unknown short flag is refused like an unknown long one (#4369)", () => {
+    // Was "unknown short flags are still silently ignored": `-x` vanished and
+    // the next token became the path. #4369 refuses it with the #1127 message.
+    expect(() => parseArgs(["build", "-x", "value"])).toThrow(/Unknown flag: -x\nRun "chant --help"/);
+    expect(() => parseArgs(["search", "kind:X", "-q"])).toThrow(/Unknown flag: -q/);
+  });
+
+  test("a search query that opens with -> is the positional, not a dropped flag (#4369)", () => {
+    expect(parseArgs(["search", "->kind:Bucket"]).path).toBe("->kind:Bucket");
+    const explained = parseArgs(["search", "->kind:Bucket", "--explain"]);
+    expect(explained.path).toBe("->kind:Bucket");
+    expect(explained.explain).toBe(true);
+    expect(parseArgs(["search", "--explain", "->*[via=subnet_id]kind:aws_vpc"]).path).toBe("->*[via=subnet_id]kind:aws_vpc");
+    // Unchanged: the in-edge spelling and a leading space always worked.
+    expect(parseArgs(["search", "<-kind:Bucket"]).path).toBe("<-kind:Bucket");
+    expect(parseArgs(["search", " ->kind:Bucket"]).path).toBe(" ->kind:Bucket");
+    // A known short flag still parses as one.
+    expect(parseArgs(["search", "->kind:Bucket", "-v"]).verbose).toBe(true);
+  });
+
+  test("-- ends flag parsing: what follows is positional, unsplit (#4369)", () => {
+    const r = parseArgs(["search", "--json", "--", "-kind:X", "--explain"]);
+    expect(r.path).toBe("-kind:X");
+    expect(r.extraPositional).toBe("--explain");
+    expect(r.explain).toBeUndefined();
+    expect(r.json).toBe(true);
+    expect(parseArgs(["search", "--", "--x=y"]).path).toBe("--x=y");
   });
 
   test("parses --watch flag", () => {
@@ -846,6 +870,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace points",
       "workspace records",
       "workspace runs",
+      "workspace search",
       "workspace signers",
       "workspace status",
       "workspace trust",

package/src/cli/main.ts

@@ -170,9 +170,15 @@ Commands:
                         bundle tree, otherwise JSON path→content on stdout)
   search "<query>"      Answer an estate question with a few matching rows
                         instead of a graph dump (kind:, tag:, attr:, ->/<- edge
-                        terms; --live or --at <ref> with --env <name> reads the
-                        estate or a recorded snapshot; --show <attr>,
-                        --check-live, --check-snapshot, --fail-on-drift)
+                        terms, ->* / ->{1,3} for depth, ->[via=attr] / [to=attr]
+                        by attribute; --live or --snapshot <ref> (also --at
+                        <ref>) with --env <name> reads the estate or a
+                        recorded snapshot; --show <attr>,
+                        --count-by kind|module|attr:<name>, --explain prints
+                        paths, --json, --check-live,
+                        --check-snapshot, --fail-on-drift; cap:<name> and
+                        ->[cap=<name>] ask with a capability, and
+                        --capabilities prints the catalog)
   query "<sql>" [dir]   Run one read-only SQL statement over chant/lifecycle:
                         the resources and snapshots each lexicon observed, Op
                         runs, gates, deploys, releases and cuts, loaded into
@@ -580,6 +586,9 @@ Ops:
                         --layout-engine graphviz to use dot instead;
                         --detail 0..3: stacks|composites|declarables|attributes;
                         --lens lexicon:<n>|stack:<n>|blast:<node> (--up/--down))
+                        --format ir --capability-view: add the lexicon-neutral
+                        view capability rules read, as this project's lexicons
+                        map it, to the IR as capabilityView (#4378)
                         --components --format ir --projection gitlab|github|forgejo:
                         add the CI/pipeline projection (stages/jobs/needs) to
                         the component-graph IR, from the same generator
@@ -934,6 +943,15 @@ Workspace (level 1, #2524):
                         source and toolchain are unchanged is served from
                         the cache in $CHANT_CACHE_DIR or ~/.cache/chant;
                         --no-cache reads every member
+                        --capability-view: each member's chant adds its
+                        capability view, mapped by its own lexicons
+  workspace search "<query>" [--member <name>] [--env <name>] [--snapshot <ref> | --live] [--at <rev>] [--explain] [--count-by ...] [--json]
+                        chant search in every chant member, each under its own
+                        chant, as one read-contract document: ids are
+                        <member>/<id> as workspace graph prints them, each
+                        member is searched alone, and a member that can't be
+                        searched has a reason code. --at <rev> is the git
+                        revision; --snapshot <ref> replays a recorded snapshot
   workspace graph --composites [--at <rev>] [--member <name>] [-o <file>]
                         Each composite instance the members declare, with the
                         components whose contract can deploy it; an instance
@@ -1610,6 +1628,8 @@ export const commandRegistry: CommandDef[] = [
   // chant#2618 — audit runs no project code, at the workspace level too.
   { name: "workspace audit", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "audit") },
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
+  // #4374 — chant search in every member, under its own chant, composed with workspace graph's ids: the search document.
+  { name: "workspace search", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/search-cli")).runWorkspaceSearch(ctx) },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },
   // #3308 — a box's listing, written through chant so a tool never edits the declaration itself (ws-074).

package/src/cli/mcp/server.test.ts

@@ -1630,9 +1630,9 @@ describe("McpServer", () => {
 
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(14);
+      expect(tools).toHaveLength(15);
       expect(tools.map((t) => t.name).sort()).toEqual([
-        "build", "composites", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
+        "build", "capabilities", "composites", "explain", "import", "lifecycle-diff", "lifecycle-snapshot", "lint",
         "op-approve", "op-list", "op-report", "op-run", "op-status",
         "scaffold", "search",
       ]);
@@ -1646,7 +1646,7 @@ describe("McpServer", () => {
       const s = new McpServer([]);
       const toolsRes = await s.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
       const tools = (toolsRes.result as { tools: Array<{ name: string }> }).tools;
-      expect(tools).toHaveLength(14);
+      expect(tools).toHaveLength(15);
     });
   });
 });

package/src/cli/mcp/server.ts

@@ -7,6 +7,7 @@ import { explainTool, handleExplain } from "./tools/explain";
 import { scaffoldTool, createScaffoldHandler } from "./tools/scaffold";
 import { searchTool, createSearchHandler } from "./tools/search";
 import { compositesTool, createCompositesHandler } from "./tools/composites";
+import { capabilitiesTool, createCapabilitiesHandler } from "./tools/capabilities";
 import type { LexiconPlugin } from "../../lexicon";
 import type { McpClientInfo, McpRequest, McpResponse, McpRequestMeta, ToolDefinition, ToolHandler, ResourceDefinition } from "./types";
 import { findWorkspaceRoot } from "../../project-root";
@@ -126,6 +127,8 @@ export class McpServer {
     this.registerTool(scaffoldTool, createScaffoldHandler(plugins ?? []));
     this.registerTool(searchTool, createSearchHandler(plugins ?? []));
     this.registerTool(compositesTool, createCompositesHandler(plugins ?? []));
+    // The capability catalog (#4375), the read contract's capabilities document.
+    this.registerTool(capabilitiesTool, createCapabilitiesHandler(options.workspace?.cwd ?? process.cwd(), options.workspace?.chantCommand));
 
     // Register state tools
     const snapshot = createSnapshotTool(plugins ?? []);

package/src/cli/mcp/tools/capabilities.ts

@@ -0,0 +1,32 @@
+/**
+ * The `capabilities` tool of `chant serve mcp` (#4375): the capability
+ * catalog `chant search` answers `cap:` terms with, as the read contract's
+ * `capabilities` document (capabilities.schema.json).
+ *
+ * Like the workspace reads, it runs the command and returns the document it
+ * printed, unchanged: `chant workspace search --capabilities --json` inside a
+ * declared workspace, where the workspace's chant runs the rules, and `chant
+ * search --capabilities --json` anywhere else. It is served everywhere, since
+ * a plain project's agent asks the same questions.
+ */
+import { findWorkspaceRoot } from "../../../project-root";
+import type { ToolDefinition, ToolHandler } from "../types";
+import { ownChantCommand, runRead, type ChantCommand } from "../workspace-tools";
+
+export const capabilitiesTool: ToolDefinition = {
+  name: "capabilities",
+  description:
+    "The capability catalog for chant search (capabilities.schema.json, #4375): each capability's name, meaning, parameters, the search term that asks for it (cap:<name> for a set, ->[cap=<name>] for an edge), the questions it answers, whether each lexicon can supply it, what it does not evaluate, and its rule. " +
+    "Read it once per session, then ask estate questions with those terms, such as cap:internet-reachable(22) or cap:stores-data <-[cap=reaches]<role>. Not the resource-type catalog: that is the search tool. " +
+    "Returns the document chant search --capabilities --json prints (chant workspace search --capabilities --json inside a declared workspace), unchanged.",
+  inputSchema: { type: "object", properties: {} },
+};
+
+/** The argv the tool runs in `cwd`: the workspace form inside a declared workspace. */
+export function capabilitiesArgv(cwd: string): string[] {
+  return findWorkspaceRoot(cwd) ? ["workspace", "search", "--capabilities", "--json"] : ["search", "--capabilities", "--json"];
+}
+
+export function createCapabilitiesHandler(cwd: string, command: ChantCommand = ownChantCommand()): ToolHandler {
+  return async () => runRead(command, capabilitiesArgv(cwd), cwd);
+}

package/src/cli/mcp/workspace-tools.e2e.test.ts

@@ -85,7 +85,7 @@ describe("which servers have the workspace tools", () => {
       const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
     }
-    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer", "points-retract", "points-withdraw"]);
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-search", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer", "points-retract", "points-withdraw"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {
@@ -159,7 +159,27 @@ describe("reads", () => {
     expect(flag.content[0].text).toMatch(/at may not start with -/);
   }, 120_000);
 
+  test("workspace-search returns exactly the document chant workspace search --json prints (#4374)", async () => {
+    const s = server();
+    const res = await call(s, "workspace-search", { query: "app" });
+    expect(res.isError).toBeUndefined();
+    expect(res.structuredContent).toEqual(cli(["workspace", "search", "app", "--json"]));
+    expect(res.structuredContent).toMatchObject({ contract: 1, query: "app", at: null, source: { kind: "declared" } });
+    // A query that opens with an edge term is passed after --, and a refusal is a document.
+    const edge = await call(s, "workspace-search", { query: "->kind:Nothing", countBy: "kind" });
+    expect(edge.structuredContent).toEqual(cli(["workspace", "search", "--count-by", "kind", "--json", "--", "->kind:Nothing"]));
+    const refused = await call(s, "workspace-search", { query: "app", at: "latest" });
+    expect(refused.structuredContent).toMatchObject({ error: { code: "revision-unknown", hint: expect.stringContaining("--snapshot latest") } });
+  }, 240_000);
+
   test("the conformance suite's argv maps to the tool that answers it", () => {
+    expect(mcpToolCall(["workspace", "search", "app", "--member", "delivery", "--snapshot", "latest", "--env", "dev", "--json"])).toEqual({
+      name: "workspace-search",
+      arguments: { query: "app", member: ["delivery"], snapshot: "latest", env: "dev" },
+    });
+    expect(readArgv("workspace-search", { query: "->kind:X", member: ["delivery"], snapshot: "latest", env: "dev" })).toEqual([
+      "workspace", "search", "--member", "delivery", "--env", "dev", "--snapshot", "latest", "--json", "--", "->kind:X",
+    ]);
     expect(mcpToolCall(["workspace", "records", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { kind: KIND } });
     expect(mcpToolCall(["workspace", "records", "--uncommitted", "--kind", KIND, "--json"])).toEqual({ name: "workspace-records", arguments: { uncommitted: true, kind: KIND } });
     expect(readArgv("workspace-records", { kind: KIND, uncommitted: true })).toEqual(["workspace", "records", "--kind", KIND, "--uncommitted", "--json"]);

package/src/cli/mcp/workspace-tools.ts

@@ -5,7 +5,7 @@
  * Served when the server starts at or inside a declared workspace. Each tool
  * is a thin call into the code the CLI runs:
  *
- * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`,
+ * - The reads (`workspace-ls`, `workspace-status`, `workspace-graph`, `workspace-search`,
  *   `workspace-changes`, `workspace-records`, `workspace-points`,
  *   `workspace-work-history`, `workspace-runs`) run `chant workspace <command>
  *   ... --json` with the chant this server runs as, in the server's
@@ -123,6 +123,27 @@ export const workspaceReadTools: ToolDefinition[] = [
       },
     },
   },
+  {
+    name: "workspace-search",
+    description:
+      "Answer an estate question over every chant member of the workspace with a few rows instead of the whole graph: chant workspace search <query> --json (search.schema.json, #4374). Returns that document unchanged. Each member is searched under its own chant and alone, ids are <member>/<id> as workspace-graph names the same nodes, and a member that can't be searched is listed with a reason code, never as zero matches. " +
+      "The query is space-separated terms that must all match: a bare word (substring of id, kind or attributes), kind:<substr> (a Terraform resource matches its type, kind:aws_instance), attr:<name>=<value>, tag:<key>=<value>, and edge terms ->X (this node references a node matching X) and <-X (referenced by one); ->*X is any depth, ->{2}X or ->{1,3}X a number of hops, ->[via=attr]X and ->[to=attr]X pick the edge by attribute, and !term negates. " +
+      "at is the git revision of the source; snapshot (with env) answers from a recorded lifecycle snapshot such as latest. They are two different times, and at refuses a snapshot ref.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The search terms. May start with -> or <-." },
+        member: { type: "array", items: { type: "string" }, description: "Only these members (--member)." },
+        env: { type: "string", description: "The environment a snapshot was recorded for (--env)." },
+        snapshot: { type: "string", description: "Answer from this recorded lifecycle snapshot, such as latest (--snapshot). Needs env." },
+        countBy: { type: "string", description: "Group the matches: kind, module or attr:<name> (--count-by). The query may then be empty." },
+        show: { type: "string", description: "Comma-separated attributes to carry on each row (--show)." },
+        explain: { type: "boolean", description: "Add each member's universe and near misses (--explain)." },
+        at: atProp,
+      },
+      required: ["query"],
+    },
+  },
   {
     name: "workspace-changes",
     description:
@@ -417,6 +438,30 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
         "--json",
       ];
     }
+    case "workspace-search": {
+      // The query is one argument after `--`, so one that opens with -> stays a query.
+      const query = params.query;
+      if (typeof query !== "string") throw new ToolInputError("query must be a string");
+      const members = params.member === undefined || params.member === null ? [] : Array.isArray(params.member) ? params.member : [params.member];
+      const memberArgs = members.flatMap((m, i) => ["--member", str({ [`member[${i}]`]: m }, `member[${i}]`, true)!]);
+      const flags = (["env", "snapshot", "show"] as const).flatMap((f) => {
+        const v = str(params, f);
+        return v !== undefined ? [`--${f}`, v] : [];
+      });
+      const countBy = str(params, "countBy");
+      return [
+        "workspace",
+        "search",
+        ...memberArgs,
+        ...flags,
+        ...(countBy !== undefined ? ["--count-by", countBy] : []),
+        ...(bool(params, "explain") ? ["--explain"] : []),
+        ...atArgs,
+        "--json",
+        "--",
+        query,
+      ];
+    }
     case "workspace-agent": {
       const name = str(params, "name", true)!;
       return ["workspace", "agent", name, "--json"];
@@ -458,7 +503,7 @@ export function readArgv(tool: string, params: Record<string, unknown>): string[
 }
 
 /** Run chant and parse the one JSON document it printed. The exit code does not matter: an error document is a document. */
-function runRead(command: ChantCommand, argv: string[], cwd: string): Promise<unknown> {
+export function runRead(command: ChantCommand, argv: string[], cwd: string): Promise<unknown> {
   return new Promise((settle, fail) => {
     const child = spawn(command[0], [...command.slice(1), ...argv], { cwd, env: { ...process.env, NO_COLOR: "1" }, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";

package/src/cli/parse-args.ts

@@ -153,13 +153,36 @@ export function parseArgs(args: string[]): ParsedArgs {
   // whose own value legitimately contains `=` (`--param=tier=production`
   // splits to flag `--param`, value `tier=production`, not further split on
   // the second `=`).
-  args = splitJoinedFlags(args, BOOLEAN_FLAGS);
+  //
+  // Tokens after a bare `--` are positionals (#4369), so they are not split.
+  const end = args.indexOf("--");
+  args = end < 0 ? splitJoinedFlags(args, BOOLEAN_FLAGS) : [...splitJoinedFlags(args.slice(0, end), BOOLEAN_FLAGS), ...args.slice(end)];
+
+  // chant #4369 — every token after a bare `--` is a positional, whatever it
+  // starts with: `chant search -- "-kind:X"` is the spelling that always works.
+  let onlyPositionals = false;
+  const positional = (arg: string): void => {
+    if (result.command) (result.positionals ??= []).push(arg);
+    if (!result.command) {
+      result.command = arg;
+    } else if (result.path === ".") {
+      result.path = arg;
+    } else if (!result.extraPositional) {
+      result.extraPositional = arg;
+    } else {
+      result.extraPositional2 = arg;
+    }
+  };
 
   let i = 0;
   while (i < args.length) {
     const arg = args[i];
 
-    if (arg === "--help" || arg === "-h") {
+    if (onlyPositionals) {
+      positional(arg);
+    } else if (arg === "--") {
+      onlyPositionals = true;
+    } else if (arg === "--help" || arg === "-h") {
       result.help = true;
     } else if (arg === "--version" || arg === "-V") {
       result.version = true;
@@ -339,6 +362,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.explain = true;
     } else if (arg === "--show") {
       result.show = args[++i];
+    } else if (arg === "--count-by") {
+      // `chant search --count-by kind|module|attr:<name>` (#4360)
+      result.countBy = args[++i];
+      if (!result.countBy || result.countBy.startsWith("-")) throw new Error("--count-by needs a grouping: --count-by kind, --count-by module or --count-by attr:<name>");
     } else if (arg === "--up") {
       result.up = true;
     } else if (arg === "--down") {
@@ -508,6 +535,16 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.deep = true;
     } else if (arg === "--at") {
       result.at = args[++i];
+    } else if (arg === "--capability-view") {
+      // `chant graph --format ir --capability-view` and `chant workspace graph --capability-view` (#4378)
+      result.capabilityView = true;
+    } else if (arg === "--capabilities") {
+      // `chant search --capabilities` and `chant workspace search --capabilities` (#4375)
+      result.capabilities = true;
+    } else if (arg === "--snapshot") {
+      // `chant search` and `chant workspace search --snapshot <ref>` (#4374)
+      result.snapshot = args[++i];
+      if (!result.snapshot || result.snapshot.startsWith("-")) throw new Error("--snapshot needs a snapshot ref: --snapshot latest");
     } else if (arg === "--kind") {
       // `chant workspace records|graph|check --kind <kind file>` (#2546, #2549)
       result.kind = args[++i];
@@ -972,17 +1009,19 @@ export function parseArgs(args: string[]): ParsedArgs {
       // every command, not scoped per-command, so "the command's known
       // flags" isn't something this loop can name in isolation.
       throw new Error(`Unknown flag: ${arg}\nRun "chant --help" to see supported flags.`);
-    } else if (!arg.startsWith("-")) {
-      if (result.command) (result.positionals ??= []).push(arg);
-      if (!result.command) {
-        result.command = arg;
-      } else if (result.path === ".") {
-        result.path = arg;
-      } else if (!result.extraPositional) {
-        result.extraPositional = arg;
-      } else {
-        result.extraPositional2 = arg;
-      }
+    } else if (/^-[A-Za-z]/.test(arg)) {
+      // chant #4369 — an unrecognised short flag (`-x`) is refused like an
+      // unrecognised `--flag` (#1127). It used to be dropped without a word,
+      // the same silent misparse #1127 closed for long flags. A lexicon's own
+      // mounted command still gets its short flags: `main` tries the plugin
+      // commands before rethrowing a parse error.
+      throw new Error(`Unknown flag: ${arg}\nRun "chant --help" to see supported flags.`);
+    } else {
+      // Anything else is a positional, including a token that starts with `-`
+      // but is not flag-shaped (#4369): `->kind:Bucket` is a search query that
+      // opens with an outgoing edge term, and dropping it made `chant search`
+      // answer for "." instead. A bare `-` is a positional too.
+      positional(arg);
     }
 
     i++;

package/src/cli/registry.ts

@@ -246,6 +246,8 @@ export interface ParsedArgs {
   show?: string;
   /** `chant search --explain` — append a footer: universe count + why non-matches were excluded (#1139). */
   explain?: boolean;
+  /** `chant search --count-by kind|module|attr:<name>`: print one count per group instead of one row per match (#4360). */
+  countBy?: string;
   /** `chant graph --lens blast:<node> --up` — include upstream producers */
   up?: boolean;
   /** `chant graph --lens blast:<node> --down` — include downstream dependents */
@@ -446,6 +448,26 @@ export interface ParsedArgs {
    * should win.
    */
   at?: string;
+  /**
+   * `chant search "<q>" --snapshot <ref> --env <name>` and `chant workspace
+   * search "<q>" --snapshot <ref>` (#4374): the recorded snapshot to answer
+   * from. Plain search also takes it as `--at <ref>`, for compatibility;
+   * everywhere else in the read contract `--at` is a git revision.
+   */
+  snapshot?: string;
+  /**
+   * `chant search --capabilities` and `chant workspace search --capabilities`
+   * (#4375): print the capability catalog, the `capabilities` document of the
+   * read contract, instead of answering a query.
+   */
+  capabilities?: boolean;
+  /**
+   * `chant graph --format ir --capability-view` (#4378): add the lexicon-neutral
+   * view capability rules read, mapped by this chant's lexicons, to the IR as
+   * `capabilityView`. `chant workspace graph --capability-view` asks each
+   * member's chant for it and carries it on the member.
+   */
+  capabilityView?: boolean;
   /** `chant workspace records --kind <path>` (#2546): the record kind file to read records through. */
   kind?: string;
   /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */

package/src/components/pr-env-ports.ts

@@ -0,0 +1,89 @@
+/**
+ * The ports `chant components pr-env` runs ./pr-env-run.ts with: the records
+ * on chant/lifecycle (`_pr-envs/records.jsonl`), the gate ledger there, and
+ * the note and status on the forge. They sit apart from ./pr-env-run.ts
+ * because the gate port loads ./pr-run.ts and ../op/gate.ts, which bring
+ * Ajv, js-yaml and the component driver. A product with its own ports
+ * imports `@intentius/chant/components/pr-env-run` and never loads these.
+ */
+
+import type { PrForge } from "../pr-forge";
+import type { PrEnvPorts } from "./pr-env-run";
+import {
+  PR_ENV_LEDGER_DIR,
+  PR_ENV_LEDGER_FILE,
+  parsePrEnvRecords,
+  prEnvNoteMarker,
+  prEnvStatusContext,
+  prEnvStatusDescription,
+  prEnvStatusState,
+  renderPrEnvNote,
+  type PrEnvReport,
+} from "./pr-environment";
+
+/**
+ * The note and the `chant/pr-env` status on the forge. A refusal from the
+ * forge warns and never fails the run.
+ */
+export function forgePrEnvPublisher(forge: PrForge, warn: (message: string) => void = () => {}): (report: PrEnvReport) => Promise<void> {
+  return async (report) => {
+    const { forgePrincipalOf } = await import("../pr-forge");
+    const note = renderPrEnvNote(report, forgePrincipalOf(forge.kind, forge.host, "<your-login>"));
+    if (report.head) {
+      try {
+        await forge.setStatus(report.head, { context: prEnvStatusContext(report.member), state: prEnvStatusState(report), description: prEnvStatusDescription(report), ...(forge.runUrl ? { url: forge.runUrl } : {}) });
+      } catch (err) {
+        warn(`could not set the ${prEnvStatusContext(report.member)} status: ${messageOf(err)}`);
+      }
+    }
+    try {
+      await forge.upsertNote(report.pr, prEnvNoteMarker(report.env, report.member), note);
+    } catch (err) {
+      warn(`could not post the note on #${report.pr}: ${messageOf(err)}`);
+    }
+  };
+}
+
+/**
+ * The ports over chant/lifecycle in `cwd` (default the working directory):
+ * the records at `_pr-envs/records.jsonl`, appended and pushed, and the gate
+ * ledger read without writing a pending fact. With `forge`, the note and
+ * status are posted and the sweep asks it whether a pull request is open.
+ */
+export function lifecyclePrEnvPorts(opts: { cwd?: string; forge?: PrForge; log?: (line: string) => void; warn?: (message: string) => void } = {}): PrEnvPorts {
+  const at = opts.cwd ? { cwd: opts.cwd } : undefined;
+  const warn = opts.warn ?? (() => {});
+  const forge = opts.forge;
+  return {
+    async readRecords() {
+      const { fetchLifecycle, readBlobFromPath } = await import("../lifecycle/git");
+      await fetchLifecycle(at).catch(() => false);
+      return parsePrEnvRecords(await readBlobFromPath(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, at));
+    },
+    async appendRecord(record) {
+      const { appendLedgerLine, fetchLifecycle, pushLifecycleReport } = await import("../lifecycle/git");
+      try {
+        await fetchLifecycle(at).catch(() => false);
+        await appendLedgerLine(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, JSON.stringify(record), `Pull request environment ${record.env} ${record.kind} (${record.result})`, at);
+        const pushed = await pushLifecycleReport(at);
+        if (pushed.pushWarning) warn(pushed.pushWarning);
+      } catch (err) {
+        warn(`could not record ${record.env}'s ${record.kind} on chant/lifecycle: ${messageOf(err)}`);
+      }
+    },
+    async decideGate(input) {
+      const { approvalOf, decidePrGate, readOnlyLedger } = await import("./pr-run");
+      const { gitGateLedgerPort } = await import("../op/gate");
+      const approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort(at)), input));
+      return { status: approval.status, ...(approval.approvedBy ? { approvedBy: approval.approvedBy } : {}) };
+    },
+    ...(forge ? { publish: forgePrEnvPublisher(forge, warn) } : {}),
+    ...(forge?.pullRequestState ? { pullRequestState: (pr: number) => forge.pullRequestState!(pr) } : {}),
+    ...(opts.log ? { log: opts.log } : {}),
+    warn,
+  };
+}
+
+function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/components/pr-env-run-bundle.test.ts

@@ -0,0 +1,54 @@
+/**
+ * The pull request environment runs bundle alone (#4330 follow-up): a
+ * product that brings its own adapter and ports imports
+ * `@intentius/chant/components/pr-env-run` into one bundled file, without the
+ * gate, Ajv, js-yaml or the config loader. The ports chant uses live in
+ * ./pr-env-ports.ts. This bundles the module and reads esbuild's list of what
+ * went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "../workspace/__fixtures__/contract-repo";
+
+describe("the pr-env-run bundle", () => {
+  test("holds the runs and the records, and no gate, schema checks, YAML or config loader", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "components", "pr-env-run.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort();
+    expect(inputs).toEqual([
+      "packages/core/src/change-set.ts",
+      "packages/core/src/ci-handover.ts",
+      "packages/core/src/ci-jobs.ts",
+      "packages/core/src/components/changed-files.ts",
+      "packages/core/src/components/pr-env-run.ts",
+      "packages/core/src/components/pr-environment.ts",
+      "packages/core/src/components/pr-pipeline.ts",
+      "packages/core/src/config-environments.ts",
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/gated-waves.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/lifecycle/teardown.ts",
+      "packages/core/src/live-endpoint.ts",
+      "packages/core/src/observation.ts",
+      "packages/core/src/op/activity-runtime.ts",
+      "packages/core/src/op/emulator-lifecycle.ts",
+      "packages/core/src/plan-summary.ts",
+      "packages/core/src/pr-loop.ts",
+    ]);
+    expect(inputs.some((i) => /node_modules\/(ajv|js-yaml)\//.test(i) || i.endsWith("/op/gate.ts") || i.endsWith("/src/config.ts") || i.endsWith("/ts-loader.ts"))).toBe(false);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(40 * 1024);
+  });
+});