peaks-cli 1.0.12 → 1.0.13

package/dist/src/services/dashboard/project-dashboard-service.d.ts

@@ -0,0 +1,64 @@
+import { type RequestArtifactRole, type RequestArtifactSummary } from '../artifacts/request-artifact-service.js';
+import type { OpenSpecChangeSummary } from '../openspec/openspec-types.js';
+import type { McpScanReport } from '../mcp/mcp-types.js';
+import type { CapabilityItem } from '../recommendations/recommendation-types.js';
+export type ProjectDashboardRequests = {
+    count: number;
+    byRole: Record<RequestArtifactRole, RequestArtifactSummary[]>;
+    byState: Record<string, number>;
+};
+export type ProjectDashboardOpenSpec = {
+    exists: boolean;
+    count: number;
+    changes: OpenSpecChangeSummary[];
+};
+export type ProjectDashboardUnderstand = {
+    exists: boolean;
+    graphExists: boolean;
+    graphPath: string;
+    parseError?: string;
+};
+export type ProjectDashboardMcp = {
+    servers: McpScanReport['servers'];
+    scopes: McpScanReport['scopes'];
+};
+export type ProjectDashboardDoctor = {
+    ok: boolean;
+    passed: number;
+    failed: number;
+};
+export type ProjectDashboardRunbookHealth = {
+    ok: boolean;
+    required: number;
+    healthy: number;
+    missingRunbook: string[];
+    applyNoteFailed: string[];
+};
+export type ProjectDashboardCapabilities = {
+    count: number;
+    mcpCount: number;
+    sample: Array<Pick<CapabilityItem, 'capabilityId' | 'name' | 'itemType' | 'category'>>;
+};
+export type ProjectDashboard = {
+    generatedAt: string;
+    projectRoot: string;
+    requests: ProjectDashboardRequests;
+    openspec: ProjectDashboardOpenSpec;
+    understand: ProjectDashboardUnderstand;
+    mcp: ProjectDashboardMcp;
+    doctor: ProjectDashboardDoctor;
+    runbookHealth: ProjectDashboardRunbookHealth;
+    capabilities: ProjectDashboardCapabilities;
+};
+export type LoadProjectDashboardOptions = {
+    projectRoot: string;
+    sampleCapabilities?: number;
+    clock?: () => string;
+    doctorReport?: {
+        ok: boolean;
+        passed: number;
+        failed: number;
+    };
+    runbookHealth?: ProjectDashboardRunbookHealth;
+};
+export declare function loadProjectDashboard(options: LoadProjectDashboardOptions): Promise<ProjectDashboard>;

package/dist/src/services/dashboard/project-dashboard-service.js

