@intentset/cli 0.10.0 → 0.12.0

package/src/commands/list.ts

@@ -0,0 +1,346 @@
+/**
+ * `intentset list` (spec/list.md, ADR 0016): the records that match a selector, from the repository's tree or from
+ * an export, as a table, as the `intentset/list/0.1` result, or as IDs. The options compile to the selector `select`
+ * in core reads, or `--where` gives it whole. Never writes. Exit 0 whenever it answered, a failed validation included
+ * (the result says so); 1 with --check when a record matched or is undetermined; 2 for an invocation error.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  COUNT_FIELDS,
+  type CountField,
+  exportListMeta,
+  type ListOutput,
+  listOutput,
+  readExport,
+  readSelector,
+  type Selector,
+  type SelectorProblem,
+  select,
+} from "@intentset/core";
+import { count, type Io, json, snapshotLine } from "../output.ts";
+import type { Session } from "../session.ts";
+import { validationSummary } from "./shared.ts";
+
+export const LIST_FORMATS = ["table", "json", "ids"] as const;
+export type ListFormat = (typeof LIST_FORMATS)[number];
+
+/** Each field option and the selector field it fills. */
+const FIELD_OPTIONS: Record<string, string> = {
+  id: "ids",
+  type: "types",
+  status: "statuses",
+  delivery: "deliveries",
+  owner: "owners",
+  audience: "audiences",
+  visibility: "visibilities",
+  under: "under",
+  "has-extension": "hasExtension",
+  describing: "describing",
+  claims: "claims",
+};
+
+/** Each availability option and the dimension it fills. */
+const AVAILABILITY_OPTIONS: Record<string, string> = {
+  product: "products",
+  release: "releases",
+  "not-release": "notReleases",
+  role: "roles",
+  edition: "editions",
+  flag: "flags",
+};
+
+/** Every option that adds to the selector, `--has` included. */
+export const SELECTOR_OPTIONS = [...Object.keys(FIELD_OPTIONS), ...Object.keys(AVAILABILITY_OPTIONS), "has"];
+
+export interface ListOptions {
+  /** The selector options as given, in order, each repetition kept. */
+  given: Array<{ name: string; value: string }>;
+  where?: string;
+  from?: string;
+  countBy?: string;
+  format?: string;
+  json: boolean;
+  check: boolean;
+  includeRestricted: boolean;
+}
+
+const HAS_SHAPE =
+  "write it as [some:|none:|all:]<out|in>:<kind>[=<status>,...], such as out:governedBy=draft or none:in:verifies";
+
+/**
+ * The checks that need no repository, so a typo costs nothing: the format, the count field, and the selector,
+ * compiled from the options or read from --where. Returns the selector and format, or a message.
+ */
+export function listUsageProblem(
+  options: ListOptions,
+  io: Io,
+): { problem: string } | { selector: Selector; format: ListFormat; countBy: CountField | null } {
+  const format = options.format ?? (options.json ? "json" : "table");
+  if (!(LIST_FORMATS as readonly string[]).includes(format)) {
+    return { problem: `--format ${format}: the formats are ${LIST_FORMATS.join(", ")}` };
+  }
+  if (options.json && format !== "json") {
+    return { problem: `--json is --format json; it does not combine with --format ${format}` };
+  }
+  if (options.countBy !== undefined && !(COUNT_FIELDS as readonly string[]).includes(options.countBy)) {
+    return { problem: `--count-by ${options.countBy}: the fields are ${COUNT_FIELDS.join(", ")}` };
+  }
+  if (options.from !== undefined && options.includeRestricted) {
+    return { problem: "--include-restricted reads the tree; an export withheld what it withheld when it was written" };
+  }
+
+  let value: unknown;
+  let where: ((problem: SelectorProblem) => string) | undefined;
+  if (options.where !== undefined) {
+    if (options.given.length > 0) {
+      const first = options.given[0].name;
+      return { problem: `--where gives the whole selector; it does not combine with --${first}` };
+    }
+    const file = options.where;
+    try {
+      value = JSON.parse(readFileSync(resolve(io.cwd, file), "utf8"));
+    } catch (error) {
+      return { problem: `--where ${file}: ${(error as Error).message}` };
+    }
+    where = (p) => `--where ${file}: ${p.pointer === "" ? "the selector" : p.pointer}: ${p.message}`;
+  } else {
+    const compiled = compile(options.given);
+    if ("problem" in compiled) return compiled;
+    value = compiled.selector;
+    where = (p) => `${optionFor(p.pointer)}: ${p.message}`;
+  }
+  const read = readSelector(value);
+  if (!read.ok) return { problem: read.problems.map(where).join("\n  ") };
+  return {
+    selector: read.selector,
+    format: format as ListFormat,
+    countBy: (options.countBy ?? null) as CountField | null,
+  };
+}
+
+/** The options as a selector: a value may be a comma-separated list (one path for --claims), and repeats add values. */
+function compile(given: ListOptions["given"]): { selector: Record<string, unknown> } | { problem: string } {
+  const selector: Record<string, unknown> = {};
+  const availability: Record<string, string[]> = {};
+  const links: unknown[] = [];
+  const add = (target: Record<string, unknown>, key: string, values: string[]) => {
+    target[key] = [...((target[key] as string[] | undefined) ?? []), ...values];
+  };
+  for (const { name, value } of given) {
+    const values = name === "claims" ? [value] : value.split(",").map((part) => part.trim());
+    if (name === "has") {
+      const link = parseHas(value);
+      if (link === null) return { problem: `--has ${value}: ${HAS_SHAPE}` };
+      links.push(link);
+    } else if (Object.hasOwn(AVAILABILITY_OPTIONS, name)) {
+      add(availability, AVAILABILITY_OPTIONS[name], values);
+    } else {
+      add(selector, FIELD_OPTIONS[name], values);
+    }
+  }
+  if (Object.keys(availability).length > 0) selector.availability = availability;
+  if (links.length > 0) selector.links = links;
+  return { selector };
+}
+
+/** `[quantifier:]direction:kind[=status,...]`; the parts are checked by readSelector, the shape here. */
+function parseHas(value: string): Record<string, unknown> | null {
+  const equals = value.indexOf("=");
+  const head = equals === -1 ? value : value.slice(0, equals);
+  const parts = head.split(":");
+  if (parts.length < 2 || parts.length > 3 || parts.some((part) => part === "")) return null;
+  const [quantifier, direction, kind] = parts.length === 3 ? parts : ["some", ...parts];
+  const link: Record<string, unknown> = { direction, kind, quantifier };
+  if (equals !== -1)
+    link.match = {
+      statuses: value
+        .slice(equals + 1)
+        .split(",")
+        .map((part) => part.trim()),
+    };
+  return link;
+}
+
+/** The option a compiled selector's pointer came from, for a message in the command line's words. */
+function optionFor(pointer: string): string {
+  const [, field, second] = pointer.split("/");
+  if (field === "links") return "--has";
+  if (field === "availability") {
+    return `--${Object.keys(AVAILABILITY_OPTIONS).find((name) => AVAILABILITY_OPTIONS[name] === second) ?? "availability"}`;
+  }
+  return `--${Object.keys(FIELD_OPTIONS).find((name) => FIELD_OPTIONS[name] === field) ?? field}`;
+}
+
+/** The list from the repository's tree, over the session's validation. */
+export function listCommand(
+  session: Session,
+  checked: { selector: Selector; format: ListFormat; countBy: CountField | null },
+  options: ListOptions,
+  io: Io,
+): number {
+  const { repo, result, snapshot } = session;
+  const selection = select(result.graph, checked.selector, {
+    includeRestricted: options.includeRestricted,
+    registries: repo.registries,
+  });
+  const v = validationSummary(session, session.level);
+  const output = listOutput(
+    selection,
+    {
+      source: "tree",
+      snapshot: {
+        repository: repo.config.repository,
+        commit: snapshot.commit,
+        ...(snapshot.commitUnavailable === undefined ? {} : { commitUnavailable: snapshot.commitUnavailable }),
+        uncommitted: snapshot.uncommitted === true,
+        graphHash: snapshot.graphHash,
+      },
+      validation: { level: session.level, status: v.status, errors: v.errors, warnings: v.warnings },
+    },
+    checked.countBy,
+  );
+  return print(output, checked.format, options, io, "the repository's tree");
+}
+
+/** The list from an export, read as a consumer reads one (spec/export.md §5), with no repository I/O. */
+export function listFromExportCommand(
+  checked: { selector: Selector; format: ListFormat; countBy: CountField | null },
+  options: ListOptions & { from: string },
+  io: Io,
+): number {
+  let bytes: Uint8Array;
+  try {
+    bytes = readFileSync(resolve(io.cwd, options.from));
+  } catch (error) {
+    io.stderr(`intentset list: --from ${options.from}: ${(error as Error).message}\n`);
+    return 2;
+  }
+  // The file is one the caller named, so its size is not a reason to refuse it.
+  const read = readExport(bytes, { maxBytes: Math.max(bytes.length, 1) });
+  if (!read.ok) {
+    const problems = read.problems.slice(0, 5).map((p) => `  ${p.pointer || "/"} ${p.message}`);
+    io.stderr(`intentset list: --from ${options.from} is not an export this reader accepts (${read.category}):\n`);
+    io.stderr(`${problems.join("\n")}\n`);
+    return 2;
+  }
+  const output = listOutput(
+    select(read.envelope, checked.selector),
+    { source: "export", ...exportListMeta(read.envelope) },
+    checked.countBy,
+  );
+  return print(output, checked.format, options, io, `the export ${options.from}`);
+}
+
+function print(output: ListOutput, format: ListFormat, options: ListOptions, io: Io, source: string): number {
+  if (format === "json") io.stdout(json(output));
+  else if (format === "ids") {
+    io.stdout(output.rows.map((row) => `${row.id}\n`).join(""));
+    for (const line of cautions(output)) io.stderr(`intentset list: ${line}\n`);
+  } else io.stdout(renderTable(output, source));
+  const flagged = output.counts.matched + output.counts.undetermined;
+  return options.check && flagged > 0 ? 1 : 0;
+}
+
+/** What a reader of bare IDs should know, said on stderr so it never lands in a captured list. */
+function cautions(output: ListOutput): string[] {
+  const lines: string[] = [];
+  const { counts, validation } = output;
+  if (counts.undetermined > 0) {
+    lines.push(
+      `${count(counts.undetermined, "record")} undetermined, because the answer depends on a link to a withheld artifact: ${output.undetermined.join(", ")}`,
+    );
+  }
+  if (validation.status === "fail") {
+    lines.push(
+      `validation failed at ${validation.level} with ${count(validation.errors, "error")}, so the graph may be incomplete; run \`intentset validate\`.`,
+    );
+  }
+  return [...lines, ...output.notes];
+}
+
+function renderTable(output: ListOutput, source: string): string {
+  const { counts, validation, snapshot } = output;
+  const lines = [
+    snapshotLine({
+      commit: snapshot.commit,
+      ...(snapshot.commitUnavailable === undefined ? {} : { commitUnavailable: snapshot.commitUnavailable }),
+      uncommitted: snapshot.uncommitted,
+      graphHash: snapshot.graphHash,
+    }),
+    `Source: ${source}${snapshot.generatedAt === undefined ? "" : `, generated ${snapshot.generatedAt}`}`,
+    `Validation: ${validation.status} at ${validation.level}, ${count(validation.errors, "error")}, ${count(validation.warnings, "warning")}` +
+      (validation.status === "fail" ? ". The graph may be incomplete; run `intentset validate`." : ""),
+    `Selector: ${describeSelector(output.selector)}`,
+    `Considered ${counts.considered} (${counts.withheld} withheld), matched ${counts.matched}, undetermined ${counts.undetermined}`,
+    "",
+  ];
+  if (output.countBy !== null) {
+    const groups = output.countBy.groups.map((group) => [group.value ?? "(none)", String(group.count)]);
+    lines.push(...columns([[output.countBy.field, "count"], ...groups], [false, true]));
+    if (output.countBy.multiValued) {
+      lines.push(
+        "",
+        `A record counts once under each ${output.countBy.field} it names, so the counts can sum to more than ${counts.matched}.`,
+      );
+    }
+  } else if (output.rows.length === 0) {
+    lines.push("No record matches.");
+  } else {
+    const rows = output.rows.map((row) => [row.id, row.type, row.status, row.owner, row.title]);
+    lines.push(...columns([["ID", "type", "status", "owner", "title"], ...rows], []));
+  }
+  if (output.undetermined.length > 0) {
+    lines.push(
+      "",
+      `Undetermined, because the answer depends on a link to a withheld artifact (${output.undetermined.length}):`,
+      ...output.undetermined.map((id) => `  ${id}`),
+    );
+  }
+  if (output.notes.length > 0) lines.push("", ...output.notes.map((note) => `Note: ${note}`));
+  return `${lines.join("\n")}\n`;
+}
+
+/** Columns padded to their widest cell, the last left ragged; `right` aligns a column to the right. */
+function columns(table: string[][], right: boolean[]): string[] {
+  const widths = table[0].map((_, i) => Math.max(...table.map((row) => row[i].length)));
+  return table.map((row) =>
+    row
+      .map((cell, i) => {
+        if (i === row.length - 1 && !right[i]) return cell;
+        return right[i] ? cell.padStart(widths[i]) : cell.padEnd(widths[i]);
+      })
+      .join("  "),
+  );
+}
+
+/** The normalized selector in a line: fields joined with "and", values with "or". */
+export function describeSelector(selector: Selector): string {
+  const parts: string[] = [];
+  const values = (list: readonly string[]) => list.join(" or ");
+  for (const [field, label] of [
+    ["ids", "id"],
+    ["types", "type"],
+    ["statuses", "status"],
+    ["deliveries", "delivery"],
+    ["owners", "owner"],
+    ["audiences", "audience"],
+    ["visibilities", "visibility"],
+    ["under", "under"],
+    ["hasExtension", "extension"],
+  ] as const) {
+    const list = selector[field];
+    if (list !== undefined) parts.push(`${label} ${values(list)}`);
+  }
+  for (const [name, dimension] of Object.entries(AVAILABILITY_OPTIONS)) {
+    const list = selector.availability?.[dimension as keyof NonNullable<Selector["availability"]>];
+    if (list !== undefined) parts.push(`${name.replace("-", " ")} ${values(list)}`);
+  }
+  for (const link of selector.links ?? []) {
+    const match = link.match === undefined ? "" : ` matching ${describeSelector(link.match)}`;
+    parts.push(`${link.quantifier} ${link.direction} ${link.kind}${match}`);
+  }
+  if (selector.describing !== undefined) parts.push(`describing ${values(selector.describing)}`);
+  if (selector.claims !== undefined) parts.push(`claiming ${values(selector.claims)}`);
+  return parts.length === 0 ? "every record" : parts.join(", and ");
+}

