@specship/specship-win32-arm64 0.21.2 → 0.23.0

package/lib/dist/activation/search-intercept.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Point-of-use search interceptor (STEER-HOOK-DOC, REQ-STEER-004/005).
+ *
+ * The prompt-level nudge (steering.ts) fires once, at prompt submit, and its
+ * pull decays across a long turn — the observed failure is a search-shaped
+ * tool call made many tool-calls after the nudge. This module is the decision
+ * logic for the `PreToolUse` hook the installer writes on search tools
+ * (`specship search-intercept`): deliver the same guidance at the moment of
+ * the wrong choice.
+ *
+ * Two properties are non-negotiable:
+ *
+ *   - ADVISORY (REQ-STEER-004): the emitted text is `additionalContext`,
+ *     never a permission decision. A search the index cannot answer is a
+ *     legitimate search; a wrong denial costs the agent a turn — the very
+ *     failure this feature exists to reduce.
+ *   - SELF-SILENCING (REQ-STEER-005): at most one line per session, and only
+ *     when the session has made zero specship tool calls. Firing on every
+ *     search would make the hook noise, and noise is what taught the agent to
+ *     ignore the prompt-level nudge.
+ */
+/**
+ * The one redirect line. Explicitly advisory ("your search still runs") so
+ * the model doesn't treat it as a rejection of the call it just made.
+ */
+export declare const SEARCH_INTERCEPT_TEXT: string;
+/** Per-session tracking file, kept inside the project's own `.specship/`. */
+export declare function interceptStatePath(projectRoot: string): string;
+export interface SearchInterceptInput {
+    /** Project the intercepted call belongs to (the hook payload's `cwd`). */
+    cwd: string;
+    /** Claude Code session id from the hook payload; null → untrackable, stay silent. */
+    sessionId: string | null;
+    /** Session transcript path from the hook payload, when present. */
+    transcriptPath: string | null;
+    env?: NodeJS.ProcessEnv;
+    homedir?: string;
+    /** Injectable clock for tests. */
+    now?: Date;
+}
+/**
+ * Decide whether to emit the redirect line for one intercepted search call.
+ *
+ * Silence gates, in order (all REQ-STEER-004.A3 / REQ-STEER-005):
+ *   1. `SPECSHIP_NO_STEERING=1` (env > project > install settings) — same
+ *      opt-out as the prompt nudge.
+ *   2. No `.specship/` directory at cwd — uninitialized projects get zero
+ *      noise.
+ *   3. No session id — nothing to key the once-per-session guarantee on, so
+ *      silence beats repeat-firing.
+ *   4. The session is already recorded — it fired before, or was seen using
+ *      specship.
+ *   5. The transcript shows specship use — the agent doesn't need redirecting;
+ *      record the session so later calls skip the scan.
+ *
+ * Otherwise: record the session and return the line (fires exactly once).
+ */
+export declare function buildSearchIntercept(input: SearchInterceptInput): string | null;
+//# sourceMappingURL=search-intercept.d.ts.map

package/lib/dist/activation/search-intercept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-intercept.d.ts","sourceRoot":"","sources":["../../src/activation/search-intercept.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAIX,CAAC;AAExB,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AA8ED,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAwB/E"}

