@intentset/cli 0.1.0

package/src/commands/evidence.ts

@@ -0,0 +1,180 @@
+/**
+ * `intentset evidence import` (Core §8): a test runner's report turned into
+ * run records bound to this repository's snapshot. A verification's
+ * `selector` is matched against each test's full title, and every
+ * verification whose selector no test matched is listed, since it gets no
+ * record from this run and reads as missing. Evidence must name the commit
+ * it ran at, so an unknown commit refuses. Writes the one file `--out` names,
+ * and never over an existing one: earlier records are history.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { compareStrings } from "@intentset/core";
+import { type ParsedRun, isUtcTimestamp, parseNodeTap, parseVitestJson, toRunRecords } from "@intentset/verification";
+import { count, type Io } from "../output.ts";
+import { outputProblem } from "../outputs.ts";
+import type { Session } from "../session.ts";
+
+export const REPORTERS = {
+  vitest: { tool: "vitest", parse: (text: string) => parseVitestJson(JSON.parse(text)) },
+  "node-tap": { tool: "node:test", parse: (text: string) => parseNodeTap(text) },
+} as const;
+
+export interface EvidenceImportOptions {
+  from?: string;
+  report?: string;
+  out?: string;
+  product?: string;
+  release?: string;
+  environment?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  uriBase?: string;
+  toolVersion?: string;
+}
+
+const URI = /^[A-Za-z][A-Za-z0-9+.-]*:\S+$/;
+
+/** Problems that need no repository, so a typo costs nothing. */
+export function evidenceUsageProblem(options: EvidenceImportOptions): string | null {
+  if (options.from === undefined || !Object.hasOwn(REPORTERS, options.from)) {
+    return `--from ${options.from ?? "(missing)"}: the reporters are ${Object.keys(REPORTERS).join(" and ")}`;
+  }
+  if (options.report === undefined) return "a report file is required: evidence import --from <reporter> <report>";
+  for (const [flag, value] of [
+    ["--out", options.out],
+    ["--product", options.product],
+    ["--release", options.release],
+  ] as const) {
+    if (value === undefined || value === "") return `${flag} is required`;
+  }
+  for (const [flag, value] of [
+    ["--started-at", options.startedAt],
+    ["--finished-at", options.finishedAt],
+  ] as const) {
+    if (value !== undefined && !isUtcTimestamp(value)) {
+      return `${flag} ${value}: give a UTC time such as 2026-10-02T12:00:00Z`;
+    }
+  }
+  if (options.uriBase !== undefined && !URI.test(options.uriBase)) {
+    return `--uri-base ${options.uriBase}: give a URI with a scheme, such as https://ci.example/runs/42`;
+  }
+  if (options.environment !== undefined && options.environment.trim() === "") return "--environment is empty";
+  return null;
+}
+
+export function evidenceImportCommand(session: Session, options: EvidenceImportOptions, io: Io): number {
+  const fail = (message: string) => {
+    io.stderr(`intentset evidence import: ${message}\n`);
+    return 2;
+  };
+  const { repo, snapshot, result } = session;
+  const graph = result.graph;
+  const reporter = REPORTERS[options.from as keyof typeof REPORTERS];
+  const product = options.product as string;
+  const release = options.release as string;
+
+  if (snapshot.commit === null) {
+    return fail(`evidence must name the commit it ran at, and none could be read: ${snapshot.commitUnavailable}`);
+  }
+  if (snapshot.uncommitted === true) {
+    return fail(
+      `tracked files differ from commit ${snapshot.commit}, so records bound to it would name a commit the run did not test; commit first (Core §8).`,
+    );
+  }
+  if (graph.artifacts.get(product)?.meta.type !== "product") {
+    return fail(`--product ${product} is not a product in this graph.`);
+  }
+  if (repo.registries.releases.length > 0 && !repo.registries.releases.includes(release)) {
+    return fail(`--release ${release} is not a release in the registries; labels match exactly (Core §7).`);
+  }
+
+  const reportFile = resolve(io.cwd, options.report as string);
+  let parsed: ParsedRun;
+  let modified: string;
+  try {
+    modified = statSync(reportFile).mtime.toISOString();
+    parsed = reporter.parse(readFileSync(reportFile, "utf8"));
+  } catch (error) {
+    return fail(`could not read ${options.report} as ${options.from} output: ${(error as Error).message}`);
+  }
+
+  const target = resolve(io.cwd, options.out as string);
+  const problem = outputProblem(repo, target);
+  if (problem !== null) return fail(`--out ${options.out} ${problem}; nothing was written.`);
+  if (existsSync(target)) {
+    return fail(`--out ${options.out} exists; run records are history, so import into a new file.`);
+  }
+
+  // Selector -> verification, from the automated verifications that are not retired, first ID winning a shared selector.
+  const verifications = new Map<string, string>();
+  const shared: string[] = [];
+  for (const id of [...graph.artifacts.keys()].sort(compareStrings)) {
+    const meta = graph.artifacts.get(id)?.meta;
+    if (meta?.type !== "verification" || meta.status === "retired" || meta.verification?.method !== "automated")
+      continue;
+    const selector = meta.verification.selector;
+    if (verifications.has(selector)) shared.push(`${selector} (${verifications.get(selector)} and ${id})`);
+    else verifications.set(selector, id);
+  }
+
+  const startedAt = options.startedAt ?? modified;
+  const finishedAt = options.finishedAt ?? modified;
+  let converted: ReturnType<typeof toRunRecords>;
+  try {
+    converted = toRunRecords(parsed, {
+      verifications,
+      commit: snapshot.commit,
+      graphHash: snapshot.graphHash,
+      environment: options.environment ?? "local",
+      scope: { product, release },
+      tool: { name: reporter.tool, version: options.toolVersion ?? "unknown" },
+      startedAt,
+      finishedAt,
+      uriBase: options.uriBase ?? pathToFileURL(reportFile).href,
+    });
+  } catch (error) {
+    return fail((error as Error).message);
+  }
+  try {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(converted.records, null, 2)}\n`, { flag: "wx" });
+  } catch (error) {
+    return fail(`could not write ${options.out}: ${(error as Error).message}`);
+  }
+
+  const lines = [
+    `Imported ${count(converted.records.length, "run record")} from ${options.report} (${options.from}, ${count(parsed.tests.length, "test")}) into ${options.out}`,
+    `  bound to commit ${snapshot.commit}, graph ${snapshot.graphHash}, for ${product} ${release}, environment ${options.environment ?? "local"}`,
+  ];
+  if (options.startedAt === undefined || options.finishedAt === undefined) {
+    lines.push(
+      `  timestamps: the report file's modification time, ${modified}, stands in for the run's ` +
+        `${options.startedAt === undefined && options.finishedAt === undefined ? "start and finish" : options.startedAt === undefined ? "start" : "finish"}; ` +
+        "pass --started-at and --finished-at to record the run's own",
+    );
+  }
+  for (const record of converted.records) {
+    lines.push(`  ${record.verificationId}  ${record.result}  ${record.rationale ?? ""}`.trimEnd());
+  }
+  lines.push(
+    `Unmatched selectors (${converted.unmatched.length}): ${converted.unmatched.length === 0 ? "none" : "no test title carries them, so their verifications get no record from this run and read as missing"}`,
+    ...converted.unmatched.map((selector) => `  - ${selector} (${verifications.get(selector)})`),
+  );
+  if (shared.length > 0) {
+    lines.push(`Selectors shared by two verifications, matched to the first only (${shared.length}):`);
+    lines.push(...shared.map((item) => `  - ${item}`));
+  }
+  if (parsed.problems.length > 0) {
+    lines.push(`Problems in the report that no test title carries (${parsed.problems.length}):`);
+    lines.push(...parsed.problems.map((item) => `  - ${item}`));
+  }
+  if (!result.ok) {
+    lines.push(
+      `Validation has ${count(session.errors, "error")}; the records are bound to that graph. Run \`intentset validate\`.`,
+    );
+  }
+  io.stdout(`${lines.join("\n")}\n`);
+  return result.ok ? 0 : 1;
+}

