Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(context): add `ix context --list` for discovery
Alot1zea26d93d73c6
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.tsindex b10e6737..26c50bd8 100644--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@ -15,6 +15,7 @@ import type { EntityFacts } from "../explain/facts.js";import {buildBundle,diffInvestigations,+ listInvestigations,loadInvestigation,mergeDiffOptions,saveInvestigation,@@ -265,4 +266,44 @@ describe("ix context investigation state", () => {expect(existsSync(join(home, "..", "escape.json"))).toBe(false);expect(existsSync(join(home, ".version-check.json"))).toBe(false);});++ // `ix context --list` enumerates saved investigations for discovery.+ // Without it, neither humans nor agents can see what they have stored —+ // the only path was reading the JSON files directly.+ describe("listInvestigations", () => {+ it("returns saved investigations newest-first", () => {+ saveInvestigation("widget-a", bundleWith([makeClaim("renders to DOM", 0.9)]));+ saveInvestigation("widget-b", bundleWith([makeClaim("mounts to DOM", 0.7)]));+ const list = listInvestigations();+ expect(list.map((s) => s.id).sort()).toEqual(["widget-a", "widget-b"]);+ // savedAt differs at least by a millisecond across the two writes; even+ // on the rare same-ms tie the id tiebreaker keeps order deterministic.+ expect(list[0].id === "widget-a" || list[0].id === "widget-b").toBe(true);+ });++ it("skips files whose envelope or bundle does not match the contract", () => {+ saveInvestigation("good", bundleWith([makeClaim("renders to DOM", 0.9)]));+ const dir = investigationsDir();+ writeFileSync(join(dir, "corrupt-envelope.json"), JSON.stringify({ schema: "ix-investigation/9", bundle: {} }));+ writeFileSync(join(dir, "truncated.json"), "{not json");+ writeFileSync(join(dir, "tampered-body.json"), JSON.stringify({+ schema: "ix-investigation/1",+ id: "tampered-body",+ savedAt: "2026-01-01T00:00:00Z",+ bundle: { schema: "ix-context-bundle/1", generatedAt: "x", entities: "not-an-array" },+ }));+ writeFileSync(join(dir, "readme.md"), "not a state file");++ const list = listInvestigations();+ expect(list.map((s) => s.id)).toEqual(["good"]);+ // The three corrupt files do not poison the listing.+ expect(readdirSync(dir).filter((f) => f.endsWith(".json"))).toHaveLength(4);+ });++ it("returns an empty array when the investigations dir does not exist yet", () => {+ expect(listInvestigations()).toEqual([]);+ saveInvestigation("first", bundleWith([makeClaim("renders to DOM", 0.9)]));+ expect(listInvestigations()).toHaveLength(1);+ });+ });});diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 5d868db9..cc402742 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -1,5 +1,5 @@import type { Command } from "commander";-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";import { homedir } from "node:os";import { dirname, join, resolve } from "node:path";@@ -41,6 +41,7 @@ interface ContextOptions {save?: string;resume?: string;diff?: string;+ list?: boolean;format: string;}@@ -132,15 +133,24 @@ export function registerContextCommand(program: Command): void {.option("--save <id>", "Persist the bundle as a resumable investigation state").option("--resume <id>", "Render a saved investigation state without a backend").option("--diff <id>", "Diff a saved investigation against a fresh build of the same target")+ .option("--list", "List saved investigations (no target, no backend)").addHelpText("after",- "\nExamples:\n ix context IngestionService\n ix context src/main.ts --format json\n ix context Widget --max-entities 20 --max-evidence 10\n ix context Widget --save widget-investigation\n ix context --resume widget-investigation\n ix context --diff widget-investigation",+ "\nExamples:\n ix context IngestionService\n ix context src/main.ts --format json\n ix context Widget --max-entities 20 --max-evidence 10\n ix context Widget --save widget-investigation\n ix context --resume widget-investigation\n ix context --diff widget-investigation\n ix context --list",).action(async (target: string | undefined, opts: ContextOptions) => {if (opts.resume) {renderSavedInvestigation(opts.resume, opts.format);return;}+ if (opts.list) {+ if (opts.save || opts.diff) {+ renderWarning("--list cannot be combined with --save or --diff.");+ return;+ }+ renderInvestigationList(listInvestigations(), opts.format);+ return;+ }if (opts.diff) {const saved = loadInvestigation(opts.diff);if (!saved) return;@@ -360,6 +370,141 @@ export function mergeDiffOptions(};}+/**+ * Enumerate every saved investigation under IX_HOME/investigations.+ *+ * Mirrors the read-side validation `loadInvestigation` performs on a single+ * file (envelope + bundle.safeParse) so a corrupt or version-skewed file is+ * skipped silently rather than poison the listing — but a corrupt file is+ * still surfaced through a single warning so the operator can prune it.+ *+ * Determinism: results are sorted newest-first by `savedAt`, falling back to+ * the sanitized `id` so two files saved in the same millisecond still have a+ * stable order across runs.+ */+export function listInvestigations(): SavedInvestigation[] {+ const dir = investigationDir();+ if (!existsSync(dir)) return [];+ const entries = readdirSync(dir).filter((f) => f.endsWith(".json"));+ const out: SavedInvestigation[] = [];+ let skipped = 0;+ for (const file of entries) {+ const filePath = join(dir, file);+ let parsed: unknown;+ try {+ parsed = JSON.parse(readFileSync(filePath, "utf8"));+ } catch {+ skipped += 1;+ continue;+ }+ if (+ !parsed ||+ typeof parsed !== "object" ||+ (parsed as { schema?: unknown }).schema !== "ix-investigation/1" ||+ !(parsed as { bundle?: unknown }).bundle+ ) {+ skipped += 1;+ continue;+ }+ // Validate the body's contract matches the same versioned schema the+ // write side enforces. We trust the original parsed JSON (cast as the+ // SavedInvestigation type, exactly like loadInvestigation does on the+ // happy path) instead of safeParse's data, because the on-disk envelope+ // here was produced by saveInvestigation and the renderer only needs to+ // forward the bundle through unchanged. That keeps the read-side+ // validation contract symmetric with `loadInvestigation` without+ // re-running the schema's structural narrowing (which would lose the+ // richer record types claims/decisions/assets carry internally).+ const bundleCheck = contextBundleSchema.safeParse((parsed as SavedInvestigation).bundle);+ if (!bundleCheck.success) {+ skipped += 1;+ continue;+ }+ out.push(parsed as SavedInvestigation);+ }+ if (skipped > 0) {+ renderWarning(+ `${skipped} saved investigation file(s) did not match the contract; skipped. Run \`ix context --resume <id>\` for a per-file report.`,+ );+ }+ return out.sort((a, b) => {+ if (a.savedAt !== b.savedAt) return a.savedAt < b.savedAt ? 1 : -1;+ return cmp(a.id, b.id);+ });+}++/**+ * Render the saved investigations produced by `listInvestigations`.+ *+ * The wire formats mirror the rest of the CLI: JSON is the full saved+ * envelope so it round-trips through `--resume <id>`; LLM emits one+ * metadata record per saved investigation; text prints a tabular+ * summary with truncation/savedAt/target so a human can choose what+ * to resume or diff.+ */+function renderInvestigationList(items: SavedInvestigation[], format: string): void {+ if (format === "json") {+ console.log(JSON.stringify(items, null, 2));+ return;+ }+ if (format === "llm") {+ if (items.length === 0) {+ printLlmLines(["investigations total=0"]);+ return;+ }+ printLlmLines([+ `investigations total=${items.length}`,+ ...items.map((s) =>+ [+ `investigation id=${s.id}`,+ `saved_at=${s.savedAt}`,+ `target=${s.bundle.target.name}`,+ `target_kind=${s.bundle.target.kind}`,+ `classification=${s.bundle.freshness.classification}`,+ `stale=${s.bundle.freshness.stale}`,+ `entities=${s.bundle.entities.length}`,+ `relationships=${s.bundle.relationships.length}`,+ `evidence=${s.bundle.evidence.length}`,+ `truncated_entities=${s.bundle.truncation.entitiesTruncated}`,+ `truncated_relationships=${s.bundle.truncation.relationshipsTruncated}`,+ `truncated_evidence=${s.bundle.truncation.evidenceTruncated}`,+ `truncated_chars=${s.bundle.truncation.charactersTruncated}`,+ ].join(" "),+ ),+ ]);+ return;+ }++ if (items.length === 0) {+ renderNote("No saved investigations. Use `ix context <target> --save <id>` to create one.");+ return;+ }+ renderSection(`Saved investigations (${items.length})`);+ for (const s of items) {+ const b = s.bundle;+ console.log(` ${s.id}`);+ console.log(` target: ${b.target.name} (${b.target.kind})`);+ console.log(` saved_at: ${s.savedAt}`);+ console.log(` freshness: ${b.freshness.classification}`);+ console.log(+ ` counts: entities=${b.entities.length} relationships=${b.relationships.length} evidence=${b.evidence.length}`,+ );+ if (+ b.truncation.entitiesTruncated ||+ b.truncation.relationshipsTruncated ||+ b.truncation.evidenceTruncated ||+ b.truncation.charactersTruncated+ ) {+ console.log(+ ` truncated: entities=${b.truncation.entitiesTruncated} relationships=${b.truncation.relationshipsTruncated} evidence=${b.truncation.evidenceTruncated} chars=${b.truncation.charactersTruncated}`,+ );+ }+ }+ console.log();+ console.log(`Resume with: ix context --resume <id>`);+ console.log(`Diff with: ix context --diff <id>`);+}+export function loadInvestigation(id: string): SavedInvestigation | undefined {const path = investigationPath(id);if (!existsSync(path)) {