@@ -0,0 +1,112 @@
+import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
+import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
+import { scanMcpServers } from '../mcp/mcp-scan-service.js';
+import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
+import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
+import { requiredSkillNames } from '../../shared/paths.js';
+function defaultClock() {
+    return new Date().toISOString();
+}
+function groupRequestsByRole(items) {
+    const byRole = { prd: [], ui: [], rd: [], qa: [] };
+    for (const item of items) {
+        byRole[item.role].push(item);
+    }
+    return byRole;
+}
+function countRequestsByState(items) {
+    const counts = {};
+    for (const item of items) {
+        counts[item.state] = (counts[item.state] ?? 0) + 1;
+    }
+    return counts;
+}
+async function loadDoctorAndRunbookHealth(doctorOverride, runbookOverride) {
+    if (doctorOverride !== undefined && runbookOverride !== undefined) {
+        return { doctor: doctorOverride, runbookHealth: runbookOverride };
+    }
+    if (doctorOverride !== undefined) {
+        return {
+            doctor: doctorOverride,
+            runbookHealth: { ok: true, required: 0, healthy: 0, missingRunbook: [], applyNoteFailed: [] }
+        };
+    }
+    const { runDoctor } = await import('../doctor/doctor-service.js');
+    const report = await runDoctor();
+    return {
+        doctor: { ok: report.summary.ok, passed: report.summary.passed, failed: report.summary.failed },
+        runbookHealth: runbookOverride ?? summarizeRunbookHealth(report.checks)
+    };
+}
+function summarizeRunbookHealth(checks) {
+    const missingRunbook = [];
+    const applyNoteFailed = [];
+    for (const check of checks) {
+        if (!check.ok && check.id.startsWith('skill-runbook:')) {
+            missingRunbook.push(check.id.slice('skill-runbook:'.length));
+        }
+        if (!check.ok && check.id.startsWith('skill-apply-note:')) {
+            applyNoteFailed.push(check.id.slice('skill-apply-note:'.length));
+        }
+    }
+    const required = requiredSkillNames.length;
+    const healthy = Math.max(0, required - missingRunbook.length - applyNoteFailed.length);
+    return {
+        ok: missingRunbook.length === 0 && applyNoteFailed.length === 0,
+        required,
+        healthy,
+        missingRunbook,
+        applyNoteFailed
+    };
+}
+function buildCapabilitiesSummary(sampleSize) {
+    const items = seedCapabilityItems;
+    return {
+        count: items.length,
+        mcpCount: items.filter((item) => item.itemType === 'mcp').length,
+        sample: items.slice(0, sampleSize).map((item) => ({
+            capabilityId: item.capabilityId,
+            name: item.name,
+            itemType: item.itemType,
+            category: item.category
+        }))
+    };
+}
+export async function loadProjectDashboard(options) {
+    const clock = options.clock ?? defaultClock;
+    const sampleSize = options.sampleCapabilities ?? 8;
+    const [items, openspecReport, mcpReport, understandReport, doctorAndRunbook] = await Promise.all([
+        listRequestArtifacts({ projectRoot: options.projectRoot }),
+        scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
+        scanMcpServers({ projectRoot: options.projectRoot }),
+        scanUnderstandAnything({ projectRoot: options.projectRoot }),
+        loadDoctorAndRunbookHealth(options.doctorReport, options.runbookHealth)
+    ]);
+    return {
+        generatedAt: clock(),
+        projectRoot: options.projectRoot,
+        requests: {
+            count: items.length,
+            byRole: groupRequestsByRole(items),
+            byState: countRequestsByState(items)
+        },
+        openspec: {
+            exists: openspecReport.exists,
+            count: openspecReport.changes.length,
+            changes: openspecReport.changes
+        },
+        understand: {
+            exists: understandReport.exists,
+            graphExists: understandReport.graph.exists,
+            graphPath: understandReport.graph.path,
+            ...(understandReport.graph.parseError !== undefined ? { parseError: understandReport.graph.parseError } : {})
+        },
+        mcp: {
+            servers: mcpReport.servers,
+            scopes: mcpReport.scopes
+        },
+        doctor: doctorAndRunbook.doctor,
+        runbookHealth: doctorAndRunbook.runbookHealth,
+        capabilities: buildCapabilitiesSummary(sampleSize)
+    };
+}

package/dist/src/services/doctor/doctor-service.d.ts

@@ -11,8 +11,15 @@ export type DoctorReport = {
         failed: number;
     };
 };
+export type CodegraphCapabilityProbe = {
+    packagePath: string;
+    version: string;
+    binaryPath: string;
+    binaryExists: boolean;
+};
 export type DoctorOptions = {
     schemasBaseDir?: string;
     skillsBaseDir?: string;
+    codegraphProbe?: () => CodegraphCapabilityProbe;
 };
 export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

package/dist/src/services/doctor/doctor-service.js

@@ -1,10 +1,41 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve as resolvePath } from 'node:path';
 import { readText } from '../../shared/fs.js';
 import { requiredSchemaFiles, requiredSkillNames, schemasDir } from '../../shared/paths.js';
 import { getErrorMessage } from '../../shared/result.js';
 import { loadSkillRegistry } from '../skills/skill-registry.js';