package/src/commands/graph.ts

@@ -0,0 +1,89 @@
+/**
+ * `intentset graph --format json` (Core §12): the `intentset/export/0.1`
+ * envelope over the validated repository. Printed to stdout, or written to
+ * the one file `--out` names, which may not be any file the repository reads.
+ * A failing validation still exports, with `validation.status: "fail"`, and
+ * exits 1.
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ID_PATTERN, exportGraph } from "@intentset/core";
+import type { Io } from "../output.ts";
+import { outputProblem } from "../outputs.ts";
+import type { Session } from "../session.ts";
+
+export interface GraphOptions {
+  format?: string;
+  includeBodies: boolean;
+  release?: string;
+  out?: string;
+  generatedAt?: string;
+}
+
+/** The export schema's generatedAt pattern. */
+const ISO_8601 = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})$/;
+
+/** Check the options that need no repository, so a typo costs nothing. Returns a message, or null. */
+export function graphUsageProblem(options: GraphOptions): string | null {
+  if (options.format !== undefined && options.format !== "json") {
+    return `--format ${options.format}: the only format is json`;
+  }
+  if (options.release !== undefined && parseRelease(options.release) === null) {
+    return `--release ${options.release}: write it as <product ID>:<label>, such as PRD-LANTERN:pilot-1`;
+  }
+  if (options.generatedAt !== undefined && !ISO_8601.test(options.generatedAt)) {
+    return `--generated-at ${options.generatedAt}: give an ISO 8601 time such as 2026-10-02T12:00:00Z`;
+  }
+  return null;
+}
+
+/** `<product>:<label>`, split at the first colon; the label is opaque and matched exactly (Core §7). */
+export function parseRelease(text: string): { product: string; label: string } | null {
+  const colon = text.indexOf(":");
+  if (colon === -1) return null;
+  const product = text.slice(0, colon);
+  const label = text.slice(colon + 1);
+  if (!ID_PATTERN.test(product) || label === "") return null;
+  return { product, label };
+}
+
+export function graphCommand(session: Session, options: GraphOptions, io: Io): number {
+  const { repo, result, snapshot } = session;
+  const release = options.release === undefined ? null : parseRelease(options.release);
+  if (release !== null && result.graph.artifacts.get(release.product)?.meta.type !== "product") {
+    io.stderr(`intentset graph: --release names ${release.product}, which is not a product in this graph.\n`);
+    return 2;
+  }
+  const envelope = exportGraph(result, repo.registries, {
+    repository: repo.config.repository,
+    commit: snapshot.commit,
+    ...(snapshot.commitUnavailable === undefined ? {} : { commitUnavailable: snapshot.commitUnavailable }),
+    scope: repo.config.scope,
+    level: session.level,
+    release,
+    ...(options.generatedAt === undefined ? {} : { generatedAt: options.generatedAt }),
+    includeBodies: options.includeBodies,
+  });
+  const text = `${JSON.stringify(envelope, null, 2)}\n`;
+
+  if (options.out === undefined) {
+    io.stdout(text);
+  } else {
+    const target = resolve(io.cwd, options.out);
+    const problem = outputProblem(repo, target);
+    if (problem !== null) {
+      io.stderr(`intentset graph: --out ${options.out} ${problem}; tools never rewrite those.\n`);
+      return 2;
+    }
+    try {
+      writeFileSync(target, text);
+    } catch (error) {
+      io.stderr(`intentset graph: could not write ${options.out}: ${(error as Error).message}\n`);
+      return 2;
+    }
+    io.stderr(
+      `intentset graph: wrote ${options.out} (${envelope.artifacts.length} artifacts, ${envelope.validation.status})\n`,
+    );
+  }
+  return result.ok ? 0 : 1;
+}

