@specship/specship-win32-arm64 0.23.0 → 0.25.0

package/lib/dist/mcp/tools.js

@@ -15,6 +15,7 @@ exports.formatStaleFooter = formatStaleFooter;
 exports.integrationEnabled = integrationEnabled;
 exports.toolIntegration = toolIntegration;
 exports.filterIntegrationTools = filterIntegrationTools;
+exports.applyLiteTierTrim = applyLiteTierTrim;
 exports.getStaticTools = getStaticTools;
 const directory_1 = require("../directory");
 const statusline_1 = require("../statusline");
@@ -411,6 +412,7 @@ const projectPathProperty = {
 const spec_tools_1 = require("./spec-tools");
 const maintainability_tool_1 = require("./maintainability-tool");
 const fitness_tool_1 = require("./fitness-tool");
+const health_tool_1 = require("./health-tool");
 const designer_tools_1 = require("./designer-tools");
 const jira_tools_1 = require("./jira-tools");
 exports.tools = [
@@ -549,7 +551,7 @@ exports.tools = [
     },
     {
         name: 'specship_status',
-        description: 'Index health check (files / nodes / edges). Skip unless debugging.',
+        description: 'Index health check (files / nodes / edges) AND server identity — package version, install method (bundle/npm/unknown), the install serving this session, and node version. Works with no project open (identity only). Skip unless debugging or asked which SpecShip is running.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -557,14 +559,6 @@ exports.tools = [
             },
         },
     },
-    {
-        name: 'specship_version',
-        description: 'Identify the running SpecShip MCP server: package version, install method (bundle/npm/unknown), install dir, node version, and project root (if bound). Zero-arg, no index required — safe to call before any project is open.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
     {
         name: 'specship_files',
         description: 'Indexed file tree with language + symbol counts. Faster than Glob for project layout.',
@@ -600,8 +594,10 @@ exports.tools = [
     },
     // Spec-layer tools (v5): see ./spec-tools.ts for handlers.
     ...spec_tools_1.specToolDefinitions,
-    ...maintainability_tool_1.maintainabilityToolDefinitions,
-    ...fitness_tool_1.fitnessToolDefinitions,
+    // Code health: one tool for maintainability + architecture fitness
+    // (REQ-SURF-007). The two former tools still execute for clients holding a
+    // cached list, but they are off the menu.
+    ...health_tool_1.healthToolDefinitions,
     // Designer tools: claude.ai/design driving, vendored from @pro-vi/designer.
     // See ./designer-tools.ts for handlers. Drives a debug Chrome over CDP.
     ...designer_tools_1.designerToolDefinitions,
@@ -629,19 +625,54 @@ function filterIntegrationTools(list, env = process.env) {
         return integ === null || integrationEnabled(integ, env);
     });
 }