+const CODEGRAPH_EXPECTED_VERSION = '0.7.10';
+function defaultCodegraphProbe() {
+    const require = createRequire(import.meta.url);
+    const packagePath = require.resolve('@colbymchenry/codegraph/package.json');
+    const pkg = require(packagePath);
+    const binaryPath = resolvePath(dirname(packagePath), 'dist', 'bin', 'codegraph.js');
+    return {
+        packagePath,
+        version: pkg.version ?? 'unknown',
+        binaryPath,
+        binaryExists: existsSync(binaryPath)
+    };
+}
+const DESTRUCTIVE_APPLY_PATTERNS = [
+    /peaks\s+memory\s+sync[^\n]*--apply/,
+    /peaks\s+memory\s+extract[^\n]*--apply/,
+    /peaks\s+artifacts\s+sync[^\n]*--apply/,
+    /peaks\s+openspec\s+archive[^\n]*--apply/,
+    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/
+];
+const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
+function extractRunbookSection(body) {
+    const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
+    return match === null ? null : (match[1] ?? null);
+}
+function findDestructiveApplyLines(section) {
+    const lines = section.split(/\r?\n/);
+    return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
+}
 export async function runDoctor(options = {}) {
     const checks = [];
     const registry = await loadSkillRegistry(options.skillsBaseDir);
@@ -35,6 +66,51 @@ export async function runDoctor(options = {}) {
             message: `Skill ${failure.directory} has invalid metadata: ${failure.message}`
         });
     }
