@rockhopper-co/mcp-server 0.7.0 → 0.10.0

package/dist/cli.js

@@ -2,8 +2,25 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ApiClient } from './api-client.js';
 import { AuthResolutionError, resolveAuth, } from './auth/resolve-auth.js';
+import { flushLoggerSync, initLogger, log, serviceVersion, } from './logger.js';
 import { createServer } from './server.js';
 const ROCKHOPPER_API_URL = process.env.ROCKHOPPER_API_URL || 'https://api.rockhopper.co';
+// KI-225: start the local rotating diagnostic logfile before anything else,
+// so startup-path failures (auth, preflight, crashes) are captured. Never
+// throws and never writes to stdout — falls back to a no-op logger.
+await initLogger();
+// Capture client-side crashes that would otherwise vanish (the backend can't
+// see them). Registering these handlers suppresses Node's default crash, so
+// uncaughtException re-exits 1 to PRESERVE the existing exit behavior; the
+// fatal line is flushed to disk synchronously first.
+process.on('uncaughtException', (err) => {
+    log.fatal({ event: 'uncaught_exception', err }, 'uncaught_exception');
+    flushLoggerSync();
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    log.error({ event: 'unhandled_rejection', err: reason }, 'unhandled_rejection');
+});
 // ENG-1444: auth resolution order is
 //   1. ROCKHOPPER_TOKEN env var (Personal Access Token — headless / CI)
 //   2. Stored OAuth bundle in the OS keychain (prior device-grant flow)
