@planu/cli 4.3.7 → 4.3.8

package/dist/engine/auto-updater/config-patcher.d.ts

@@ -1,4 +1,5 @@
 import type { McpServerEntry } from '../../types/auto-update.js';
+export declare const PLANU_MCP_STARTUP_TIMEOUT_SEC = 120;
 /**
  * Patches the mcpServers.planu entry in the given config file.
  * Steps:

package/dist/engine/auto-updater/config-patcher.js

@@ -3,6 +3,7 @@
 // SPEC-443
 // Creates a backup before any modification. Restores backup on write failure.
 import { readFile, writeFile } from 'node:fs/promises';
+export const PLANU_MCP_STARTUP_TIMEOUT_SEC = 120;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -64,6 +65,7 @@ export function buildNpxLatestEntry() {
     return {
         command: 'npx',
         args: ['-y', '@planu/cli@latest'],
+        startup_timeout_sec: PLANU_MCP_STARTUP_TIMEOUT_SEC,
     };
 }
 /**
@@ -73,6 +75,7 @@ export function buildPinnedEntry(version) {
     return {
         command: 'npx',
         args: ['-y', `@planu/cli@${version}`],
+        startup_timeout_sec: PLANU_MCP_STARTUP_TIMEOUT_SEC,
     };
 }
 //# sourceMappingURL=config-patcher.js.map

package/dist/engine/config-health/index.d.ts

@@ -6,6 +6,7 @@ export { checkCargoFeatures, checkClippyConfig, checkRustToolchain } from './rus
 export { checkCiCommands, checkBuildArtifacts, checkVersionConsistency } from './ci-checker.js';
 export { checkOtelVersionCompatibility } from './otel-checker.js';
 export { checkBuildToolHealth } from './build-tool-checker.js';
+export { checkMcpConfig } from './mcp-config-checker.js';
 export type { ConfigHealthCheckGroup as CheckGroup } from '../../types/index.js';
 /**
  * Run all requested config health checkers in parallel and return a

package/dist/engine/config-health/index.js

@@ -7,6 +7,7 @@ import { checkCargoFeatures, checkClippyConfig, checkRustToolchain } from './rus
 import { checkCiCommands, checkBuildArtifacts, checkVersionConsistency } from './ci-checker.js';
 import { checkOtelVersionCompatibility } from './otel-checker.js';
 import { checkBuildToolHealth } from './build-tool-checker.js';
+import { checkMcpConfig } from './mcp-config-checker.js';
 // Re-export individual checkers for direct use
 export { checkTsCoverage, checkVitestSchema, checkJestSchema, checkPackageScripts, checkHuskyScripts, } from './ts-checker.js';
 export { checkPyprojectSchema, checkMypyConfig, checkPythonScripts, checkRequirementsConflicts, } from './python-checker.js';
@@ -15,6 +16,7 @@ export { checkCargoFeatures, checkClippyConfig, checkRustToolchain } from './rus
 export { checkCiCommands, checkBuildArtifacts, checkVersionConsistency } from './ci-checker.js';
 export { checkOtelVersionCompatibility } from './otel-checker.js';
 export { checkBuildToolHealth } from './build-tool-checker.js';
+export { checkMcpConfig } from './mcp-config-checker.js';
 const SEVERITY_ORDER = {
     error: 0,
     warning: 1,
@@ -32,7 +34,8 @@ const SEVERITY_ORDER = {
  * @param minSeverity - Minimum severity level to include in findings (default: info).
  */
 export async function runConfigHealthChecks(projectPath, checks, minSeverity = 'info') {
-    const activeChecks = checks ?? ['ts', 'python', 'go', 'rust', 'ci', 'build-tool'];
+    const activeChecks = checks ??
+        ['ts', 'python', 'go', 'rust', 'ci', 'build-tool', 'mcp'];
     const minOrder = SEVERITY_ORDER[minSeverity];
     const checkPromises = [];
     if (activeChecks.includes('ts')) {
@@ -56,6 +59,9 @@ export async function runConfigHealthChecks(projectPath, checks, minSeverity = '
     if (activeChecks.includes('build-tool')) {
         checkPromises.push(checkBuildToolHealth(projectPath));
     }
+    if (activeChecks.includes('mcp')) {
+        checkPromises.push(checkMcpConfig(projectPath));
+    }
     const results = await Promise.all(checkPromises);
     const allFindings = results.flat();
     // Filter by minimum severity

package/dist/engine/config-health/mcp-config-checker.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigHealthFinding, McpConfigCheckOptions } from '../../types/index.js';
+export declare function checkMcpConfig(projectPath: string, options?: McpConfigCheckOptions): Promise<ConfigHealthFinding[]>;
+//# sourceMappingURL=mcp-config-checker.d.ts.map

package/dist/engine/config-health/mcp-config-checker.js

@@ -0,0 +1,144 @@
+// engine/config-health/mcp-config-checker.ts — SPEC-1062
+// Detects unsafe Planu MCP host configuration.
+import { access, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readIfExists(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function replacementFix() {
+    return 'Replace the Planu MCP entry with command "npx", args ["-y", "@planu/cli@latest"], and startup_timeout_sec 120 where the host supports it.';
+}
+async function checkPathTarget(configFile, target) {
+    if (!target || !isAbsolute(target) || (await fileExists(target))) {
+        return [];
+    }
+    return [
+        {
+            severity: 'error',
+            checker: 'mcp-config',
+            file: configFile,
+            message: `Planu MCP config points to missing path '${target}'`,
+            fix: replacementFix(),
+        },
+    ];
+}
+async function checkJsonConfig(basePath, relativePath, displayPath = relativePath) {
+    const filePath = join(basePath, relativePath);
+    const raw = await readIfExists(filePath);
+    if (!raw) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const planu = parsed.mcpServers?.planu;
+    if (!planu) {
+        return [];
+    }
+    const findings = await checkPathTarget(displayPath, planu.command);
+    for (const arg of planu.args ?? []) {
+        findings.push(...(await checkPathTarget(displayPath, arg)));
+    }
+    return findings;
+}
+function extractPlanuCodexServer(content) {
+    const serverBlocks = content.split(/\n(?=\[\[mcp\.servers\]\])/);
+    return serverBlocks.find((block) => /name\s*=\s*"planu"/.test(block)) ?? null;
+}
+function extractTomlString(block, key) {
+    const match = new RegExp(`^${key}\\s*=\\s*"([^"]+)"`, 'm').exec(block);
+    return match?.[1];
+}
+function extractTomlStringArray(block, key) {
+    const match = new RegExp(`^${key}\\s*=\\s*\\[([^\\]]*)\\]`, 'm').exec(block);
+    const body = match?.[1];
+    if (!body) {
+        return [];
+    }
+    return [...body.matchAll(/"([^"]+)"/g)].map((item) => item[1] ?? '');
+}
+async function checkCodexConfig(basePath, relativePath, displayPath = relativePath) {
+    const raw = await readIfExists(join(basePath, relativePath));
+    if (!raw) {
+        return [];
+    }
+    const planuBlock = extractPlanuCodexServer(raw);
+    if (!planuBlock) {
+        return [];
+    }
+    const findings = await checkPathTarget(displayPath, extractTomlString(planuBlock, 'command'));
+    for (const arg of extractTomlStringArray(planuBlock, 'args')) {
+        findings.push(...(await checkPathTarget(displayPath, arg)));
+    }
+    const timeoutMatch = /^startup_timeout_sec\s*=\s*(\d+)/m.exec(planuBlock);
+    const timeout = timeoutMatch?.[1] ? Number(timeoutMatch[1]) : 0;
+    if (timeout < 60) {
+        findings.push({
+            severity: 'warning',
+            checker: 'mcp-config',
+            file: displayPath,
+            message: 'Planu Codex MCP config is missing startup_timeout_sec >= 60',
+            fix: 'Add startup_timeout_sec = 120 to the planu MCP server block.',
+        });
+    }
+    return findings;
+}
+function uniqueLocations(locations) {
+    const seen = new Set();
+    return locations.filter((location) => {
+        const key = join(location.basePath, location.relativePath);
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+export async function checkMcpConfig(projectPath, options = {}) {
+    const homePath = options.homePath ?? homedir();
+    const jsonLocations = uniqueLocations([
+        { basePath: projectPath, relativePath: '.mcp.json' },
+        { basePath: projectPath, relativePath: '.claude.json' },
+        { basePath: projectPath, relativePath: '.claude/claude.json' },
+        { basePath: homePath, relativePath: '.claude.json', displayPath: '~/.claude.json' },
+        {
+            basePath: homePath,
+            relativePath: '.claude/claude.json',
+            displayPath: '~/.claude/claude.json',
+        },
+    ]);
+    const codexLocations = uniqueLocations([
+        { basePath: projectPath, relativePath: '.openai/config.toml' },
+        { basePath: homePath, relativePath: '.codex/config.toml', displayPath: '~/.codex/config.toml' },
+        {
+            basePath: homePath,
+            relativePath: '.openai/config.toml',
+            displayPath: '~/.openai/config.toml',
+        },
+    ]);
+    const results = await Promise.all([
+        ...jsonLocations.map((location) => checkJsonConfig(location.basePath, location.relativePath, location.displayPath)),
+        ...codexLocations.map((location) => checkCodexConfig(location.basePath, location.relativePath, location.displayPath)),
+    ]);
+    return results.flat();
+}
+//# sourceMappingURL=mcp-config-checker.js.map

package/dist/engine/mcp-config/mcp-config-writer.d.ts

@@ -9,7 +9,7 @@ import type { CheckAndFixResult } from '../../types/mcp-config.js';
  */
 export declare function findMcpConfigPath(projectPath: string): Promise<string>;
 /**
- * Returns true if the config already has a `planu` entry pointing to @planu/cli@latest.
+ * Returns true if the config already has a safe `planu` entry pointing to @planu/cli@latest.
  */
 export declare function isPlanuDirectlyConfigured(configPath: string): Promise<boolean>;
 /**

package/dist/engine/mcp-config/mcp-config-writer.js

@@ -4,11 +4,13 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { buildNpxLatestEntry } from '../auto-updater/config-patcher.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const PLANU_KEY = 'planu';
 const PLANU_LATEST_ARG = '@planu/cli@latest';
+const MIN_STARTUP_TIMEOUT_SEC = 60;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -60,7 +62,7 @@ export async function findMcpConfigPath(projectPath) {
     return join(projectPath, '.mcp.json');
 }
 /**
- * Returns true if the config already has a `planu` entry pointing to @planu/cli@latest.
+ * Returns true if the config already has a safe `planu` entry pointing to @planu/cli@latest.
  */
 export async function isPlanuDirectlyConfigured(configPath) {
     const config = await readJsonFile(configPath);
@@ -76,7 +78,8 @@ export async function isPlanuDirectlyConfigured(configPath) {
     if (!Array.isArray(args)) {
         return false;
     }
-    return args.includes(PLANU_LATEST_ARG);
+    return (args.includes(PLANU_LATEST_ARG) &&
+        (planuEntry.startup_timeout_sec ?? 0) >= MIN_STARTUP_TIMEOUT_SEC);
 }
 /**
  * Merges the direct Planu entry into the config file.
@@ -85,7 +88,7 @@ export async function isPlanuDirectlyConfigured(configPath) {
 export async function injectDirectPlanuEntry(configPath, currentVersion, latestVersion) {
     const existing = await readJsonFile(configPath);
     const mcpServers = existing.mcpServers !== undefined ? { ...existing.mcpServers } : {};
-    mcpServers[PLANU_KEY] = { command: 'npx', args: ['-y', PLANU_LATEST_ARG] };
+    mcpServers[PLANU_KEY] = buildNpxLatestEntry();
     const updated = {
         ...existing,
         mcpServers,

package/dist/hosts/codex/config-scaffold.js

@@ -26,6 +26,7 @@ name = "planu"
 transport = "stdio"
 command = "npx"
 args = ["@planu/cli@latest"]
+startup_timeout_sec = 120
 
 [workspace]
 # Spec files are stored under planu/ — do not gitignore this directory.

package/dist/tools/check-config-health.js

@@ -9,10 +9,10 @@ import { safeTracked } from './safe-handler.js';
 const checkConfigHealthSchema = {
     projectPath: z.string().max(4096).describe('Absolute path to the project root to check'),
     checks: z
-        .array(z.enum(['ts', 'python', 'go', 'rust', 'ci', 'build-tool']))
+        .array(z.enum(['ts', 'python', 'go', 'rust', 'ci', 'build-tool', 'mcp']))
         .max(100)
         .optional()
-        .describe('Subset of check groups to run. Default: all groups (ts, python, go, rust, ci, build-tool)'),
+        .describe('Subset of check groups to run. Default: all groups (ts, python, go, rust, ci, build-tool, mcp)'),
     severity: z
         .enum(['error', 'warning', 'info'])
         .optional()

package/dist/tools/validate.js

@@ -392,9 +392,31 @@ function buildCompactValidateText(args) {
 }
 /** Allowlist: alphanumerics, spaces, and safe shell chars. Rejects ; | $ ` & < > */
 const SAFE_COMMAND_RE = /^[\w\s./:@~=-]+$/;
+const LINT_CHECK_TIMEOUT_MS = 50_000;
 function isSafeCommand(cmd) {
     return SAFE_COMMAND_RE.test(cmd);
 }
+function isCommandTimeout(err) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    const errorWithProcessFields = err;
+    return (errorWithProcessFields.signal === 'SIGTERM' ||
+        errorWithProcessFields.killed === true ||
+        errorWithProcessFields.code === 'ETIMEDOUT' ||
+        /timed out|timeout/i.test(err.message));
+}
+function commandOutput(err) {
+    if (!(err instanceof Error)) {
+        return String(err);
+    }
+    const errorWithOutput = err;
+    return [errorWithOutput.stdout, errorWithOutput.stderr]
+        .filter((chunk) => chunk !== undefined)
+        .map((chunk) => String(chunk))
+        .join('\n')
+        .trim();
+}
 function runLintCheck(projectPath, lintCommand) {
     if (lintCommand !== null && !isSafeCommand(lintCommand)) {
         console.warn(`[Planu] validate: lintCommand contains unsafe characters — skipping execution`);
@@ -413,14 +435,19 @@ function runLintCheck(projectPath, lintCommand) {
         execSync(command, {
             cwd: projectPath,
             stdio: ['pipe', 'pipe', 'pipe'],
-            timeout: 30_000,
+            timeout: LINT_CHECK_TIMEOUT_MS,
         });
         return { passed: true, command, issueCount: 0, output: '' };
     }
     catch (err) {
-        const raw = err instanceof Error && 'stdout' in err
-            ? String(err.stdout ?? '')
-            : String(err);
+        if (isCommandTimeout(err)) {
+            const seconds = Math.round(LINT_CHECK_TIMEOUT_MS / 1000);
+            const output = `Lint command timed out after ${String(seconds)}s and was skipped so validate can complete within MCP request limits. ` +
+                `Run \`${command}\` manually before marking the spec done.`;
+            console.warn(`[Planu] lintCheck timed out: command="${command}" cwd="${projectPath}" timeoutMs=${String(LINT_CHECK_TIMEOUT_MS)}`);
+            return { passed: true, command, issueCount: 0, output };
+        }
+        const raw = commandOutput(err);
         // SPEC-787: never truncate — preserve full output so caller sees real issues
         const output = raw.trim();
         const issueCount = parseLintIssueCount(output);

package/dist/transports/transport-factory.js

@@ -41,10 +41,41 @@ export async function selectTransport(server, args, serverFactory) {
     if (config.transport === 'stdio') {
         const transport = new StdioServerTransport();
         await server.connect(transport);
+        installStdioShutdownHandlers(server);
         return;
     }
     // HTTP mode: each session needs its own McpServer instance
     const factory = serverFactory ?? (() => server);
     await createHttpTransport(factory, config);
 }
+function installStdioShutdownHandlers(server) {
+    let shuttingDown = false;
+    const shutdown = (reason) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        console.error(`[Planu] MCP stdio ${reason}; shutting down.`);
+        void server
+            .close()
+            .catch((err) => {
+            console.error('[Planu] Error while closing MCP server:', err);
+        })
+            .finally(() => {
+            process.exit(0);
+        });
+    };
+    process.stdin.once('end', () => {
+        shutdown('stdin ended');
+    });
+    process.stdin.once('close', () => {
+        shutdown('stdin closed');
+    });
+    process.once('SIGTERM', () => {
+        shutdown('received SIGTERM');
+    });
+    process.once('SIGINT', () => {
+        shutdown('received SIGINT');
+    });
+}
 //# sourceMappingURL=transport-factory.js.map

package/dist/types/analysis-detection.d.ts

@@ -63,7 +63,7 @@ export interface SloConfig {
     errorRatePercent: number;
     windowMinutes: number;
 }
-export type ConfigHealthChecker = 'ts-coverage' | 'vitest-schema' | 'jest-schema' | 'husky-scripts' | 'package-scripts' | 'pyproject-schema' | 'mypy-config' | 'go-mod-imports' | 'golangci-config' | 'cargo-features' | 'clippy-config' | 'ci-commands' | 'build-artifacts' | 'otel-version' | 'build-tool';
+export type ConfigHealthChecker = 'ts-coverage' | 'vitest-schema' | 'jest-schema' | 'husky-scripts' | 'package-scripts' | 'pyproject-schema' | 'mypy-config' | 'go-mod-imports' | 'golangci-config' | 'cargo-features' | 'clippy-config' | 'ci-commands' | 'build-artifacts' | 'mcp-config' | 'otel-version' | 'build-tool';
 export interface ConfigHealthFinding {
     severity: 'error' | 'warning' | 'info';
     checker: ConfigHealthChecker;
@@ -72,6 +72,14 @@ export interface ConfigHealthFinding {
     message: string;
     fix: string;
 }
+export interface JsonMcpHealthEntry {
+    command?: string;
+    args?: string[];
+    startup_timeout_sec?: number;
+}
+export interface McpConfigCheckOptions {
+    homePath?: string;
+}
 export interface ConfigHealthReport {
     summary: {
         errors: number;
@@ -81,6 +89,6 @@ export interface ConfigHealthReport {
     findings: ConfigHealthFinding[];
     blocksDoR: boolean;
 }
-export type ConfigHealthCheckGroup = 'ts' | 'python' | 'go' | 'rust' | 'ci' | 'build-tool';
+export type ConfigHealthCheckGroup = 'ts' | 'python' | 'go' | 'rust' | 'ci' | 'build-tool' | 'mcp';
 export type ConfigHealthSeverityFilter = 'error' | 'warning' | 'info';
 //# sourceMappingURL=analysis-detection.d.ts.map

package/dist/types/auto-update.d.ts

@@ -3,6 +3,7 @@ export interface McpServerEntry {
     command?: string;
     args?: string[];
     env?: Record<string, string>;
+    startup_timeout_sec?: number;
 }
 export interface McpConfig {
     mcpServers?: Record<string, McpServerEntry>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.3.7",
+  "version": "4.3.8",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -32,14 +32,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.3.7",
-    "@planu/core-darwin-x64": "4.3.7",
-    "@planu/core-linux-arm64-gnu": "4.3.7",
-    "@planu/core-linux-arm64-musl": "4.3.7",
-    "@planu/core-linux-x64-gnu": "4.3.7",
-    "@planu/core-linux-x64-musl": "4.3.7",
-    "@planu/core-win32-arm64-msvc": "4.3.7",
-    "@planu/core-win32-x64-msvc": "4.3.7"
+    "@planu/core-darwin-arm64": "4.3.8",
+    "@planu/core-darwin-x64": "4.3.8",
+    "@planu/core-linux-arm64-gnu": "4.3.8",
+    "@planu/core-linux-arm64-musl": "4.3.8",
+    "@planu/core-linux-x64-gnu": "4.3.8",
+    "@planu/core-linux-x64-musl": "4.3.8",
+    "@planu/core-win32-arm64-msvc": "4.3.8",
+    "@planu/core-win32-x64-msvc": "4.3.8"
   },
   "engines": {
     "node": ">=24.0.0"