+    const requiredSkillNameSet = new Set(requiredSkillNames);
+    for (const skill of skills) {
+        if (!requiredSkillNameSet.has(skill.name)) {
+            continue;
+        }
+        try {
+            const body = await readText(skill.skillPath);
+            const hasRunbook = /## Default runbook\s/.test(body);
+            checks.push({
+                id: `skill-runbook:${skill.name}`,
+                ok: hasRunbook,
+                message: hasRunbook
+                    ? `Skill ${skill.name} declares a Default runbook`
+                    : `Skill ${skill.name} is missing a ## Default runbook section`
+            });
+            const runbookSection = extractRunbookSection(body);
+            if (runbookSection !== null) {
+                const destructiveLines = findDestructiveApplyLines(runbookSection);
+                if (destructiveLines.length === 0) {
+                    checks.push({
+                        id: `skill-apply-note:${skill.name}`,
+                        ok: true,
+                        message: `Skill ${skill.name} runbook has no destructive --apply commands to gate`
+                    });
+                }
+                else {
+                    const hasAuthorizationNote = AUTHORIZATION_KEYWORDS_PATTERN.test(runbookSection);
+                    checks.push({
+                        id: `skill-apply-note:${skill.name}`,
+                        ok: hasAuthorizationNote,
+                        message: hasAuthorizationNote
+                            ? `Skill ${skill.name} gates ${destructiveLines.length} destructive --apply command(s) with an authorization note`
+                            : `Skill ${skill.name} has ${destructiveLines.length} destructive --apply command(s) without an authorization/dry-run note in the runbook section`
+                    });
+                }
+            }
+        }
+        catch (error) {
+            checks.push({
+                id: `skill-runbook:${skill.name}`,
+                ok: false,
+                message: `Skill ${skill.name} runbook check failed: ${getErrorMessage(error)}`
+            });
+        }
+    }
     const schemaRoot = options.schemasBaseDir ?? schemasDir;
     for (const schemaFile of requiredSchemaFiles) {
         try {
@@ -56,6 +132,69 @@ export async function runDoctor(options = {}) {
         ok: true,
         message: hasUserConfig ? 'User config exists at ~/.peaks/config.json' : 'Optional user config not found at ~/.peaks/config.json'
     });
+    const probe = options.codegraphProbe ?? defaultCodegraphProbe;
+    try {
+        const result = probe();
+        const versionOk = result.version === CODEGRAPH_EXPECTED_VERSION;
+        if (!versionOk) {
+            checks.push({
+                id: 'capability:codegraph',
+                ok: false,
+                message: `@colbymchenry/codegraph version mismatch: expected ${CODEGRAPH_EXPECTED_VERSION}, resolved ${result.version} at ${result.packagePath}`
+            });
+        }
+        else if (!result.binaryExists) {
+            checks.push({
+                id: 'capability:codegraph',
+                ok: false,
+                message: `@colbymchenry/codegraph@${result.version} resolved at ${result.packagePath} but binary is missing at ${result.binaryPath}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'capability:codegraph',
+                ok: true,
+                message: `@colbymchenry/codegraph@${result.version} resolves with binary at ${result.binaryPath}`
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'capability:codegraph',
+            ok: false,
+            message: `@colbymchenry/codegraph not resolvable: ${getErrorMessage(error)}`
+        });
+    }
+    try {
+        const schemaText = await readText(join(schemaRoot, 'doctor-report.schema.json'));
+        const schema = JSON.parse(schemaText);
+        const patternSource = schema.properties?.checks?.items?.properties?.id?.pattern;
+        if (typeof patternSource === 'string') {
+            const pattern = new RegExp(patternSource);
+            const mismatches = checks.filter((check) => !pattern.test(check.id)).map((check) => check.id);
+            checks.push({
+                id: 'doctor-self:check-id-pattern',
+                ok: mismatches.length === 0,
+                message: mismatches.length === 0
+                    ? 'All doctor check IDs match the doctor-report schema pattern'
+                    : `Doctor check IDs missing from schema pattern: ${mismatches.join(', ')}`
+            });
+        }
+        else {
+            checks.push({
+                id: 'doctor-self:check-id-pattern',
+                ok: false,
+                message: 'doctor-report.schema.json does not declare a check.id pattern'
+            });
+        }
+    }
+    catch (error) {
+        checks.push({
+            id: 'doctor-self:check-id-pattern',
+            ok: false,
+            message: `Failed to load doctor-report.schema.json for self-validation: ${getErrorMessage(error)}`
+        });
+    }
     const failed = checks.filter((check) => !check.ok).length;
     return {
         checks,

package/dist/src/services/mcp/mcp-apply-service.d.ts

@@ -0,0 +1,31 @@
+import { type PlanMcpInstallOptions, type McpInstallEnvCheck } from './mcp-plan-service.js';
+export type McpApplyAction = 'add' | 'update' | 'claimed' | 'noop';
+export type McpApplyBackupInfo = {
+    path: string | null;
+    skipped: boolean;
+};
+export type McpApplyResult = {
+    capabilityId: string;
+    action: McpApplyAction;
+    backup: McpApplyBackupInfo;
+    written: {
+        settingsPath: string;
+        managedMarkerPath: string;
+    };
+    envCheck: McpInstallEnvCheck;
+};
+export type McpApplyOptions = PlanMcpInstallOptions & {
+    claim?: boolean;
+    backupRoot?: string;
+    clock?: () => string;
+};
+export type McpRollbackOptions = {
+    backupPath: string;
+    globalSettingsPath?: string;
+};
+export type McpRollbackResult = {
+    restoredFrom: string;
+    restoredTo: string;
+};
+export declare function applyMcpInstall(capabilityId: string, options?: McpApplyOptions): Promise<McpApplyResult>;
+export declare function rollbackMcpInstall(options: McpRollbackOptions): Promise<McpRollbackResult>;

package/dist/src/services/mcp/mcp-apply-service.js

@@ -0,0 +1,112 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { pathExists, readText } from '../../shared/fs.js';
+import { planMcpInstall } from './mcp-plan-service.js';
+function defaultGlobalSettingsPath() {
+    return join(homedir(), '.claude', 'settings.json');
+}
+function defaultManagedMarkerPath() {
+    return join(homedir(), '.peaks', 'mcp-managed.json');
+}
+function defaultBackupRoot() {
+    return join(homedir(), '.peaks-artifacts', 'mcp-backups');
+}
+function defaultClock() {
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+async function readJsonFile(path) {
+    if (!(await pathExists(path))) {
+        return {};
+    }
+    const raw = await readText(path);
+    if (raw.length === 0) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {};
+    }
+    return parsed;
+}
+async function writeJsonFile(path, data) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+function buildServerConfig(spec) {
+    const env = {};
+    for (const key of spec.envKeys) {
+        env[key] = `\${${key}}`;
+    }
+    return { command: spec.command, args: [...spec.args], env };
+}
+async function createBackup(settingsPath, backupRoot, timestamp) {
+    if (!(await pathExists(settingsPath))) {
+        return null;
+    }
+    const backupPath = join(backupRoot, timestamp, 'settings.json');
+    await mkdir(dirname(backupPath), { recursive: true });
+    await writeFile(backupPath, await readText(settingsPath), 'utf8');
+    return backupPath;
+}
+async function updateManagedMarker(markerPath, name) {
+    const marker = await readJsonFile(markerPath);
+    const existing = Array.isArray(marker.servers)
+        ? marker.servers.filter((entry) => typeof entry === 'string')
+        : [];
+    if (!existing.includes(name)) {
+        existing.push(name);
+    }
+    await writeJsonFile(markerPath, { ...marker, servers: existing });
+}
+export async function applyMcpInstall(capabilityId, options = {}) {
+    const plan = await planMcpInstall(capabilityId, options);
+    if (plan.action === 'unknown-capability' || plan.spec === null) {
+        throw new Error(`No MCP install spec registered for capability ${capabilityId} (unknown-capability)`);
+    }
+    if (plan.envCheck.missing.length > 0) {
+        throw new Error(`Refusing to apply: missing required env vars: ${plan.envCheck.missing.join(', ')}`);
+    }
+    if (plan.action === 'conflict' && options.claim !== true) {
+        throw new Error(`Refusing to apply: server ${plan.spec.name} exists but is not peaks-managed (conflict). Re-run with --claim to take ownership.`);
+    }
+    const settingsPath = options.globalSettingsPath ?? defaultGlobalSettingsPath();
+    const markerPath = options.managedMarkerPath ?? defaultManagedMarkerPath();
+    const backupRoot = options.backupRoot ?? defaultBackupRoot();
+    const clock = options.clock ?? defaultClock;
+    if (plan.action === 'noop') {
+        return {
+            capabilityId,
+            action: 'noop',
+            backup: { path: null, skipped: true },
+            written: { settingsPath, managedMarkerPath: markerPath },
+            envCheck: plan.envCheck
+        };
+    }
+    const backupPath = await createBackup(settingsPath, backupRoot, clock());
+    const settings = await readJsonFile(settingsPath);
+    const existingServers = settings.mcpServers !== null && typeof settings.mcpServers === 'object' && !Array.isArray(settings.mcpServers)
+        ? settings.mcpServers
+        : {};
+    const nextServers = { ...existingServers, [plan.spec.name]: buildServerConfig(plan.spec) };
+    await writeJsonFile(settingsPath, { ...settings, mcpServers: nextServers });
+    await updateManagedMarker(markerPath, plan.spec.name);
+    const action = plan.action === 'conflict' ? 'claimed' : plan.action;
+    return {
+        capabilityId,
+        action,
+        backup: { path: backupPath, skipped: false },
+        written: { settingsPath, managedMarkerPath: markerPath },
+        envCheck: plan.envCheck
+    };
+}
+export async function rollbackMcpInstall(options) {
+    if (!(await pathExists(options.backupPath))) {
+        throw new Error(`Refusing to rollback: backup file not found at ${options.backupPath}`);
+    }
+    const target = options.globalSettingsPath ?? defaultGlobalSettingsPath();
+    const content = await readText(options.backupPath);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content, 'utf8');
+    return { restoredFrom: options.backupPath, restoredTo: target };
+}

package/dist/src/services/mcp/mcp-call-service.d.ts

@@ -0,0 +1,17 @@
+import { type McpInstallSpec } from './mcp-install-registry.js';
+import { type McpClientTransport } from './mcp-client-service.js';
+export type McpCallTransportFactory = (spec: McpInstallSpec, env: Record<string, string | undefined>) => McpClientTransport;
+export type McpCallOptions = {
+    capabilityId: string;
+    toolName: string;
+    transportFactory: McpCallTransportFactory;
+    args?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+};
+export type McpCallResult = {
+    capabilityId: string;
+    toolName: string;
+    result: unknown;
+};
+export declare function callMcpTool(options: McpCallOptions): Promise<McpCallResult>;

package/dist/src/services/mcp/mcp-call-service.js

@@ -0,0 +1,34 @@
+import { findMcpInstallSpec } from './mcp-install-registry.js';
+import { createMcpClient } from './mcp-client-service.js';
+function checkRequiredEnv(spec, env) {
+    return spec.envKeys.filter((key) => {
+        const value = env[key];
+        return value === undefined || value.length === 0;
+    });
+}
+export async function callMcpTool(options) {
+    const spec = findMcpInstallSpec(options.capabilityId);
+    if (spec === null) {
+        throw new Error(`No MCP install spec registered for capability ${options.capabilityId}`);
+    }
+    const env = options.env ?? process.env;
+    const missing = checkRequiredEnv(spec, env);
+    if (missing.length > 0) {
+        throw new Error(`Refusing to call ${spec.name}: missing required env vars: ${missing.join(', ')}`);
+    }
+    const transport = options.transportFactory(spec, env);
+    const clientOptions = options.timeoutMs !== undefined
+        ? { transport, timeoutMs: options.timeoutMs }
+        : { transport };
+    const client = createMcpClient(clientOptions);
+    try {
+        const result = await client.request('tools/call', {
+            name: options.toolName,
+            arguments: options.args ?? {}
+        });
+        return { capabilityId: options.capabilityId, toolName: options.toolName, result };
+    }
+    finally {
+        await client.close();
+    }
+}

package/dist/src/services/mcp/mcp-client-service.d.ts

@@ -0,0 +1,14 @@
+export type McpClientTransport = {
+    send: (line: string) => Promise<void>;
+    onLine: (handler: (line: string) => void) => void;
+    close: () => Promise<void>;
+};
+export type McpClientOptions = {
+    transport: McpClientTransport;
+    timeoutMs?: number;
+};
+export type McpClientHandle = {
+    request: (method: string, params?: unknown) => Promise<unknown>;
+    close: () => Promise<void>;
+};
+export declare function createMcpClient(options: McpClientOptions): McpClientHandle;

package/dist/src/services/mcp/mcp-client-service.js

@@ -0,0 +1,49 @@
+import { buildRequest, parseMessages, serializeMessage } from './mcp-protocol.js';
+const DEFAULT_TIMEOUT_MS = 30000;
+export function createMcpClient(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let nextId = 1;
+    let buffer = '';
+    const pending = new Map();
+    function deliver(message) {
+        const entry = pending.get(message.id);
+        if (entry === undefined) {
+            return;
+        }
+        pending.delete(message.id);
+        clearTimeout(entry.timer);
+        if (message.error !== undefined) {
+            entry.reject(new Error(`MCP error ${message.error.code}: ${message.error.message}`));
+            return;
+        }
+        entry.resolve(message.result);
+    }
+    options.transport.onLine((line) => {
+        buffer += line;
+        const { messages, remainder } = parseMessages(buffer);
+        buffer = remainder;
+        for (const message of messages) {
+            deliver(message);
+        }
+    });
+    async function request(method, params) {
+        const id = nextId++;
+        const message = serializeMessage(buildRequest(id, method, params));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new Error(`MCP request ${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            pending.set(id, { resolve, reject, timer });
+            options.transport.send(message).catch((error) => {
+                clearTimeout(timer);
+                pending.delete(id);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
+    async function close() {
+        await options.transport.close();
+    }
+    return { request, close };
+}

package/dist/src/services/mcp/mcp-install-registry.d.ts

@@ -0,0 +1,11 @@
+import type { McpServerScope } from './mcp-types.js';
+export type McpInstallSpec = {
+    capabilityId: string;
+    name: string;
+    scope: McpServerScope;
+    command: string;
+    args: string[];
+    envKeys: string[];
+};
+export declare const seedMcpInstalls: ReadonlyArray<McpInstallSpec>;
+export declare function findMcpInstallSpec(capabilityId: string): McpInstallSpec | null;

package/dist/src/services/mcp/mcp-install-registry.js

@@ -0,0 +1,38 @@
+export const seedMcpInstalls = [
+    {
+        capabilityId: 'context7.docs-lookup',
+        name: 'context7',
+        scope: 'global',
+        command: 'npx',
+        args: ['-y', '@upstash/context7-mcp@latest'],
+        envKeys: ['CONTEXT7_API_KEY']
+    },
+    {
+        capabilityId: 'playwright-mcp.browser-validation',
+        name: 'playwright',
+        scope: 'global',
+        command: 'npx',
+        args: ['-y', '@playwright/mcp@latest'],
+        envKeys: []
+    },
+    {
+        capabilityId: 'chrome-devtools-mcp.browser-debug',
+        name: 'chrome-devtools',
+        scope: 'global',
+        command: 'npx',
+        args: ['-y', 'chrome-devtools-mcp@latest'],
+        envKeys: []
+    },
+    {
+        capabilityId: 'figma-context-mcp.design-context',
+        name: 'figma',
+        scope: 'global',
+        command: 'npx',
+        args: ['-y', 'figma-developer-mcp@latest', '--stdio'],
+        envKeys: ['FIGMA_API_KEY']
+    }
+];
+export function findMcpInstallSpec(capabilityId) {
+    const match = seedMcpInstalls.find((spec) => spec.capabilityId === capabilityId);
+    return match ?? null;
+}