package/src/commands/shared.ts

@@ -3,10 +3,30 @@
  * the graph validated, and the CORE003-style refusal for an ID the graph does
  * not hold.
  */
+import type { TypeScriptMissingError } from "@intentset/architecture";
 import { type Diagnostic, ID_PATTERN } from "@intentset/core";
 import { count } from "../output.ts";
 import type { Session } from "../session.ts";
 
+/**
+ * What the CLI says when a check needed TypeScript 7's scanner and the `typescript` the repository gave
+ * @intentset/architecture is older or absent: the version found and the command that runs the toolchain with its
+ * own TypeScript, for the arguments that were given, with pnpm (which resolves the peer to the repository's own
+ * copy) and with npm (which installs the peer beside the CLI, so it rarely gets here).
+ */
+export function typescriptMissing(error: TypeScriptMissingError, argv: readonly string[]): string {
+  const args = argv.length === 0 ? "" : ` ${argv.join(" ")}`;
+  const found =
+    error.found === null
+      ? "no `typescript` resolves from @intentset/architecture"
+      : `the \`typescript\` this repository gives @intentset/architecture is ${error.found}`;
+  return (
+    `intentset: the architecture check needs TypeScript 7, and ${found}. Run the toolchain without installing it, ` +
+    `as \`pnpm dlx --package=@intentset/cli --package=typescript@7 intentset${args}\`, or with npm as ` +
+    `\`npx -p @intentset/cli -p typescript@7 intentset${args}\`; or give the repository TypeScript 7.`
+  );
+}
+
 /** The validation state a query ran over, so a reader knows whether the graph was whole. */
 export function validationSummary(session: Session, level: string) {
   return {

package/src/glob.ts

@@ -1,58 +1,6 @@
 /**
- * The pattern language of `.intentset/config.yaml` scope and ignore lists,
- * which is VSA §3's: repository-relative POSIX paths made of literal segments,
- * `*` within one segment, and `**` across zero or more segments. Nothing else
- * is special: no `?`, no classes, no braces, no negation, so there is no
- * precedence to explain. A pattern and a path match segment by segment, and
- * `*` never crosses a `/`.
- *
- * The architecture package has its own copy for claims. Duplicating thirty
- * lines keeps the CLI's core commands independent of it.
+ * The pattern language of `.intentset/config.yaml` scope and ignore lists and of slice claims (VSA §3). It moved to
+ * `@intentset/core` in 0.11.0 with the slice helpers that use it (ADR 0016), and the CLI re-exports it, so
+ * `matchGlob` and `matchAny` stay on its public surface.
  */
-
-/** VSA §3: true when the repository-relative POSIX `path` matches `pattern`. */
-export function matchGlob(pattern: string, path: string): boolean {
-  const p = normalize(pattern).split("/");
-  const s = path.split("/");
-  // Memo of (pattern index, path index) pairs already known not to match, so
-  // several `**` in one pattern stay polynomial rather than exponential.
-  const failed = new Set<number>();
-  const width = s.length + 1;
-  const match = (i: number, j: number): boolean => {
-    if (failed.has(i * width + j)) return false;
-    let ok: boolean;
-    if (i === p.length) ok = j === s.length;
-    else if (p[i] === "**") ok = match(i + 1, j) || (j < s.length && match(i, j + 1));
-    else ok = j < s.length && matchSegment(p[i], s[j]) && match(i + 1, j + 1);
-    if (!ok) failed.add(i * width + j);
-    return ok;
-  };
-  return match(0, 0);
-}
-
-/** True when any of `patterns` matches `path`. */
-export function matchAny(patterns: readonly string[], path: string): boolean {
-  return patterns.some((pattern) => matchGlob(pattern, path));
-}
-
-/** A leading `./` names the same path; repeated `/` separate nothing. */
-function normalize(pattern: string): string {
-  return pattern.replace(/^(?:\.\/)+/, "").replace(/\/{2,}/g, "/");
-}
-
-const SEGMENTS = new Map<string, RegExp>();
-
-/** One segment: literal text, with each `*` standing for any run of characters other than `/`. */
-function matchSegment(pattern: string, name: string): boolean {
-  if (!pattern.includes("*")) return pattern === name;
-  let regex = SEGMENTS.get(pattern);
-  if (regex === undefined) {
-    const body = pattern
-      .split("*")
-      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
-      .join("[^/]*");
-    regex = new RegExp(`^${body}$`);
-    SEGMENTS.set(pattern, regex);
-  }
-  return regex.test(name);
-}
+export { matchAny, matchGlob } from "@intentset/core";

package/src/index.ts

@@ -7,4 +7,6 @@ export { main, USAGE } from "./main.ts";
 export { AGENT_GUIDE_PATH, AGENT_POINTERS, agentGuide, type PackageManager } from "./agents.ts";
 export type { Io } from "./output.ts";
 export { matchAny, matchGlob } from "./glob.ts";
+/** @deprecated Moved to `@intentset/core` in 0.11.0 (ADR 0016); import them from there. Re-exported until 0.13. */
+export { activeSlices, claimingSlices, describingRecords, isSliceCode } from "./slices.ts";
 export { CONFIG_PATH, enumerate, findRoot, loadRepository, readCommit, type Repository } from "./repository.ts";

package/src/main.ts

@@ -4,14 +4,15 @@
  * exiting, so tests run it in-process with captured io.
  *
  * Exit codes (Core §11, ADR 0004): 0 no errors, 1 validation errors, 2
- * invocation or tool failure. validate, graph, architecture check, impact,
- * context, review, evidence stale, serve, mcp and guide never write; graph --out, architecture
+ * invocation or tool failure (list exits 0 whenever it answered, and 1 only
+ * with --check). validate, graph, architecture check, impact, context, list,
+ * review, evidence stale, serve, mcp and guide never write; graph --out, architecture
  * check --write-baseline, evidence import --out, publish --out and serve
  * --out write only what they name; init only creates; migrate rewrites the
  * two version values of each record's frontmatter and nothing else.
  */
 import { parseArgs } from "node:util";
-import type { Mode } from "@intentset/architecture";
+import { type Mode, TypeScriptMissingError } from "@intentset/architecture";
 import { EVIDENCE_BINDINGS, type EvidenceBinding, LEVELS, type Level } from "@intentset/core";
 import type { RunScope } from "@intentset/verification";
 import { architectureCommand } from "./commands/architecture.ts";
@@ -22,6 +23,13 @@ import { graphCommand, graphUsageProblem, parseRelease } from "./commands/graph.
 import { guideCommand } from "./commands/guide.ts";
 import { impactCommand } from "./commands/impact.ts";
 import { initCommand } from "./commands/init.ts";
+import {
+  listCommand,
+  listFromExportCommand,
+  type ListOptions,
+  listUsageProblem,
+  SELECTOR_OPTIONS,
+} from "./commands/list.ts";
 import { migrateCommand, migrateUsageProblem } from "./commands/migrate.ts";
 import { mcpCommand, mcpUsageProblem } from "./commands/mcp.ts";
 import { publishCommand, publishUsageProblem } from "./commands/publish.ts";
@@ -29,6 +37,7 @@ import { reviewCommand } from "./commands/review.ts";
 import { serveCommand } from "./commands/serve.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { type Io, TOOL } from "./output.ts";
+import { typescriptMissing } from "./commands/shared.ts";
 import { type CarrierName, CARRIERS, findRoot } from "./repository.ts";
 import { EVIDENCE_DIR, evidenceFiles, openSession, type SessionOptions } from "./session.ts";
 
@@ -50,7 +59,7 @@ commands
   graph [--format json] [--include-bodies] [--release <product>:<label>] [--out <file>]
         [--generated-at <time>] [--report evidence|knowledge|impact|ownership|all]...
         [--include-restricted]
-                            print the intentset/export/0.4 envelope, or write it to --out;
+                            print the intentset/export/0.5 envelope, or write it to --out;
                             each --report adds a section (ownership needs L2, evidence L3; all
                             is every one the level reads). Restricted artifacts are withheld
                             and counted unless --include-restricted
@@ -69,6 +78,19 @@ commands
                             exits 1 when any needs a run
   impact <ID>               what depends on an artifact: direct, candidates, review context,
                             ancestors
+  list [--id <ID|prefix*>] [--type <t>] [--status <s>] [--delivery <d>] [--owner <o>]
+        [--audience <a>] [--visibility <v>] [--under <ID>] [--product <ID>] [--release <label>]
+        [--not-release <label>] [--role <r>] [--edition <e>] [--flag <f>]
+        [--has-extension <key>] [--has [some:|none:|all:]<out|in>:<kind>[=<status>,...]]
+        [--describing <slice>] [--claims <path>] [--where <file.json>] [--from <export.json>]
+        [--include-restricted] [--count-by <field>] [--check] [--format table|json|ids]
+                            the records that match: fields combine with AND, the values of one
+                            field (comma-separated or repeated) with OR, and matching is exact
+                            (a trailing * on an ID is a prefix). --where gives the selector as
+                            JSON instead; --from reads an export, not the tree. A record whose
+                            answer depends on a withheld link is undetermined, listed apart.
+                            Never writes; exits 0 whenever it answered, and with --check 1 when
+                            any record matched or is undetermined (spec/list.md)
   context <ID|path> [--include-restricted]
                             the bounded engineering context of an artifact, with paths and
                             bodies; given a file a slice claims, the context of that slice
@@ -126,7 +148,8 @@ options
 
 exit codes: 0 no errors, 1 validation errors (or, with review --fail-on-drift,
             unacknowledged drift; with --fail-on-baseline-growth, a baseline
-            entry the base did not hold), 2 invocation or tool failure`;
+            entry the base did not hold; with list --check, a record matched or
+            undetermined), 2 invocation or tool failure`;
 
 const COMMANDS = [
   "init",
@@ -137,6 +160,7 @@ const COMMANDS = [
   "evidence",
   "impact",
   "context",
+  "list",
   "review",
   "publish",
   "serve",
@@ -182,6 +206,7 @@ const COMMAND_OPTIONS: Record<string, string[]> = {
   ],
   impact: LEVEL_OPTIONS,
   context: ["include-restricted", ...LEVEL_OPTIONS],
+  list: [...SELECTOR_OPTIONS, "where", "from", "count-by", "check", "format", "include-restricted"],
   review: ["base", "fail-on-drift", "fail-on-baseline-growth", ...LEVEL_OPTIONS],
   serve: ["port", "host", "out", ...LEVEL_OPTIONS],
   mcp: [
@@ -223,6 +248,21 @@ const POSITIONALS: Record<string, { subs?: Record<string, number>; count: number
 };
 
 export async function main(argv: string[], io: Io): Promise<number> {
+  try {
+    return await dispatch(argv, io);
+  } catch (error) {
+    // The one failure a command raises rather than reports: the scanner's TypeScript is not there. It arrives from
+    // the first check that needs it (architecture check, validate at L2 and above, review, a subject-bound
+    // evidence read), and every other command has already run without it.
+    if (error instanceof TypeScriptMissingError) {
+      io.stderr(`${typescriptMissing(error, argv)}\n`);
+      return 2;
+    }
+    throw error;
+  }
+}
+
+async function dispatch(argv: string[], io: Io): Promise<number> {
   let parsed: ReturnType<typeof parse>;
   try {
     parsed = parse(argv);
@@ -336,7 +376,7 @@ export async function main(argv: string[], io: Io): Promise<number> {
 
   // Evidence scope: --product with --release, or graph's --release <product>:<label>.
   let scope: RunScope | null = null;
-  if ((command !== "evidence" || sub === "stale") && command !== "publish" && command !== "mcp") {
+  if ((command !== "evidence" || sub === "stale") && command !== "publish" && command !== "mcp" && command !== "list") {
     if (command === "graph" || command === "evidence") {
       const release = values.release === undefined ? null : parseRelease(values.release);
       scope = release === null ? null : { product: release.product, release: release.label };
@@ -425,6 +465,32 @@ export async function main(argv: string[], io: Io): Promise<number> {
       const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
       return typeof session === "number" ? session : impactCommand(session, args[0], values.json, io);
     }
+    case "list": {
+      const options: ListOptions = {
+        given: tokens.flatMap((token) =>
+          token.kind === "option" && SELECTOR_OPTIONS.includes(token.name)
+            ? [{ name: token.name, value: token.value ?? "" }]
+            : [],
+        ),
+        where: values.where,
+        from: values.from,
+        countBy: values["count-by"],
+        format: values.format,
+        json: values.json,
+        check: values.check,
+        includeRestricted: values["include-restricted"],
+      };
+      const checked = listUsageProblem(options, io);
+      if ("problem" in checked) return usage(checked.problem);
+      if (options.from !== undefined) {
+        const tree = (["root", "carrier", "level"] as const).find((name) => values[name] !== undefined);
+        if (tree !== undefined)
+          return usage(`--${tree} reads the tree; --from reads the records from the export alone`);
+        return listFromExportCommand(checked, { ...options, from: options.from }, io);
+      }
+      const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
+      return typeof session === "number" ? session : listCommand(session, checked, options, io);
+    }
     case "context": {
       const session = openSession(command, sessionOptions(levelGiven ?? "L1"), io);
       if (typeof session === "number") return session;
@@ -567,6 +633,19 @@ function parse(argv: string[]) {
       host: { type: "string" },
       to: { type: "string" },
       "allow-dirty": { type: "boolean", default: false },
+      id: { type: "string", multiple: true },
+      type: { type: "string", multiple: true },
+      status: { type: "string", multiple: true },
+      delivery: { type: "string", multiple: true },
+      owner: { type: "string", multiple: true },
+      under: { type: "string", multiple: true },
+      "not-release": { type: "string", multiple: true },
+      has: { type: "string", multiple: true },
+      "has-extension": { type: "string", multiple: true },
+      describing: { type: "string", multiple: true },
+      claims: { type: "string", multiple: true },
+      where: { type: "string" },
+      "count-by": { type: "string" },
     },
   });
 }

package/src/session.ts

@@ -48,11 +48,10 @@ import {
 import { insideRoot } from "./outputs.ts";
 import { formatDiagnostic, type Io, type Snapshot } from "./output.ts";
 import { type CarrierName, CONFIG_PATH, findRoot, loadRepository, type Repository } from "./repository.ts";
-import { bindingFor, subjectsOf } from "./subject.ts";
+import { bindingFor, EVIDENCE_DIR, subjectsOf } from "./subject.ts";
 import { readTree, type Tree } from "./tree.ts";
 
-/** Where run records are read from when no --evidence is given. Local output: not to be committed. */
-export const EVIDENCE_DIR = ".intentset/evidence";
+export { EVIDENCE_DIR } from "./subject.ts";
 
 export interface SessionOptions {
   root?: string;