package/lib/dist/activation/search-intercept.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Point-of-use search interceptor (STEER-HOOK-DOC, REQ-STEER-004/005).
+ *
+ * The prompt-level nudge (steering.ts) fires once, at prompt submit, and its
+ * pull decays across a long turn — the observed failure is a search-shaped
+ * tool call made many tool-calls after the nudge. This module is the decision
+ * logic for the `PreToolUse` hook the installer writes on search tools
+ * (`specship search-intercept`): deliver the same guidance at the moment of
+ * the wrong choice.
+ *
+ * Two properties are non-negotiable:
+ *
+ *   - ADVISORY (REQ-STEER-004): the emitted text is `additionalContext`,
+ *     never a permission decision. A search the index cannot answer is a
+ *     legitimate search; a wrong denial costs the agent a turn — the very
+ *     failure this feature exists to reduce.
+ *   - SELF-SILENCING (REQ-STEER-005): at most one line per session, and only
+ *     when the session has made zero specship tool calls. Firing on every
+ *     search would make the hook noise, and noise is what taught the agent to
+ *     ignore the prompt-level nudge.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEARCH_INTERCEPT_TEXT = void 0;
+exports.interceptStatePath = interceptStatePath;
+exports.buildSearchIntercept = buildSearchIntercept;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_settings_1 = require("../config/runtime-settings");
+/**
+ * The one redirect line. Explicitly advisory ("your search still runs") so
+ * the model doesn't treat it as a rejection of the call it just made.
+ */
+exports.SEARCH_INTERCEPT_TEXT = 'SpecShip: this project has an indexed code graph. For finding or understanding code, ' +
+    'mcp__specship__specship_explore with the relevant symbol/file names usually answers in ' +
+    'ONE call and returns the verbatim source. Your search still runs — reach for explore ' +
+    'on the next lookup.';
+/** Per-session tracking file, kept inside the project's own `.specship/`. */
+function interceptStatePath(projectRoot) {
+    return path.join(projectRoot, '.specship', 'steer-intercept-state.json');
+}
+/** Records older than this are pruned on write (REQ-STEER-005.A4). */
+const STATE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+function readState(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (v && typeof v === 'object' && typeof v.at === 'string') {
+                out[k] = { at: v.at };
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Best-effort write with TTL pruning; a failed write must never fail the hook. */
+function writeState(file, state, now) {
+    try {
+        const pruned = {};
+        for (const [k, v] of Object.entries(state)) {
+            const at = Date.parse(v.at);
+            if (Number.isFinite(at) && now.getTime() - at < STATE_TTL_MS)
+                pruned[k] = v;
+        }
+        fs.writeFileSync(file, JSON.stringify(pruned));
+    }
+    catch {
+        /* state is an optimization; losing it only risks one extra advisory line */
+    }
+}
+/**
+ * Whether the session's transcript shows any specship tool USE. A transcript
+ * record must be an actual `tool_use` naming a specship tool — a bare
+ * mention of a tool name is NOT use: transcripts routinely carry the full
+ * tool listing (`deferred_tools_delta` attachments, skill listings), so a
+ * substring test alone silences the hook in every session where specship is
+ * merely INSTALLED (found live in the REQ-STEER-006 A/B — the interceptor
+ * never fired). Reads at most the trailing 4 MB — usage anywhere counts, but
+ * a huge transcript must not blow the hook's latency budget, and a false
+ * negative costs one harmless advisory line.
+ */
+function transcriptUsedSpecship(transcriptPath) {
+    const MAX_SCAN_BYTES = 4 * 1024 * 1024;
+    let text;
+    try {
+        const stat = fs.statSync(transcriptPath);
+        if (stat.size <= MAX_SCAN_BYTES) {
+            text = fs.readFileSync(transcriptPath, 'utf-8');
+        }
+        else {
+            const fd = fs.openSync(transcriptPath, 'r');
+            try {
+                const buf = Buffer.alloc(MAX_SCAN_BYTES);
+                const read = fs.readSync(fd, buf, 0, MAX_SCAN_BYTES, stat.size - MAX_SCAN_BYTES);
+                text = buf.toString('utf-8', 0, read);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    // One JSONL record per line; a specship tool_use block puts both markers on
+    // the same record. Cheap two-substring test — no JSON.parse per line.
+    for (const line of text.split('\n')) {
+        if (line.includes('"type":"tool_use"') && line.includes('"name":"mcp__specship__')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decide whether to emit the redirect line for one intercepted search call.
+ *
+ * Silence gates, in order (all REQ-STEER-004.A3 / REQ-STEER-005):
+ *   1. `SPECSHIP_NO_STEERING=1` (env > project > install settings) — same
+ *      opt-out as the prompt nudge.
+ *   2. No `.specship/` directory at cwd — uninitialized projects get zero
+ *      noise.
+ *   3. No session id — nothing to key the once-per-session guarantee on, so
+ *      silence beats repeat-firing.
+ *   4. The session is already recorded — it fired before, or was seen using
+ *      specship.
+ *   5. The transcript shows specship use — the agent doesn't need redirecting;
+ *      record the session so later calls skip the scan.
+ *
+ * Otherwise: record the session and return the line (fires exactly once).
+ */
+function buildSearchIntercept(input) {
+    const { cwd, sessionId, transcriptPath, env = process.env, homedir, now = new Date() } = input;
+    if ((0, runtime_settings_1.resolveSetting)('SPECSHIP_NO_STEERING', cwd, env, homedir) === '1')
+        return null;
+    try {
+        if (!fs.statSync(path.join(cwd, '.specship')).isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    if (!sessionId)
+        return null;
+    const stateFile = interceptStatePath(cwd);
+    const state = readState(stateFile);
+    if (state[sessionId])
+        return null;
+    state[sessionId] = { at: now.toISOString() };
+    if (transcriptPath && transcriptUsedSpecship(transcriptPath)) {
+        // Already an index user — silence, but remember so we don't rescan.
+        writeState(stateFile, state, now);
+        return null;
+    }
+    writeState(stateFile, state, now);
+    return exports.SEARCH_INTERCEPT_TEXT;
+}
+//# sourceMappingURL=search-intercept.js.map

package/lib/dist/activation/search-intercept.js.map

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