@selvakumaresra/specship 0.1.3 → 0.4.0

package/dist/mcp/designer-tools.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Designer MCP tools — claude.ai/design driving, vendored from @pro-vi/designer.
+ *
+ * These six tools merge the standalone `designer` MCP into SpecShip's surface
+ * so one `specship serve --mcp` exposes both the code-graph tools and the
+ * design loop:
+ *   - designer_session   — enter / inspect / transition a claude.ai/design session
+ *   - designer_prompt    — modify the design (returns a live URL to taste)
+ *   - designer_ask       — Q&A with the design assistant (no file change)
+ *   - designer_list      — list projects or files
+ *   - designer_snapshot  — capture the current file (paths + hash; optional HTML)
+ *   - designer_handoff   — fetch the export bundle → ./artifacts/<key>/handoff-<ts>/
+ *
+ * The heavy lifting lives in the vendored subtree under src/designer/ (compiled
+ * separately to dist/designer/ as CommonJS — see src/designer/tsconfig.json).
+ * We load it through a RUNTIME require so SpecShip's strict root tsc never has
+ * to type-check the foreign code. `DesignerController` holds a CDP connection to
+ * a debug Chrome; it is a per-process singleton (keyed by `key`) held here so
+ * the daemon shares one browser across MCP clients.
+ *
+ * Runtime requirements (inherited from designer, NOT vendored): the external
+ * `agent-browser` binary on PATH, and a one-time Chrome debug-profile + login
+ * (`designer setup`). Tools surface a clear error if the session isn't ready.
+ */
+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.designerToolDefinitions = void 0;
+exports.handleDesignerSession = handleDesignerSession;
+exports.handleDesignerPrompt = handleDesignerPrompt;
+exports.handleDesignerAsk = handleDesignerAsk;
+exports.handleDesignerList = handleDesignerList;
+exports.handleDesignerSnapshot = handleDesignerSnapshot;
+exports.handleDesignerHandoff = handleDesignerHandoff;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+// Lazy module handles + per-key controller cache (process singleton).
+let designerMod = null;
+let artifactStoreMod = null;
+const controllers = new Map();
+function loadDesignerModules() {
+    if (!designerMod || !artifactStoreMod) {
+        // Relative to the COMPILED location (dist/mcp/designer-tools.js → dist/designer/*).
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        designerMod = require('../designer/designer-controller');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        artifactStoreMod = require('../designer/artifact-store');
+    }
+    return { designer: designerMod, artifacts: artifactStoreMod };
+}
+function getController(key) {
+    const k = key || 'default';
+    let c = controllers.get(k);
+    if (!c) {
+        const { designer } = loadDesignerModules();
+        c = new designer.DesignerController({ key: k, headed: true });
+        controllers.set(k, c);
+    }
+    return c;
+}
+function ok(obj) {
+    return {
+        content: [{ type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2) }],
+    };
+}
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** Wrap a controller call so a not-ready session / missing agent-browser
+ *  surfaces as a clean tool error rather than an unhandled rejection. */
+async function guard(run) {
+    try {
+        return ok(await run());
+    }
+    catch (err) {
+        return fail(`designer: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function str(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+function num(v) {
+    return typeof v === 'number' ? v : undefined;
+}
+function bool(v) {
+    return typeof v === 'boolean' ? v : undefined;
+}
+// --- Handlers ----------------------------------------------------------------
+async function handleDesignerSession(args) {
+    const key = str(args.key);
+    const action = str(args.action) ?? 'status';
+    const name = str(args.name);
+    const fidelity = str(args.fidelity);
+    return guard(() => getController(key).session({ action, name, fidelity }));
+}
+async function handleDesignerPrompt(args) {
+    const prompt = str(args.prompt);
+    if (prompt === undefined)
+        return fail('designer_prompt: "prompt" (string) is required');
+    const key = str(args.key);
+    return guard(() => getController(key).iterate(prompt, {
+        file: str(args.file),
+        timeoutMs: num(args.timeoutMs),
+        stabilityMs: num(args.stabilityMs),
+        decisive: bool(args.decisive),
+    }));
+}
+async function handleDesignerAsk(args) {
+    const prompt = str(args.prompt);
+    if (prompt === undefined)
+        return fail('designer_ask: "prompt" (string) is required');
+    const key = str(args.key);
+    return guard(() => getController(key).ask(prompt, {
+        file: str(args.file),
+        timeoutMs: num(args.timeoutMs),
+        stabilityMs: num(args.stabilityMs),
+    }));
+}
+async function handleDesignerList(args) {
+    const scope = str(args.scope);
+    if (scope !== 'projects' && scope !== 'files') {
+        return fail('designer_list: "scope" must be "projects" or "files"');
+    }
+    const key = str(args.key);
+    return guard(async () => {
+        const c = getController(key);
+        if (scope === 'projects')
+            return c.listProjects();
+        const detail = await c.listFilesDetailed();
+        if (!detail.authoritative) {
+            return {
+                files: detail.files,
+                folders: detail.folders,
+                authoritative: false,
+                warning: 'This project has folders (' +
+                    detail.folders.join(', ') +
+                    '). Files under folders are not visible to the live file-list scrape. Call designer_handoff for an authoritative list.',
+            };
+        }
+        return { files: detail.files, authoritative: true };
+    });
+}
+async function handleDesignerSnapshot(args) {
+    const key = str(args.key);
+    const filename = str(args.filename);
+    const includeHtml = bool(args.includeHtml) ?? false;
+    const screenshot = bool(args.screenshot) ?? true;
+    return guard(async () => {
+        const { artifacts } = loadDesignerModules();
+        const c = getController(key);
+        if (filename) {
+            const swap = await c.openFile(filename);
+            if (!swap.ok)
+                return { ok: false, error: swap.error, file: filename };
+        }
+        const snap = await c.snapshotDesign({});
+        let htmlPath = null;
+        if (snap.html) {
+            htmlPath = path.join(artifacts.sessionDir(c.key), `snap-${Date.now()}.html`);
+            fs.writeFileSync(htmlPath, snap.html);
+        }
+        return {
+            ok: true,
+            file: filename || extractFileParamFromUrl(snap.url),
+            url: snap.url,
+            iframeSrc: snap.iframeSrc,
+            htmlPath,
+            screenshotPath: screenshot ? snap.screenshotPath : null,
+            htmlBytes: snap.html ? snap.html.length : 0,
+            html: includeHtml ? snap.html : undefined,
+        };
+    });
+}
+async function handleDesignerHandoff(args) {
+    const key = str(args.key);
+    const openFile = str(args.openFile);
+    return guard(() => getController(key).handoff({ openFile }));
+}
+function extractFileParamFromUrl(url) {
+    try {
+        return new URL(url).searchParams.get('file');
+    }
+    catch {
+        return null;
+    }
+}
+// --- Definitions -------------------------------------------------------------
+exports.designerToolDefinitions = [
+    {
+        name: 'designer_session',
+        description: "Enter, inspect, or transition a claude.ai/design session (drives a debug Chrome via CDP). action='status' (default) is a read-only orient — returns stored state + currentUrl + inSession + availableFiles. Other actions: ensure_ready (navigate to /design), resume (open the stored design URL), create (new project — requires name), adopt (bind an already-open /design/p/<uuid> tab), clear (dismiss interstitial overlays). Requires the agent-browser tool on PATH and a signed-in debug Chrome (one-time `designer setup`).",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Stable key for this loop (e.g. feature name). Defaults to "default".' },
+                action: {
+                    type: 'string',
+                    description: 'Default: status',
+                    enum: ['status', 'ensure_ready', 'resume', 'create', 'adopt', 'clear'],
+                },
+                name: { type: 'string', description: 'Required when action=create; optional label when action=adopt.' },
+                fidelity: {
+                    type: 'string',
+                    description: 'wireframe (default) or highfi — folded into the creation seed prompt.',
+                    enum: ['wireframe', 'highfi'],
+                },
+            },
+        },
+    },
+    {
+        name: 'designer_prompt',
+        description: "Modify the design. Sends a prompt expected to change the served HTML (e.g. 'create a login screen'). Waits for Claude Design's turn to complete, then returns slim metadata (NOT inline HTML). DEFAULT TASTE PATH: hand the human the returned `url` — it's the live, interactive claude.ai/design surface. Auto-appends a 'keep all files at project root, no subfolders' instruction.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Stable key for this loop. Defaults to "default".' },
+                prompt: { type: 'string', description: 'The instruction to send to Claude Design.' },
+                file: { type: 'string', description: 'Switch to this file before sending (targets the prompt at it).' },
+                timeoutMs: { type: 'number', description: 'Default 20m. Hi-fi generations can take 15+ min.' },
+                stabilityMs: { type: 'number', description: 'Default 4s.' },
+                decisive: {
+                    type: 'boolean',
+                    description: "Append a 'do not stop to ask clarifying questions' instruction.",
+                },
+            },
+            required: ['prompt'],
+        },
+    },
+    {
+        name: 'designer_ask',
+        description: "Q&A with the design assistant — text-only, changes no file. Use for 'why did you choose X?', 'compare A vs B', 'suggest 3 alternatives before I commit'. Returns the assistant's reply.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Stable key for this loop. Defaults to "default".' },
+                prompt: { type: 'string', description: 'The question to ask Claude Design.' },
+                file: { type: 'string', description: 'Switch to this file before asking (gives Claude context).' },
+                timeoutMs: { type: 'number', description: 'Default 5m.' },
+                stabilityMs: { type: 'number', description: 'Default 2.5s.' },
+            },
+            required: ['prompt'],
+        },
+    },
+    {
+        name: 'designer_list',
+        description: "Inventory. scope='projects' lists all your Claude design projects; scope='files' lists files in the currently-open project (flat-only — folder contents need designer_handoff). Usually unnecessary — designer_session already returns availableFiles.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Stable key for this loop. Defaults to "default".' },
+                scope: { type: 'string', description: 'projects or files', enum: ['projects', 'files'] },
+            },
+            required: ['scope'],
+        },
+    },
+    {
+        name: 'designer_snapshot',
+        description: "Inspect a file's current state. Switches to `filename` first if given. Default returns paths + hash only (HTML written to disk at htmlPath); set includeHtml=true to inline the HTML. Reads the real rendered HTML over CDP from inside the cross-origin preview iframe.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Stable key for this loop. Defaults to "default".' },
+                filename: { type: 'string', description: 'Switch to this file first. Omit to snapshot whatever is active.' },
+                includeHtml: { type: 'boolean', description: 'Default false.' },
+                screenshot: { type: 'boolean', description: 'Default true.' },
+            },
+        },
+    },
+    {
+        name: 'designer_handoff',
+        description: "Promote: fetch the project's export zip and extract it under ./artifacts/<key>/handoff-<ts>/project/, plus decision-record.md (the live chat transcript, verbatim). Call when the human says 'yes, that's it'. The bundle is what /ss-design-loop feeds to the claude-design-implement workflow.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Stable key for this loop. Defaults to "default".' },
+                openFile: { type: 'string', description: 'Set the open file before handoff.' },
+            },
+        },
+    },
+];
+//# sourceMappingURL=designer-tools.js.map

package/dist/mcp/designer-tools.js.map

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

package/dist/mcp/engine.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link SpecShip} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+import { ToolHandler } from './tools';
+export interface MCPEngineOptions {
+    /**
+     * Whether to start the file watcher when initializing. Daemon and direct
+     * modes both want this true; tests may set it false to keep the engine
+     * cheap. Honors {@link watchDisabledReason} regardless.
+     */
+    watch?: boolean;
+}
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+export declare class MCPEngine {
+    private cg;
+    private toolHandler;
+    private projectPath;
+    private initPromise;
+    private watcherStarted;
+    private opts;
+    private closed;
+    constructor(opts?: MCPEngineOptions);
+    /**
+     * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+     * project path (from the `--path` CLI flag) without yet opening it. This
+     * keeps the synchronous constructor cheap; the actual open happens on the
+     * first `ensureInitialized` call.
+     */
+    setProjectPathHint(projectPath: string): void;
+    /** Project root that the engine resolved on first init (null if none). */
+    getProjectPath(): string | null;
+    /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+    getToolHandler(): ToolHandler;
+    /** Whether the default project's SpecShip is open. */
+    hasDefaultSpecShip(): boolean;
+    /**
+     * Walk up from `searchFrom` to find the nearest `.specship/` and open it.
+     * Idempotent: concurrent callers share one in-flight init; subsequent
+     * callers after success are no-ops.
+     *
+     * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+     * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+     * search misses (just leaves `cg` null so the next call can retry).
+     */
+    ensureInitialized(searchFrom: string): Promise<void>;
+    /**
+     * Synchronous last-resort init used by the per-session retry loop when the
+     * background `ensureInitialized` already finished (or failed) and we need
+     * to pick up a project that appeared *after* the engine started.
+     */
+    retryInitializeSync(searchFrom: string): void;
+    /**
+     * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+     * and on direct-mode stop. Idempotent.
+     */
+    stop(): void;
+    private doInitialize;
+    /**
+     * Start file watching on the active SpecShip instance. Idempotent — the
+     * watcher is per-engine, not per-session, which is why the daemon path
+     * collapses N inotify sets to one. The wording of the disabled-reason log
+     * exactly matches the prior in-tree implementation so log-driven dashboards
+     * keep working.
+     */
+    private startWatching;
+    /**
+     * Reconcile the index with the current filesystem once, right after open —
+     * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+     * no watcher was running. Runs in the background, but the returned promise
+     * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+     * call awaits completion before serving (without this, a tool call that
+     * races past sync returns rows for files that no longer exist on disk —
+     * and the per-file staleness banner can't help because `getPendingFiles()`
+     * is populated by the watcher, not by catch-up).
+     */
+    private catchUpSync;
+}
+/**
+ * Parse and clamp the SPECSHIP_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+export declare function parseDebounceEnv(raw: string | undefined): number | undefined;
+//# sourceMappingURL=engine.d.ts.map

package/dist/mcp/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/mcp/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAWtC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,WAAW,CAAc;IAIjC,OAAO,CAAC,WAAW,CAAuB;IAE1C,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,GAAE,gBAAqB;IAKvC;;;;;OAKG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAK7C,0EAA0E;IAC1E,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,yEAAyE;IACzE,cAAc,IAAI,WAAW;IAI7B,sDAAsD;IACtD,kBAAkB,IAAI,OAAO;IAI7B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D;;;;OAIG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAsB7C;;;OAGG;IACH,IAAI,IAAI,IAAI;YAUE,YAAY;IAsB1B;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IA+CrB;;;;;;;;;OASG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAM5E"}