Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.md
index 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 exists
because the header used to carry a single `total` field holding the length of
the *cut* list — so `ix callers` on a symbol with 212 callers reported
diff --git a/ix-cli/src/cli/__tests__/edge-server-cap.test.ts b/ix-cli/src/cli/__tests__/edge-server-cap.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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();