package/src/commands/impact.ts

@@ -0,0 +1,97 @@
+/**
+ * `intentset impact <ID>` (Core §10): what depends on an artifact. Direct
+ * dependents apart from candidates further downstream, each with the path
+ * that reached it and a reason per step; the start's own rules, contracts and
+ * decisions as review context; navigation ancestors. Every report names its
+ * snapshot and says that reachability is not proof. Never writes.
+ */
+import { type ImpactHit, type ImpactReport, impact } from "@intentset/core";
+import { formatDiagnostic, type Io, json, snapshotLine, TOOL } from "../output.ts";
+import type { Session } from "../session.ts";
+import { unresolved, validationLine, validationSummary } from "./shared.ts";
+
+export const REACHABILITY_NOTE =
+  "Reachability through authored links marks an artifact for review; it is not proof that runtime behavior changed (Core §10).";
+
+export function impactCommand(session: Session, id: string, asJson: boolean, io: Io): number {
+  const { graph } = session.result;
+  const level = session.level;
+  const start = graph.artifacts.get(id);
+  if (start === undefined) {
+    const diagnostic = unresolved(id, session);
+    if (asJson) {
+      io.stdout(
+        json({
+          tool: TOOL,
+          snapshot: session.snapshot,
+          validation: validationSummary(session, level),
+          start: null,
+          diagnostics: [diagnostic],
+        }),
+      );
+    } else {
+      io.stderr(formatDiagnostic(diagnostic));
+    }
+    return 1;
+  }
+
+  const report = impact(graph, id);
+  if (asJson) {
+    io.stdout(
+      json({
+        tool: TOOL,
+        snapshot: session.snapshot,
+        validation: validationSummary(session, level),
+        note: REACHABILITY_NOTE,
+        start: { id, type: start.meta.type, title: start.meta.title, path: start.path },
+        direct: report.direct,
+        candidates: report.candidates,
+        context: report.context,
+        ancestors: report.ancestors,
+        diagnostics: [],
+      }),
+    );
+  } else {
+    io.stdout(renderImpact(report, session, level, `${start.meta.type} "${start.meta.title}"`));
+  }
+  return session.result.ok ? 0 : 1;
+}
+
+function renderImpact(report: ImpactReport, session: Session, level: string, described: string): string {
+  const lines = [
+    `Impact of ${report.start}, ${described}`,
+    snapshotLine(session.snapshot),
+    validationLine(session, level),
+    REACHABILITY_NOTE,
+    "",
+  ];
+  const section = (title: string, gloss: string, hits: ImpactHit[]) => {
+    lines.push(`${title} (${hits.length}): ${gloss}`);
+    if (hits.length === 0) lines.push("  none");
+    for (const hit of hits) {
+      lines.push(`  ${hit.id}  ${hit.type}  ${hit.title}`);
+      lines.push(`    path: ${pathText(report.start, hit)}`);
+      lines.push(`    reason: ${hit.path.map((step) => step.reason).join(" ")}`);
+    }
+    lines.push("");
+  };
+  section("Direct", "one link from the start", report.direct);
+  section("Candidates", "reachable beyond the direct set, for review", report.candidates);
+  section("Review context", "the start's own rules, contracts and decisions", report.context);
+  lines.push(`Ancestors: ${report.ancestors.length === 0 ? "none" : report.ancestors.join(" > ")}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * A hit's path as authored edges, written in the direction they were authored.
+ * A reverse step (`kind←`) is an edge from the step to the node before it, so
+ * a chain reads from the hit back to the start: `C --dependsOn--> B --implements--> A`.
+ * A context step (`kind→`) is an edge from the start to the hit.
+ */
+export function pathText(start: string, hit: ImpactHit): string {
+  const forward = hit.path.length === 1 && hit.path[0].via.endsWith("→");
+  if (forward) return `${start} --${hit.path[0].via.slice(0, -1)}--> ${hit.id}`;
+  let text = start;
+  for (const step of hit.path) text = `${step.id} --${step.via.slice(0, -1)}--> ${text}`;
+  return text;
+}

package/src/commands/init.ts

@@ -0,0 +1,138 @@
+/**
+ * `intentset init`: the one command that writes, and it only creates. It
+ * writes `.intentset/config.yaml` and an empty-but-valid
+ * `.intentset/registries.yaml`, and with `--example` the scheduling example's
+ * records under `product/scheduling/` and its registries in place of the
+ * empty ones. Every target is checked before anything is written, and each
+ * file is opened with exclusive create, so an existing file is never
+ * overwritten, not even by a race.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compareStrings, DEFAULT_IGNORE, readConfig, readRegistries } from "@intentset/core";
+import type { Io } from "../output.ts";
+import { CONFIG_PATH } from "../repository.ts";
+
+export const REGISTRIES_PATH = ".intentset/registries.yaml";
+export const DEFAULT_INIT_SCOPE = "product/**/*.md";
+const EXAMPLE_TARGET = "product/scheduling";
+
+export interface InitOptions {
+  root?: string;
+  repository?: string;
+  example: boolean;
+}
+
+/** YAML double-quoted scalar; the strict reader takes JSON's escapes. */
+function quote(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function configText(repository: string): string {
+  return [
+    "# Intentset configuration (Core §11): the repository scope a conformance claim is about.",
+    "# Written by `intentset init`. Patterns are repository-relative: literal segments, * within",
+    "# one segment, ** across segments.",
+    `repository: ${quote(repository)}`,
+    "scope:",
+    `  - ${quote(DEFAULT_INIT_SCOPE)}`,
+    `registries: ${quote(REGISTRIES_PATH)}`,
+    "ignore:",
+    ...DEFAULT_IGNORE.map((pattern) => `  - ${quote(pattern)}`),
+    "",
+  ].join("\n");
+}
+
+export const EMPTY_REGISTRIES_TEXT = [
+  "# Intentset registries (Core §4, §7; VSA §3): the owners, audiences, release dimensions",
+  "# and shared resources records may name. An empty registry reads as not declared, and",
+  "# validate warns (CORE005) when a record names a value it could not check.",
+  "owners: []",
+  "audiences: []",
+  "releases: []",
+  "roles: []",
+  "editions: []",
+  "flags: []",
+  "resources: []",
+  "",
+].join("\n");
+
+/**
+ * The scheduling example: this repository's own copy when running from a
+ * checkout, otherwise the one @intentset/conformance-suite ships. Null when
+ * neither is present.
+ */
+export async function exampleDir(): Promise<string | null> {
+  const candidates = [fileURLToPath(new URL("../../../../examples/scheduling/", import.meta.url))];
+  try {
+    const suite = (await import("@intentset/conformance-suite")) as { examplesPath?: string };
+    if (typeof suite.examplesPath === "string") candidates.push(join(suite.examplesPath, "scheduling"));
+  } catch {
+    // Not installed: the checkout's copy is the only candidate.
+  }
+  return candidates.find((dir) => existsSync(join(dir, "registries.yaml"))) ?? null;
+}
+
+export async function initCommand(options: InitOptions, io: Io): Promise<number> {
+  const root = resolve(io.cwd, options.root ?? ".");
+  const repository = options.repository ?? basename(root);
+  if (repository.trim() === "" || /[\r\n]/.test(repository)) {
+    io.stderr("intentset init: --repository must be a non-empty name on one line, such as org/name.\n");
+    return 2;
+  }
+
+  // Everything to write, decided before anything is written.
+  const files = new Map<string, string>([[CONFIG_PATH, configText(repository)]]);
+  let registries = EMPTY_REGISTRIES_TEXT;
+  if (options.example) {
+    const dir = await exampleDir();
+    if (dir === null) {
+      io.stderr(
+        "intentset init: --example needs the scheduling example, which is in an Intentset checkout under\n" +
+          "examples/scheduling and in the @intentset/conformance-suite package. Neither was found; install\n" +
+          "@intentset/conformance-suite beside @intentset/cli, or run init without --example.\n",
+      );
+      return 2;
+    }
+    registries = readFileSync(join(dir, "registries.yaml"), "utf8");
+    for (const name of readdirSync(dir)
+      .filter((n) => n.endsWith(".md"))
+      .sort(compareStrings)) {
+      files.set(`${EXAMPLE_TARGET}/${name}`, readFileSync(join(dir, name), "utf8"));
+    }
+  }
+  files.set(REGISTRIES_PATH, registries);
+
+  // What init writes must read back clean, or it has handed the user a broken repository.
+  const config = readConfig(files.get(CONFIG_PATH) as string, CONFIG_PATH);
+  const registry = readRegistries(registries, REGISTRIES_PATH);
+  if (config.diagnostics.length > 0 || registry.diagnostics.length > 0) {
+    io.stderr("intentset init: the files it would write do not read back clean; nothing was written.\n");
+    return 2;
+  }
+
+  const ordered = [...files.keys()].sort(compareStrings);
+  const existing = ordered.filter((path) => existsSync(join(root, path)));
+  if (existing.length > 0) {
+    io.stderr(
+      `intentset init: refusing to overwrite ${existing.join(", ")}; init only creates files.\n` +
+        "Remove them first if a fresh start is what you want.\n",
+    );
+    return 2;
+  }
+  for (const path of ordered) {
+    const target = join(root, path);
+    try {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, files.get(path) as string, { flag: "wx" });
+    } catch (error) {
+      io.stderr(`intentset init: could not create ${path}: ${(error as Error).message}\n`);
+      return 2;
+    }
+    io.stdout(`created ${path}\n`);
+  }
+  const scope = options.example ? `${files.size - 2} example records in scope` : "an empty scope";
+  io.stdout(`Initialized ${quote(repository)} with ${scope}. Next: intentset validate\n`);
+  return 0;
+}

package/src/commands/mcp.ts

@@ -0,0 +1,143 @@
+/**
+ * `intentset mcp` (Core §10): the read-only MCP server over stdio, in the
+ * mode the operator chooses here and no client can change.
+ *
+ *   engineering  the validated graph: lookup, context, impact and search,
+ *                every result naming the snapshot and its source paths
+ *   customer     a publication made in memory exactly as `publish` makes
+ *                one, and its retrieval chunks; the server is never given
+ *                the graph, so it has no engineering record to leak
+ *
+ * stdout carries the protocol and nothing else: the startup line and every
+ * diagnostic go to stderr. A customer request that the publisher refuses,
+ * or a graph that does not validate, stops before any server starts.
+ */
+import { type Visibility, sortDiagnostics } from "@intentset/core";
+import { createIntentsetServer, runStdio } from "@intentset/mcp";
+import { type PublicationRequest, publish, toChunks } from "@intentset/publisher";
+import { count, formatDiagnostic, type Io, snapshotLine } from "../output.ts";
+import { openSession, type SessionOptions } from "../session.ts";
+
+export type McpServer = ReturnType<typeof createIntentsetServer>;
+
+export interface McpOptions {
+  mode?: string;
+  includeRestricted: boolean;
+  visibility?: string;
+  audience?: string;
+  product?: string;
+  release?: string;
+  role?: string;
+  edition?: string;
+  flags: string[];
+  authorizedInternal: boolean;
+  authorizedRestricted: boolean;
+  publishedAt?: string;
+}
+
+export const MCP_MODES = ["engineering", "customer"] as const;
+
+export function mcpUsageProblem(options: McpOptions): string | null {
+  if (options.mode === undefined || !(MCP_MODES as readonly string[]).includes(options.mode)) {
+    return `--mode ${options.mode ?? "(missing)"}: the modes are engineering and customer, and one must be chosen`;
+  }
+  const request = [
+    options.visibility,
+    options.audience,
+    options.product,
+    options.release,
+    options.role,
+    options.edition,
+  ].some((value) => value !== undefined);
+  if (options.mode === "engineering" && (request || options.flags.length > 0)) {
+    return "publication request options belong to --mode customer";
+  }
+  if (options.mode === "customer") {
+    if (options.includeRestricted) return "--include-restricted belongs to --mode engineering";
+    if (options.visibility !== undefined && options.visibility !== "public" && options.visibility !== "customer") {
+      return `--visibility ${options.visibility}: customer mode serves a public or customer projection only`;
+    }
+  }
+  return null;
+}
+
+/** The server the command would run, or the exit code after saying why there is none. Writes only to stderr. */
+export function buildMcpServer(options: McpOptions, sessionOptions: SessionOptions, io: Io): McpServer | number {
+  const session = openSession("mcp", sessionOptions, io);
+  if (typeof session === "number") return session;
+  const { result, snapshot, repo } = session;
+  const summary = `${count(result.graph.artifacts.size, "artifact")}, ${count(session.errors, "error")}, ${count(session.warnings, "warning")} at ${session.level}`;
+
+  if (options.mode === "engineering") {
+    if (!result.ok) {
+      io.stderr(`intentset mcp: validation has ${count(session.errors, "error")}; results may be incomplete.\n`);
+    }
+    try {
+      const server = createIntentsetServer({
+        mode: "engineering",
+        graph: result.graph,
+        snapshot: { commit: snapshot.commit, graphHash: snapshot.graphHash },
+        includeRestricted: options.includeRestricted,
+      });
+      io.stderr(
+        `intentset mcp: engineering context for ${repo.config.repository} over stdio (${summary}${
+          options.includeRestricted ? ", restricted records included" : ", restricted records withheld"
+        }). ${snapshotLine(snapshot)}\n`,
+      );
+      return server;
+    } catch (error) {
+      io.stderr(`intentset mcp: ${(error as Error).message}\n`);
+      return 2;
+    }
+  }
+
+  if (!result.ok) {
+    for (const d of session.diagnostics) io.stderr(formatDiagnostic(d));
+    io.stderr(`intentset mcp: refused: validation has ${count(session.errors, "error")}, so nothing is published.\n`);
+    return 1;
+  }
+  const request = {
+    visibility: options.visibility as Visibility,
+    audience: options.audience,
+    product: options.product,
+    release: options.release,
+    role: options.role,
+    edition: options.edition,
+    flags: options.flags,
+    authorizedInternal: options.authorizedInternal,
+    authorizedRestricted: options.authorizedRestricted,
+  } as PublicationRequest;
+  const published = publish(result.graph, repo.registries, request, {
+    snapshot: { commit: snapshot.commit, graphHash: snapshot.graphHash },
+    publishedAt: options.publishedAt ?? new Date().toISOString(),
+  });
+  for (const d of sortDiagnostics(published.diagnostics)) io.stderr(formatDiagnostic(d));
+  if (published.index.request === null) {
+    io.stderr("intentset mcp: refused: the publisher refused the request, so there is nothing to serve.\n");
+    return 1;
+  }
+  try {
+    const documents = published.documents;
+    const server = createIntentsetServer({
+      mode: "customer",
+      publication: { documents, index: published.index },
+      chunks: toChunks(documents),
+    });
+    const r = published.index.request;
+    io.stderr(
+      `intentset mcp: customer knowledge over stdio: ${count(documents.length, "published document")} for a ${r.visibility} projection, audience ${r.audience}, ${r.product} ${r.release}. ${snapshotLine(snapshot)}\n`,
+    );
+    return server;
+  } catch (error) {
+    io.stderr(`intentset mcp: ${(error as Error).message}\n`);
+    return 2;
+  }
+}
+
+export async function mcpCommand(options: McpOptions, sessionOptions: SessionOptions, io: Io): Promise<number> {
+  const server = buildMcpServer(options, sessionOptions, io);
+  if (typeof server === "number") return server;
+  io.signal?.addEventListener("abort", () => void server.close(), { once: true });
+  await runStdio(server);
+  return 0;
+}