+/**
+ * Lite-tier menu trim (LOWMODEL-DOC, REQ-LOWMODEL-004): small-model tool
+ * choice degrades with menu size, so the code-graph group trims to the core
+ * three; spec/link tools and enabled integrations are untouched. Composes
+ * with the tiny-repo gate and SPECSHIP_MCP_TOOLS as an intersection.
+ * Schemas never vary — only the list; `execute()` still answers a
+ * trimmed-away tool for clients that cached the full list (A2).
+ *
+ * Needs only a project-root hint, NOT an open DB — tier detection reads the
+ * session model marker file. That is what lets the proxy's connect-time
+ * static list trim too (A4); `hint` may be any path at or under the project
+ * (the nearest `.specship/` root wins).
+ */
+const LITE_CORE_TOOLS = new Set(['specship_explore', 'specship_search', 'specship_node']);
+// `specship_status` is deliberately NOT in this group (REQ-SURF-006.A2): it
+// carries the server-identity answer, so the lite tier must keep it.
+const CODE_GRAPH_GROUP = new Set([
+    'specship_explore', 'specship_search', 'specship_node',
+    'specship_callers', 'specship_callees', 'specship_impact',
+    'specship_files',
+    'specship_health',
+]);
+function applyLiteTierTrim(list, hint) {
+    if (!hint)
+        return list;
+    const root = (0, directory_1.findNearestSpecShipRoot)(hint);
+    if (!root || (0, model_context_1.detectModelTier)(root) !== 'lite')
+        return list;
+    return list.filter(t => !CODE_GRAPH_GROUP.has(t.name) || LITE_CORE_TOOLS.has(t.name));
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
  * `ToolHandler.getTools()` in the no-SpecShip case (the dynamic per-repo budget
  * note in a description only adds once `cg` is loaded; the schemas are static).
+ * When a project-root hint is given, the lite-tier trim applies here too
+ * (REQ-LOWMODEL-004.A4) — the marker file needs no DB open.
  */
-function getStaticTools() {
+function getStaticTools(projectRootHint) {
     const base = filterIntegrationTools(exports.tools);
     const raw = process.env.SPECSHIP_MCP_TOOLS;
-    if (!raw || !raw.trim())
-        return base;
-    const allow = new Set(raw.split(',').map(s => s.trim().replace(/^specship_/, '')).filter(Boolean));
-    return allow.size ? base.filter(t => allow.has(t.name.replace(/^specship_/, ''))) : base;
+    let visible = base;
+    if (raw && raw.trim()) {
+        const allow = new Set(raw.split(',').map(s => s.trim().replace(/^specship_/, '')).filter(Boolean));
+        if (allow.size)
+            visible = base.filter(t => allow.has(t.name.replace(/^specship_/, '')));
+    }
+    return applyLiteTierTrim(visible, projectRootHint ?? null);
 }
 /**
  * Tool handler that executes tools against a SpecShip instance
@@ -772,29 +803,18 @@ class ToolHandler {
                 'specship_explore',
                 'specship_search',
                 'specship_node',
-                'specship_version',
+                // Identity probe — folded into status (REQ-SURF-006), which therefore
+                // survives the tiny-repo trim the way specship_version used to.
+                'specship_status',
             ]);
             if (stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
                 // Designer tools are not code-graph tools — the tiny-repo flow-question
                 // economics that justify trimming don't apply, so they always survive.
                 visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name) || t.name.startsWith('designer_'));
             }
-            // Haiku-tier menu trim (LOWMODEL-DOC, REQ-LOWMODEL-004): small-model
-            // tool choice degrades with menu size, so the code-graph group trims
-            // to the core three; spec/link tools and enabled integrations are
-            // untouched. Composes with the tiny-repo gate as an intersection.
-            // Schemas never vary — only the list; `execute()` still answers a
-            // trimmed-away tool for clients that cached the full list (A2).
-            if ((0, model_context_1.detectModelTier)(this.cg.getProjectRoot()) === 'haiku') {
-                const HAIKU_CORE = new Set(['specship_explore', 'specship_search', 'specship_node']);
-                const CODE_GRAPH_GROUP = new Set([
-                    'specship_explore', 'specship_search', 'specship_node',
-                    'specship_callers', 'specship_callees', 'specship_impact',
-                    'specship_files', 'specship_status',
-                    'specship_maintainability', 'specship_fitness',
-                ]);
-                visible = visible.filter(t => !CODE_GRAPH_GROUP.has(t.name) || HAIKU_CORE.has(t.name));
-            }
+            // Lite-tier menu trim — shared with the proxy's static list (A4);
+            // see applyLiteTierTrim above for the full contract.
+            visible = applyLiteTierTrim(visible, this.cg.getProjectRoot());
             return visible.map(tool => {
                 if (tool.name === 'specship_explore') {
                     return {
@@ -982,11 +1002,11 @@ class ToolHandler {
     /**
      * Model-aware compaction (MODCTX-DOC, REQ-MODCTX-002/003). Resolves the
      * session's model tier (status-line marker / SPECSHIP_MODEL; SPECSHIP_COMPACT=0
-     * disables) and, on haiku/sonnet, compresses the response's prose
+     * disables) and, on the lite/standard tiers, compresses the response's prose
      * scaffolding — fenced code stays byte-verbatim. Full tier is identity.
      */
     /**
-     * Tier-change listeners (LOWMODEL-DOC, REQ-LOWMODEL-004.A3): the haiku
+     * Tier-change listeners (LOWMODEL-DOC, REQ-LOWMODEL-004.A3): the lite-tier
      * menu trim changes `tools/list`, so a mid-session /model switch must ride
      * an MCP `notifications/tools/list_changed`. Sessions subscribe here; the
      * change is detected on the next code-graph call (the same funnel that
@@ -1166,11 +1186,13 @@ class ToolHandler {
             // its own verbose worktree warning but still flows through the
             // staleness wrapper so its pending-files section stays consistent
             // with what the read tools surface.
-            // specship_version (REQ-MCPVER-001): zero-arg identity probe. Answered
-            // before the worktree/staleness/compaction wrappers so it works with no
-            // project open and never touches the DB.
+            // specship_version (REQ-MCPVER-001): zero-arg identity probe, folded into
+            // specship_status (REQ-SURF-006) and off the menu. Still answered here for
+            // clients holding a cached tool list. Runs before the
+            // worktree/staleness/compaction wrappers so it works with no project open
+            // and never touches the DB.
             if (toolName === 'specship_version') {
-                return this.handleVersion();
+                return this.textResult(this.identityBlock());
             }
             let result;
             switch (toolName) {
@@ -1212,6 +1234,11 @@ class ToolHandler {
                 case 'specship_drifted':
                     result = await (0, spec_tools_1.handleSpecshipDrifted)(this.getSpecShip(args.projectPath), args);
                     break;
+                case 'specship_health':
+                    result = await (0, health_tool_1.handleSpecshipHealth)(this.getSpecShip(args.projectPath), args);
+                    break;
+                // Folded into specship_health (REQ-SURF-007) and off the menu; still
+                // answered for clients holding a cached tool list.
                 case 'specship_maintainability':
                     result = await (0, maintainability_tool_1.handleSpecshipMaintainability)(this.getSpecShip(args.projectPath), args);
                     break;
@@ -1336,7 +1363,7 @@ class ToolHandler {
             }
             const withWorktree = this.withWorktreeNotice(result, args.projectPath);
             const withStaleness = this.withStalenessNotice(withWorktree, args.projectPath);
-            // Model-aware compaction (MODCTX-DOC): on haiku/sonnet sessions the
+            // Model-aware compaction (MODCTX-DOC): on lite/standard sessions the
             // prose scaffolding compresses; code stays byte-verbatim. Only the
             // code-graph tools reach this funnel — designer/jira returned above
             // (REQ-MODCTX-004).
@@ -1765,7 +1792,7 @@ class ToolHandler {
                 out.push('## Flow (call path among the symbols you queried)', '');
                 for (let i = 0; i < best.length; i++) {
                     const step = best[i];
-                    if (tier === 'haiku') {
+                    if (tier === 'lite') {
                         // LOWMODEL-DOC REQ-LOWMODEL-003: small models don't synthesize
                         // the flow from evidence — render each hop as ONE explicit line
                         // with its mechanism inline. Additive formatting only; the code
@@ -3232,12 +3259,13 @@ class ToolHandler {
         return lines.join('\n');
     }
     /**
-     * Handle specship_version (REQ-MCPVER-001). Identifies the running MCP
-     * server process — the version an agent's tools are being served by,
-     * how it was installed, node version, and (if bound) the project root.
-     * Zero-arg, synchronous, never touches the DB, safe with no project.
+     * Server identity (REQ-MCPVER-001, folded into specship_status by
+     * REQ-SURF-006). Identifies the running MCP server process — the version an
+     * agent's tools are being served by, how it was installed, node version, and
+     * (if bound) the project root. Synchronous, never touches the DB, safe with
+     * no project open.
      */
-    handleVersion() {
+    identityBlock() {
         const binDirname = (0, path_1.dirname)(__filename);
         const installDir = (0, updater_1.resolveInstallDir)();
         const installMethod = (0, updater_1.detectInstallMethod)(binDirname, installDir);
@@ -3265,13 +3293,24 @@ class ToolHandler {
             `**node:** ${process.version}`,
             `**projectRoot:** ${projectRoot ?? 'null'}`,
         ];
-        return this.textResult(lines.join('\n'));
+        return lines.join('\n');
     }
     /**
      * Handle specship_status
      */
     async handleStatus(args) {
-        let cg = this.getSpecShip(args.projectPath);
+        // Server identity leads the response (REQ-SURF-006.A1) and is answerable
+        // with no project open, so a status call on an unindexed directory still
+        // tells the agent which SpecShip is serving it.
+        const identity = this.identityBlock();
+        let cg;
+        try {
+            cg = this.getSpecShip(args.projectPath);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            return this.textResult(`${identity}\n\n## SpecShip Status\n\n${detail}`);
+        }
         // Same trick as withStalenessNotice — when an explicit projectPath
         // resolves to the same project as the default session cg, prefer the
         // default so getPendingFiles() (only populated by the default's watcher)
@@ -3292,6 +3331,8 @@ class ToolHandler {
         // one-liner via withWorktreeNotice. Both share the cached detection.
         const mismatch = this.worktreeMismatchFor(args.projectPath);
         const lines = [
+            identity,
+            '',
             '## SpecShip Status',
             '',
         ];