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
fix(cli): print next: only for commands that page, and phrase it for MCP (HR-02A)
KageBinary34dd30911dd4
diff --git a/docs/llm-format.md b/docs/llm-format.mdindex 3c75d5c5..71ee2a00 100644--- a/docs/llm-format.md+++ b/docs/llm-format.md@@ -122,9 +122,13 @@ record: `shown` is what follows, `total` is what there was before the cut.```callers target=verify_token shown=50 total=212 resolved=48 unresolved=2-diagnostic code=results_truncated message="212 callers; showing 50. Raise --limit to see the rest."+diagnostic code=results_truncated next_offset=50 message="212 callers; showing 50. next: ix callers --offset 50 verify_token"```+The `next:` text is for whoever reads it: over MCP it is the tool's own+input (`next: offset=50`), not a CLI command. A command with no `--offset`+never prints `next:`; its message says `Raise --limit to see them.`+`shown < total` is the only signal that a list is partial, and it existsbecause the header used to carry a single `total` field holding the length ofthe *cut* list — so `ix callers` on a symbol with 212 callers reporteddiff --git a/ix-cli/src/cli/__tests__/edge-server-cap.test.ts b/ix-cli/src/cli/__tests__/edge-server-cap.test.tsindex efc31a57..5b6ede6e 100644--- a/ix-cli/src/cli/__tests__/edge-server-cap.test.ts+++ b/ix-cli/src/cli/__tests__/edge-server-cap.test.ts@@ -69,9 +69,9 @@ describe("edge paging at the server cap", () => {});it("a page inside the cap still points at the next page, with the count as a floor", () => {- const s = sliceEdgeResults(full(), 50, 0, true);+ const s = { ...sliceEdgeResults(full(), 50, 0, true), next: "ix callers t --offset 50" };expect(s.nextOffset).toBe(50);- expect(truncationHint(s, "callers")).toBe("At least 1000 callers (the server returns at most 1000 edges); showing 50. next: --offset 50");+ expect(truncationHint(s, "callers")).toBe("At least 1000 callers (the server returns at most 1000 edges); showing 50. next: ix callers t --offset 50");});it("leaves an uncapped list alone", () => {diff --git a/ix-cli/src/cli/__tests__/honest-truncation.test.ts b/ix-cli/src/cli/__tests__/honest-truncation.test.tsindex fb84af0f..07a47b94 100644--- a/ix-cli/src/cli/__tests__/honest-truncation.test.ts+++ b/ix-cli/src/cli/__tests__/honest-truncation.test.ts@@ -3,8 +3,9 @@import { Command } from "commander";import { describe, expect, it } from "vitest";-import { renderEdgeResultsLlm, sliceEdgeResults, sliceRanked } from "../format.js";-import { nextPageCommand } from "../paging.js";+import { renderEdgeResultsLlm, sliceEdgeResults, sliceRanked, truncationHint } from "../format.js";+import { IX_CALLER_ENV } from "../next-step.js";+import { nextPageCommand, shellQuote } from "../paging.js";import { renderInventoryLlm } from "../commands/inventory.js";import { scanWindow, textResultPriority } from "../commands/text.js";@@ -59,13 +60,24 @@ describe("sliceEdgeResults", () => {expect(header).toBe("callers target=verify_token shown=1 total=2 resolved=1");});- it("names the flag that would show the rest", () => {+ it("names the next page when the command set one", () => {const all = Array.from({ length: 212 }, (_, i) => node(`c${i}`, "src/a.ts"));- const lines = renderEdgeResultsLlm(sliceEdgeResults(all, 50), "callers", "verify_token", "graph");+ const s = { ...sliceEdgeResults(all, 50), next: "ix callers verify_token --offset 50" };+ const lines = renderEdgeResultsLlm(s, "callers", "verify_token", "graph");expect(lines[1]).toBe(- 'diagnostic code=results_truncated next_offset=50 message="212 callers; showing 50. next: --offset 50"',+ 'diagnostic code=results_truncated next_offset=50 message="212 callers; showing 50. next: ix callers verify_token --offset 50"',);});++ it("never points at --offset when the command did not opt into paging", () => {+ // `ix impact` slices its leaf rows with sliceEdgeResults but has no --offset.+ const all = Array.from({ length: 25 }, (_, i) => node(`c${i}`, "src/a.ts"));+ const s = sliceEdgeResults(all, 10);+ expect(s.nextOffset).toBe(10);+ expect(truncationHint(s, "callers")).toBe("25 callers; showing 10. Raise --limit to see them.");+ const capped = sliceEdgeResults(Array.from({ length: 1000 }, (_, i) => node(`c${i}`, "src/a.ts")), 10, 0, true);+ expect(truncationHint(capped, "callers")).not.toContain("--offset");+ });});describe("paging with --offset", () => {@@ -96,7 +108,9 @@ describe("paging with --offset", () => {const lines = renderEdgeResultsLlm(s, "callers", "t", "graph");expect(lines[0]).toBe("callers target=t offset=50 shown=50 total=212 resolved=50");expect(lines[1]).toContain("next_offset=100");- expect(lines[1]).toContain("showing 51-100. next: --offset 100");+ expect(lines[1]).toContain("showing 51-100. Raise --limit");+ const paged = renderEdgeResultsLlm({ ...s, next: "ix callers t --offset 100" }, "callers", "t", "graph");+ expect(paged[1]).toContain("showing 51-100. next: ix callers t --offset 100");});it("uses the caller's next command when given", () => {@@ -165,6 +179,34 @@ describe("nextPageCommand", () => {expect(nextPageCommand(cmd, ["a b"], 50)).toBe("ix callers --offset 50 'a b'");expect(nextPageCommand(cmd, ["-x"], 50)).toBe("ix callers --offset 50 -- -x");});++ it("over MCP names the tool's offset input, not a CLI command", () => {+ const cmd = parsed(["--kind", "method", "x"]);+ const prev = process.env[IX_CALLER_ENV];+ process.env[IX_CALLER_ENV] = "mcp";+ try {+ expect(nextPageCommand(cmd, ["x"], 50)).toBe("offset=50");+ } finally {+ if (prev === undefined) delete process.env[IX_CALLER_ENV];+ else process.env[IX_CALLER_ENV] = prev;+ }+ });+});++describe("shellQuote", () => {+ it("uses POSIX quoting off Windows", () => {+ expect(shellQuote("it's", "linux")).toBe(`'it'\\''s'`);+ });++ it("doubles an embedded quote on Windows (PowerShell)", () => {+ expect(shellQuote("it's", "win32")).toBe("'it''s'");+ expect(shellQuote("a b", "win32")).toBe("'a b'");+ });++ it("leaves a safe word bare on every platform", () => {+ expect(shellQuote("src/a.ts", "win32")).toBe("src/a.ts");+ expect(shellQuote("src/a.ts", "darwin")).toBe("src/a.ts");+ });});describe("renderInventoryLlm", () => {diff --git a/ix-cli/src/cli/commands/callers.ts b/ix-cli/src/cli/commands/callers.tsindex 330345c3..377d8da6 100644--- a/ix-cli/src/cli/commands/callers.ts+++ b/ix-cli/src/cli/commands/callers.ts@@ -19,14 +19,14 @@ import { currentRunSignal } from "../../client/run-signal.js";const execFileAsync = promisify(execFile);+/** Rows per page of the text fallback. --limit does not apply to it. */+export const TEXT_FALLBACK_PAGE = 10;+/*** rg's argv for the text fallback. -F and -e: the name is a literal pattern,* never a regex or a flag (a symbol named `--pre=x` would otherwise run an rg* preprocessor). `--` ends the options before the root.*/-/** Rows per page of the text fallback. --limit does not apply to it. */-export const TEXT_FALLBACK_PAGE = 10;-export function callersTextSearchArgs(name: string, root: string): string[] {return ["--json", "--max-count", "10", "-F", "-e", name, "--", root];}diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.tsindex 879dc885..d8b6912b 100644--- a/ix-cli/src/cli/format.ts+++ b/ix-cli/src/cli/format.ts@@ -198,14 +198,21 @@ export function expandCapped(result: { nodes?: unknown[]; edges?: unknown[]; tru|| (result.nodes?.length ?? 0) >= EXPAND_MAX_EDGES;}-/** What was left out, and the one flag that gets it. */+/**+ * What was left out, and the one flag that gets it.+ *+ * `next:` is printed only when the caller set `slice.next`: that is how a+ * command says it takes `--offset`. `sliceRanked` sets `nextOffset` on every+ * truncated slice, including slices cut by commands with no `--offset` (`ix+ * impact`'s leaf rows), and pointing those at a flag they reject would send the+ * reader into an unknown-option error.+ */export function truncationHint(slice: Slice<unknown>, relation: string): string {const offset = slice.offset ?? 0;if (slice.capped) return cappedHint(slice, relation);const range = offset > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;- if (slice.nextOffset === undefined) return `${slice.total} ${relation}; showing ${range}. Raise --limit to see them.`;- const next = slice.next ?? `--offset ${slice.nextOffset}`;- return `${slice.total} ${relation}; showing ${range}. next: ${next}`;+ if (slice.nextOffset === undefined || slice.next === undefined) return `${slice.total} ${relation}; showing ${range}. Raise --limit to see them.`;+ return `${slice.total} ${relation}; showing ${range}. next: ${slice.next}`;}/**@@ -217,7 +224,8 @@ function cappedHint(slice: Slice<unknown>, relation: string): string {const head = `At least ${slice.total} ${relation} (the server returns at most ${EXPAND_MAX_EDGES} edges)`;if (slice.nextOffset !== undefined) {const range = offset > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;- return `${head}; showing ${range}. next: ${slice.next ?? `--offset ${slice.nextOffset}`}`;+ if (slice.next !== undefined) return `${head}; showing ${range}. next: ${slice.next}`;+ return `${head}; showing ${range}. Raise --limit, or narrow the target with --kind or --path, to see the rest.`;}const where = slice.shown > 0? `showing ${offset > 0 ? `${offset + 1}-${offset + slice.shown}` : slice.shown}, the end of what it returned`diff --git a/ix-cli/src/cli/paging.ts b/ix-cli/src/cli/paging.tsindex 2785aa1b..5f322ba1 100644--- a/ix-cli/src/cli/paging.ts+++ b/ix-cli/src/cli/paging.ts@@ -1,6 +1,7 @@// Copyright 2026 Ix Infrastructure Inc.import type { Command } from "commander";+import { forMcp } from "./next-step.js";/** Help text for `--offset`, shared so the flag reads the same on every command. */export const OFFSET_FLAG = "Skip the first N results (use the next: hint to page)";@@ -16,16 +17,28 @@ export function parseOffset(raw?: string): number {const SAFE_WORD = /^[A-Za-z0-9_./:@%+=,-]+$/;-function shellQuote(word: string): string {+/**+ * Quote one word for the reader's shell. POSIX shells take `'...'` with `'\''`+ * for an embedded quote. On Windows the hint is most likely pasted into+ * PowerShell, where a single-quoted string doubles an embedded quote (`''`);+ * cmd.exe has no single-quote form at all, so a word with spaces or quotes may+ * still need hand-editing there.+ */+export function shellQuote(word: string, platform: NodeJS.Platform = process.platform): string {if (SAFE_WORD.test(word)) return word;+ if (platform === "win32") return `'${word.replace(/'/g, "''")}'`;return `'${word.replace(/'/g, `'\\''`)}'`;}/**- * The command line that prints the next page: the same command, the same- * positionals, the options the caller typed, and `--offset nextOffset`.+ * The next page, phrased for whoever reads it. At a shell that is the command+ * line that prints it: the same command, the same positionals, the options the+ * caller typed, and `--offset nextOffset`. Over MCP there is no shell and no+ * `--offset` flag; the tool that printed the page takes an `offset` input, so+ * the hint is that input (`offset=50`).*/export function nextPageCommand(cmd: Command, positionals: string[], nextOffset: number): string {+ if (forMcp()) return `offset=${nextOffset}`;const parts = ["ix", cmd.name()];for (const option of cmd.options) {const name = option.attributeName();