@@ -17,6 +34,8 @@ try {
 }
 catch (err) {
     if (err instanceof AuthResolutionError) {
+        // KI-225: local auth failure before any API call (bad token / sign-in).
+        log.warn({ event: 'auth_failed', reason: err.code }, 'auth_failed');
         if (err.code === 'pat_malformed') {
             console.error(`Error: ${err.message}`);
             console.error('Tokens start with "rh_pat_". Check that the full token was copied correctly.');
@@ -34,16 +53,33 @@ catch (err) {
     }
     process.exit(1);
 }
+// Every catch branch above ends in `process.exit(1)`, so `resolved` is always
+// assigned past this point. TS 6.0's stricter control-flow analysis can't prove
+// that across the implicit-typed `let`, so narrow it explicitly here.
+if (!resolved) {
+    process.exit(1);
+}
 const apiClient = new ApiClient({
     baseUrl: ROCKHOPPER_API_URL,
     token: resolved.accessToken,
 });
 try {
-    await apiClient.getMe();
+    const me = await apiClient.getMe();
+    // ENG-1756 (plan §9 decision 15): the PAT owner IS the human driving this
+    // local agent — reuse the preflight to declare them, so every write carries
+    // `X-Driving-Human` and the backend's anonymous-agent-write admission
+    // never fires for this client. Best-effort: while unset, the backend
+    // resolves the PAT owner server-side (same human).
+    apiClient.setDrivingHuman(me?.msId ?? me?.googleId ?? null);
 }
 catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes('401') || msg.includes('403')) {
+        // KI-225: preflight token rejection — the local auth-fail signal.
+        log.warn({
+            event: 'auth_failed',
+            reason: resolved.source === 'pat' ? 'pat_invalid' : 'oauth_invalid',
+        }, 'auth_failed');
         if (resolved.source === 'pat') {
             console.error('Error: ROCKHOPPER_TOKEN is invalid or expired.\n' +
                 'Create a new Personal Access Token in Rockhopper Settings and set it as ROCKHOPPER_TOKEN.');
@@ -60,6 +96,8 @@ catch (err) {
     process.exit(1);
 }
 const server = createServer(apiClient);
+// KI-225: one line per launch — anchors a session in the file.
+log.info({ event: 'mcp_server_start', version: serviceVersion }, 'mcp_server_start');
 const transport = new StdioServerTransport();
 await server.connect(transport);
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/correlation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Runs `fn` inside an AsyncLocalStorage scope carrying `id`. Reads via
+ * {@link getCorrelationId} anywhere in the (sync or async) continuation
+ * return the same id. Mints a fresh UUID v4 when `id` is omitted.
+ */
+export declare const runWithCorrelationId: <T>(fn: () => T, id?: string) => T;
+/** Current correlation id, or `undefined` when called outside a scope. */
+export declare const getCorrelationId: () => string | undefined;
+//# sourceMappingURL=correlation.d.ts.map

package/dist/correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,EACpC,IAAI,MAAM,CAAC,EACX,KAAI,MAAqB,KACxB,CAAoB,CAAC;AAExB,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,QAAO,MAAM,GAAG,SAA2B,CAAC"}

package/dist/correlation.js

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+/**
+ * Phase 1.1 / KI-226 — correlation id propagation.
+ *
+ * Per-tool-call scope: a single correlation id covers every outbound
+ * Rockhopper API call a tool invocation makes (including multi-call
+ * fan-outs like search). The id rides the `X-Correlation-Id` header out of
+ * {@link ApiClient.request}, so an mcp-server-originated request is
+ * traceable as a group in backend logs.
+ *
+ * The id is a non-sensitive UUID v4 — never co-log the bearer token with it.
+ * `randomUUID` comes from `node:crypto` (NOT the global `crypto`) because the
+ * package supports Node 18, where global `crypto.randomUUID` is not
+ * guaranteed.
+ */
+const als = new AsyncLocalStorage();
+/**
+ * Runs `fn` inside an AsyncLocalStorage scope carrying `id`. Reads via
+ * {@link getCorrelationId} anywhere in the (sync or async) continuation
+ * return the same id. Mints a fresh UUID v4 when `id` is omitted.
+ */
+export const runWithCorrelationId = (fn, id = randomUUID()) => als.run(id, fn);
+/** Current correlation id, or `undefined` when called outside a scope. */
+export const getCorrelationId = () => als.getStore();
+//# sourceMappingURL=correlation.js.map

package/dist/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;GAaG;AACH,MAAM,GAAG,GAAG,IAAI,iBAAiB,EAAU,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,EAAW,EACX,KAAa,UAAU,EAAE,EACtB,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AAExB,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAuB,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,42 @@
+import pino from 'pino';
+import pinoRoll from 'pino-roll';
+/** The 5 log methods we expose. A real `pino.Logger` satisfies this. */
+export interface DiagnosticLogger {
+    debug: pino.LogFn;
+    info: pino.LogFn;
+    warn: pino.LogFn;
+    error: pino.LogFn;
+    fatal: pino.LogFn;
+}
+export declare const serviceVersion: string;
+/**
+ * Builds a file-only diagnostic logger. NEVER throws and NEVER writes to
+ * stdout — on opt-out or any failure it returns a no-op logger. Exposed
+ * (vs. only the {@link log} singleton) so tests can drive an isolated
+ * instance pointed at a tmpdir.
+ */
+export declare function createDiagnosticLogger(opts?: {
+    dir?: string;
+    disable?: boolean;
+    level?: string;
+}): Promise<{
+    logger: DiagnosticLogger;
+    flush: () => Promise<void>;
+    destination?: Awaited<ReturnType<typeof pinoRoll>>;
+}>;
+/**
+ * Process-wide singleton. Starts as a no-op (so importing this module —
+ * including from the library entry / mcp-gateway — has no side effect and
+ * opens no file) and is swapped to the real file logger by
+ * {@link initLogger}, which the stdio CLI calls at startup.
+ */
+export declare let log: DiagnosticLogger;
+/** Idempotently constructs the singleton from env config. Never rejects. */
+export declare function initLogger(): Promise<void>;
+/**
+ * Best-effort synchronous flush — for the crash path, where the last
+ * `fatal` line must hit disk before {@link process.exit}. No-op when the
+ * logger is disabled / not yet ready.
+ */
+export declare function flushLoggerSync(): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AA2BA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,QAAQ,MAAM,WAAW,CAAC;AAGjC,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC;IAClB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IACjB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC;IAClB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC;CACnB;AA0BD,eAAO,MAAM,cAAc,QAAkB,CAAC;AAuB9C;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7D,OAAO,CAAC;IACT,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC;CACpD,CAAC,CAmDD;AAED;;;;;GAKG;AACH,eAAO,IAAI,GAAG,EAAE,gBAA6B,CAAC;AAK9C,4EAA4E;AAC5E,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAQhD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAMtC"}

package/dist/logger.js

@@ -0,0 +1,159 @@
+/**
+ * Phase 1.5 / KI-225 — local, rotating diagnostic logfile.
+ *
+ * Why this exists: the backend already logs everything that *reaches* the
+ * API. The unique value of a client-side log is the failures that NEVER
+ * reach the backend (network-unreachable, local auth rejection, schema
+ * drift, uncaught crashes) plus a local request-latency view. The file is
+ * the customer's to keep and hand to support — there is NO remote
+ * transmission.
+ *
+ * 🚨 HARD CONSTRAINT — stdout is the MCP stdio transport. Logs MUST go to
+ * the FILE ONLY, never stdout. We therefore:
+ *   - build pino against a {@link pino-roll} Sonic-boom file destination
+ *     (NOT pino's default stdout destination, NOT a worker transport), and
+ *   - fall back to a NO-OP logger on ANY construction failure — never
+ *     crash the server, never write to stdout.
+ *
+ * Redaction (SOC2-adjacent, runs on customer machines): callers must only
+ * ever pass safe fields — event, method, URL pathname (no query/token),
+ * status, durationMs, tool name, correlationId, version, error
+ * type/message. Never tokens, Authorization headers, request/response
+ * bodies, tool arguments, file contents, or cell data.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import pino from 'pino';
+import pinoRoll from 'pino-roll';
+import { getCorrelationId } from './correlation.js';
+const SERVICE_NAME = 'mcp-server';
+const LOG_FILE_BASENAME = 'mcp-server.log';
+const LOG_MAX_SIZE = '5m';
+const LOG_FILE_COUNT = 5;
+const DEFAULT_LOG_DIR = path.join(os.homedir(), '.rockhopper', 'mcp-server');
+const VALID_LEVELS = new Set([
+    'fatal',
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'trace',
+    'silent',
+]);
+/** Package version stamped into every line's `base`. Best-effort read. */
+const requireJson = createRequire(import.meta.url);
+let resolvedVersion = '0.0.0';
+try {
+    const pkg = requireJson('../package.json');
+    if (pkg.version)
+        resolvedVersion = pkg.version;
+}
+catch {
+    // package.json unreadable — keep the sentinel; never crash over a version.
+}
+export const serviceVersion = resolvedVersion;
+/** Shared no-op so disabled/failed logging is a single cheap call site. */
+const noopFn = () => { };
+const noopLogger = {
+    debug: noopFn,
+    info: noopFn,
+    warn: noopFn,
+    error: noopFn,
+    fatal: noopFn,
+};
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+}
+function normalizeLevel(level) {
+    const v = level?.trim().toLowerCase();
+    return v && VALID_LEVELS.has(v) ? v : 'info';
+}
+/**
+ * Builds a file-only diagnostic logger. NEVER throws and NEVER writes to
+ * stdout — on opt-out or any failure it returns a no-op logger. Exposed
+ * (vs. only the {@link log} singleton) so tests can drive an isolated
+ * instance pointed at a tmpdir.
+ */
+export async function createDiagnosticLogger(opts = {}) {
+    const disable = opts.disable ?? isTruthyEnv(process.env.ROCKHOPPER_MCP_LOG_DISABLE);
+    if (disable) {
+        return { logger: noopLogger, flush: async () => { } };
+    }
+    try {
+        const envDir = process.env.ROCKHOPPER_MCP_LOG_DIR?.trim();
+        const dir = opts.dir ?? (envDir && envDir.length ? envDir : DEFAULT_LOG_DIR);
+        fs.mkdirSync(dir, { recursive: true });
+        const destination = await pinoRoll({
+            file: path.join(dir, LOG_FILE_BASENAME),
+            size: LOG_MAX_SIZE,
+            limit: { count: LOG_FILE_COUNT },
+            mkdir: true,
+        });
+        // A logging IO error must never crash the server (or escape as an
+        // unhandled 'error' event). Swallow it — diagnostics are best-effort.
+        destination.on('error', () => { });
+        const logger = pino({
+            level: normalizeLevel(opts.level ?? process.env.ROCKHOPPER_MCP_LOG_LEVEL),
+            base: { service: SERVICE_NAME, version: serviceVersion },
+            serializers: { err: pino.stdSerializers.err },
+            // Every line auto-carries the per-tool-call correlationId (Phase 1.1
+            // ALS scope) when one is active — no call site has to thread it.
+            mixin() {
+                const id = getCorrelationId();
+                return id ? { correlationId: id } : {};
+            },
+        }, destination);
+        const flush = () => new Promise((resolve) => {
+            try {
+                destination.flush(() => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+        return { logger, flush, destination };
+    }
+    catch {
+        // fs / pino-roll / pino failure — degrade to no-op, never to stdout.
+        return { logger: noopLogger, flush: async () => { } };
+    }
+}
+/**
+ * Process-wide singleton. Starts as a no-op (so importing this module —
+ * including from the library entry / mcp-gateway — has no side effect and
+ * opens no file) and is swapped to the real file logger by
+ * {@link initLogger}, which the stdio CLI calls at startup.
+ */
+export let log = noopLogger;
+let activeDestination;
+let initPromise;
+/** Idempotently constructs the singleton from env config. Never rejects. */
+export async function initLogger() {
+    if (initPromise)
+        return initPromise;
+    initPromise = (async () => {
+        const built = await createDiagnosticLogger();
+        log = built.logger;
+        activeDestination = built.destination;
+    })();
+    return initPromise;
+}
+/**
+ * Best-effort synchronous flush — for the crash path, where the last
+ * `fatal` line must hit disk before {@link process.exit}. No-op when the
+ * logger is disabled / not yet ready.
+ */
+export function flushLoggerSync() {
+    try {
+        activeDestination?.flushSync();
+    }
+    catch {
+        // Stream not ready or already closed — nothing more we can do pre-exit.
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/not-ready.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Plan 02 ruling 5 (David, 2026-08-04) — STRICT no-partial, on the machine
+ * surfaces.
+ *
+ * The rule David landed is "nothing serves change history until it is
+ * complete", and he chose STRICT specifically because THIS server is a
+ * consumer: rows leave here for Claude Desktop / Cursor, which get no banner,
+ * no colour and no human in the loop, and will narrate whatever arrives as
+ * fact. An empty list is the dangerous answer — "there are no changes" is a
+ * factual claim, and it is the claim an assistant makes when handed zero rows.
+ *
+ * So a not-ready answer here is a REFUSAL, not a value: `isError: true`, a
+ * shouting marker, an explicit "this is not an empty result", and a JSON
+ * object an assistant can branch on. A resource or prompt THROWS for the same
+ * reason a tool cannot return rows — a protocol error cannot be summarised as
+ * data.
+ *
+ * Vocabulary is deliberately the backend's, not a second one: the reasons
+ * mirror the SP02 `ParsedOutputNotReadyReason` family
+ * (`backend/src/common/parsed-output/parsed-output-not-ready.error.ts`), and
+ * `isNotReady` matches both the typed error and a wrapper carrying it as
+ * `cause`, exactly like the backend's `isParsedOutputNotReady`.
+ */
+/** Why a change-history answer is being refused. */
+export type NotReadyReason = 
+/** A commit-diff fold is still rewriting this file's change-log window. */
+'change_history_incomplete'
+/** The backend answered 429/503: parsed outputs are still being produced. */
+ | 'still_producing'
+/**
+ * The completeness probe itself could not answer. Fail CLOSED: under STRICT
+ * an unknown completeness state is not permission to serve rows. This is the
+ * one reason that is NOT a statement about the file.
+ */
+ | 'completeness_unknown';
+/** Grep marker; also the first token of every refusal an assistant sees. */
+export declare const NOT_READY_MARKER = "CHANGE_HISTORY_NOT_READY";
+/** Poll hint when the backend gave none — mirrors the backend's own default. */
+export declare const DEFAULT_RETRY_AFTER_SECONDS = 15;
+export declare class ChangeHistoryNotReadyError extends Error {
+    /** Structural marker, so a wrapper can be recognised without importing. */
+    readonly notReady: true;
+    readonly reason: NotReadyReason;
+    readonly retryAfterSeconds: number;
+    readonly fileMsId: string | null;
+    constructor(ctx: {
+        reason: NotReadyReason;
+        retryAfterSeconds?: number | null;
+        fileMsId?: string | null;
+        detail?: string;
+    });
+}
+/** Matches the typed error AND any error carrying one as `cause`. */
+export declare function isNotReady(err: unknown): err is ChangeHistoryNotReadyError;
+export interface NotReadyToolResult {
+    /** The SDK's `CallToolResult` carries an index signature; mirror it so this
+     * shape is assignable to a tool handler's return type. */
+    [key: string]: unknown;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: true;
+}
+/**
+ * The tool answer for a refusal. Three defences, because one is not enough
+ * against a model that wants to be helpful: `isError`, prose that names the
+ * wrong inference explicitly, and a JSON object to branch on.
+ */
+export declare function notReadyToolResult(err: unknown): NotReadyToolResult;
+/** The completeness probe this module needs from the API client. */
+export interface CompletenessProbe {
+    getFoldStatus(fileMsId: string): Promise<{
+        foldPending: boolean;
+        foldTargetVersionId: number | null;
+    }>;
+}
+/**
+ * Throws {@link ChangeHistoryNotReadyError} unless the file's change history is
+ * complete.
+ *
+ * `foldPending` is the backend's own authoritative queue read
+ * (`GET /file-versions/file/:fileMsId/fold-status`, KI-1399) — while it is
+ * true a commit-diff fold is queued, retrying or running, and the change-log
+ * window is mid-rewrite. That is precisely the incomplete state, and after
+ * plan 02's write-path decoupling (David Q3, 2026-08-03: save the version row
+ * first, defer the fold) it is the NORMAL state immediately after any write.
+ *
+ * A probe that cannot answer refuses. The backend's own probe fails OPEN to
+ * not-pending on purpose — a UI lock that can hang is worse than a stale row —
+ * but that trade does not transfer here: for a machine consumer a wrong
+ * "complete" is a fabricated fact, so the client-side default is the opposite.
+ */
+export declare function assertChangeHistoryComplete(api: CompletenessProbe, fileMsId: string): Promise<void>;
+//# sourceMappingURL=not-ready.d.ts.map

package/dist/not-ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-ready.d.ts","sourceRoot":"","sources":["../src/not-ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oDAAoD;AACpD,MAAM,MAAM,cAAc;AACxB,2EAA2E;AACzE,2BAA2B;AAC7B,6EAA6E;GAC3E,iBAAiB;AACnB;;;;GAIG;GACD,sBAAsB,CAAC;AAE3B,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAE3D,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAG,IAAI,CAAU;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;gBAErB,GAAG,EAAE;QACf,MAAM,EAAE,cAAc,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAClC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CAeF;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,0BAA0B,CAI1E;AAyBD,MAAM,WAAW,kBAAkB;IACjC;8DAC0D;IAC1D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAwBnE;AAED,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,WAAW,EAAE,OAAO,CAAC;QACrB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;KACpC,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/not-ready.js

@@ -0,0 +1,151 @@
+/**
+ * Plan 02 ruling 5 (David, 2026-08-04) — STRICT no-partial, on the machine
+ * surfaces.
+ *
+ * The rule David landed is "nothing serves change history until it is
+ * complete", and he chose STRICT specifically because THIS server is a
+ * consumer: rows leave here for Claude Desktop / Cursor, which get no banner,
+ * no colour and no human in the loop, and will narrate whatever arrives as
+ * fact. An empty list is the dangerous answer — "there are no changes" is a
+ * factual claim, and it is the claim an assistant makes when handed zero rows.
+ *
+ * So a not-ready answer here is a REFUSAL, not a value: `isError: true`, a
+ * shouting marker, an explicit "this is not an empty result", and a JSON
+ * object an assistant can branch on. A resource or prompt THROWS for the same
+ * reason a tool cannot return rows — a protocol error cannot be summarised as
+ * data.
+ *
+ * Vocabulary is deliberately the backend's, not a second one: the reasons
+ * mirror the SP02 `ParsedOutputNotReadyReason` family
+ * (`backend/src/common/parsed-output/parsed-output-not-ready.error.ts`), and
+ * `isNotReady` matches both the typed error and a wrapper carrying it as
+ * `cause`, exactly like the backend's `isParsedOutputNotReady`.
+ */
+/** Grep marker; also the first token of every refusal an assistant sees. */
+export const NOT_READY_MARKER = 'CHANGE_HISTORY_NOT_READY';
+/** Poll hint when the backend gave none — mirrors the backend's own default. */
+export const DEFAULT_RETRY_AFTER_SECONDS = 15;
+export class ChangeHistoryNotReadyError extends Error {
+    /** Structural marker, so a wrapper can be recognised without importing. */
+    notReady = true;
+    reason;
+    retryAfterSeconds;
+    fileMsId;
+    constructor(ctx) {
+        super(`${NOT_READY_MARKER}: reason=${ctx.reason} ` +
+            `retryAfterSeconds=${ctx.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS}` +
+            (ctx.detail ? ` — ${ctx.detail}` : '') +
+            ' — Rockhopper has not finished computing this change history. ' +
+            'This is NOT an empty result: no rows can be served yet, and nothing ' +
+            'may be inferred about whether the file changed.');
+        this.name = 'ChangeHistoryNotReadyError';
+        this.reason = ctx.reason;
+        this.retryAfterSeconds =
+            ctx.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS;
+        this.fileMsId = ctx.fileMsId ?? null;
+    }
+}
+/** Matches the typed error AND any error carrying one as `cause`. */
+export function isNotReady(err) {
+    if (err instanceof ChangeHistoryNotReadyError)
+        return true;
+    const cause = err?.cause;
+    return cause instanceof ChangeHistoryNotReadyError;
+}
+/**
+ * HTTP statuses that answer the question DEFINITIVELY. A permanently-refused
+ * request is not "still producing", and the two must not share an answer: a
+ * probe that 404s (no such file) or 403s (no access) has told us something
+ * true, and dressing it up as a capacity signal would send an assistant into a
+ * retry loop against a wall. Matched structurally (`err.status`) so this module
+ * stays free of an import cycle with the API client.
+ */
+const DEFINITIVE_HTTP_STATUSES = new Set([400, 401, 403, 404, 405, 410, 422]);
+function isDefinitiveRejection(err) {
+    const status = err?.status;
+    return typeof status === 'number' && DEFINITIVE_HTTP_STATUSES.has(status);
+}
+/** Unwrap to the typed error (accepts the `cause` shape). */
+function unwrap(err) {
+    if (err instanceof ChangeHistoryNotReadyError)
+        return err;
+    const cause = err.cause;
+    if (cause instanceof ChangeHistoryNotReadyError)
+        return cause;
+    return new ChangeHistoryNotReadyError({ reason: 'completeness_unknown' });
+}
+/**
+ * The tool answer for a refusal. Three defences, because one is not enough
+ * against a model that wants to be helpful: `isError`, prose that names the
+ * wrong inference explicitly, and a JSON object to branch on.
+ */
+export function notReadyToolResult(err) {
+    const e = unwrap(err);
+    const payload = {
+        status: 'not_ready',
+        reason: e.reason,
+        retryAfterSeconds: e.retryAfterSeconds,
+        fileMsId: e.fileMsId,
+    };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${NOT_READY_MARKER} — this is NOT a result and NOT an empty result.\n` +
+                    `Rockhopper has not finished computing this file's change history, ` +
+                    `so no rows can be served.\n` +
+                    `Do NOT say there are no changes, that nothing changed, or that the ` +
+                    `history is empty — none of that is known.\n` +
+                    `Retry in ${e.retryAfterSeconds} seconds.\n` +
+                    JSON.stringify(payload),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Throws {@link ChangeHistoryNotReadyError} unless the file's change history is
+ * complete.
+ *
+ * `foldPending` is the backend's own authoritative queue read
+ * (`GET /file-versions/file/:fileMsId/fold-status`, KI-1399) — while it is
+ * true a commit-diff fold is queued, retrying or running, and the change-log
+ * window is mid-rewrite. That is precisely the incomplete state, and after
+ * plan 02's write-path decoupling (David Q3, 2026-08-03: save the version row
+ * first, defer the fold) it is the NORMAL state immediately after any write.
+ *
+ * A probe that cannot answer refuses. The backend's own probe fails OPEN to
+ * not-pending on purpose — a UI lock that can hang is worse than a stale row —
+ * but that trade does not transfer here: for a machine consumer a wrong
+ * "complete" is a fabricated fact, so the client-side default is the opposite.
+ */
+export async function assertChangeHistoryComplete(api, fileMsId) {
+    let status;
+    try {
+        status = await api.getFoldStatus(fileMsId);
+    }
+    catch (err) {
+        if (isNotReady(err))
+            throw unwrap(err);
+        // A definitive rejection is the caller's real answer — let it through so
+        // the tool reports "not found" / "no access" instead of "retry in 15s".
+        if (isDefinitiveRejection(err))
+            throw err;
+        throw new ChangeHistoryNotReadyError({
+            reason: 'completeness_unknown',
+            fileMsId,
+            detail: `fold-status probe failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    if (status.foldPending) {
+        throw new ChangeHistoryNotReadyError({
+            reason: 'change_history_incomplete',
+            fileMsId,
+            detail: `a commit-diff fold is still pending` +
+                (status.foldTargetVersionId == null
+                    ? ''
+                    : ` for version ${status.foldTargetVersionId}`),
+        });
+    }
+}
+//# sourceMappingURL=not-ready.js.map

package/dist/not-ready.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-ready.js","sourceRoot":"","sources":["../src/not-ready.ts"],"names":[],"mappings":"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"}

package/dist/prompts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAuNvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAgOvE"}

package/dist/prompts/index.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { assertChangeHistoryComplete } from '../not-ready.js';
 export function registerPrompts(server, api) {
     server.registerPrompt('summarize-file-changes', {
         title: 'Summarize Recent Changes',
@@ -7,6 +8,10 @@ export function registerPrompts(server, api) {
             fileMsId: z.string().describe('Platform ID of the enrolled file'),
         },
     }, async ({ fileMsId }) => {
+        // Plan 02 ruling 5 (STRICT) — a prompt is the highest-risk surface: its
+        // whole product is a model narrating these rows as fact. Refuse before
+        // assembling anything; a prompt has no error channel but its own throw.
+        await assertChangeHistoryComplete(api, fileMsId);
         const [file, versions, changesPage] = await Promise.all([
             api.getEnrolledFile(fileMsId),
             api.getFileVersions(fileMsId),
@@ -118,6 +123,9 @@ export function registerPrompts(server, api) {
             fileMsId: z.string().describe('Platform ID of the enrolled file'),
         },
     }, async ({ fileMsId }) => {
+        // Plan 02 ruling 5 (STRICT) — this prompt reports a change COUNT, which
+        // is the same factual claim in one number instead of many rows.
+        await assertChangeHistoryComplete(api, fileMsId);
         const [file, versions, comments, changesPage] = await Promise.all([
             api.getEnrolledFile(fileMsId),
             api.getFileVersions(fileMsId),