peaks-cli 1.0.12 → 1.0.13

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

@@ -0,0 +1,29 @@
+import { type McpScanOptions } from './mcp-scan-service.js';
+import { type McpInstallSpec } from './mcp-install-registry.js';
+import type { McpServerConfig } from './mcp-types.js';
+export type McpInstallAction = 'add' | 'update' | 'noop' | 'conflict' | 'unknown-capability';
+export type McpInstallEnvCheck = {
+    missing: string[];
+};
+export type McpInstallDiffEntry<T> = {
+    before: T;
+    after: T;
+};
+export type McpInstallDiff = {
+    command?: McpInstallDiffEntry<string>;
+    args?: McpInstallDiffEntry<string[]>;
+    envKeys?: McpInstallDiffEntry<string[]>;
+};
+export type McpInstallPlan = {
+    capabilityId: string;
+    action: McpInstallAction;
+    spec: McpInstallSpec | null;
+    current: McpServerConfig | null;
+    envCheck: McpInstallEnvCheck;
+    diff: McpInstallDiff | null;
+    nextActions: string[];
+};
+export type PlanMcpInstallOptions = McpScanOptions & {
+    env?: Record<string, string | undefined>;
+};
+export declare function planMcpInstall(capabilityId: string, options?: PlanMcpInstallOptions): Promise<McpInstallPlan>;

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

@@ -0,0 +1,109 @@
+import { scanMcpServers } from './mcp-scan-service.js';
+import { findMcpInstallSpec } from './mcp-install-registry.js';
+function arraysEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    return a.every((value, index) => value === b[index]);
+}
+function buildEnvCheck(spec, env) {
+    const missing = spec.envKeys.filter((key) => {
+        const value = env[key];
+        return value === undefined || value.length === 0;
+    });
+    return { missing };
+}
+function buildDiff(spec, current) {
+    const diff = {};
+    if (current.command !== spec.command) {
+        diff.command = { before: current.command, after: spec.command };
+    }
+    if (!arraysEqual(current.args, spec.args)) {
+        diff.args = { before: current.args, after: spec.args };
+    }
+    if (!arraysEqual(current.envKeys, spec.envKeys)) {
+        diff.envKeys = { before: current.envKeys, after: spec.envKeys };
+    }
+    return Object.keys(diff).length === 0 ? null : diff;
+}
+function buildNextActions(action, capabilityId, envMissing) {
+    const actions = [];
+    if (action === 'unknown-capability') {
+        actions.push(`No MCP install spec registered for capability ${capabilityId}`);
+        return actions;
+    }
+    if (envMissing.length > 0) {
+        actions.push(`Set required env vars before apply: ${envMissing.join(', ')}`);
+    }
+    if (action === 'add') {
+        actions.push(`Run peaks mcp apply --capability ${capabilityId} --yes to write the new server`);
+    }
+    else if (action === 'update') {
+        actions.push(`Run peaks mcp apply --capability ${capabilityId} --yes to update the existing peaks-managed server`);
+    }
+    else if (action === 'conflict') {
+        actions.push(`Re-run with --claim to take ownership of the existing non-peaks-managed entry, or rename the conflicting server`);
+    }
+    else if (action === 'noop') {
+        actions.push(`Server already matches the install spec; nothing to apply`);
+    }
+    return actions;
+}
+export async function planMcpInstall(capabilityId, options = {}) {
+    const spec = findMcpInstallSpec(capabilityId);
+    if (spec === null) {
+        return {
+            capabilityId,
+            action: 'unknown-capability',
+            spec: null,
+            current: null,
+            envCheck: { missing: [] },
+            diff: null,
+            nextActions: buildNextActions('unknown-capability', capabilityId, [])
+        };
+    }
+    const env = options.env ?? process.env;
+    const envCheck = buildEnvCheck(spec, env);
+    const scanOptions = {};
+    if (options.globalSettingsPath !== undefined) {
+        scanOptions.globalSettingsPath = options.globalSettingsPath;
+    }
+    if (options.projectRoot !== undefined) {
+        scanOptions.projectRoot = options.projectRoot;
+    }
+    if (options.managedMarkerPath !== undefined) {
+        scanOptions.managedMarkerPath = options.managedMarkerPath;
+    }
+    if (options.pluginsRegistryPath !== undefined) {
+        scanOptions.pluginsRegistryPath = options.pluginsRegistryPath;
+    }
+    const report = await scanMcpServers(scanOptions);
+    const current = report.servers.find((server) => server.name === spec.name && server.scope === spec.scope) ?? null;
+    const pluginDuplicate = report.servers.find((server) => server.source === 'plugin' && server.name === spec.name) ?? null;
+    let action;
+    let diff = null;
+    if (current === null) {
+        action = 'add';
+    }
+    else if (current.source !== 'peaks') {
+        action = 'conflict';
+    }
+    else {
+        diff = buildDiff(spec, current);
+        action = diff === null ? 'noop' : 'update';
+    }
+    const nextActions = buildNextActions(action, capabilityId, envCheck.missing);
+    if (pluginDuplicate !== null) {
+        const pluginLabel = pluginDuplicate.pluginName ?? 'a Claude Code plugin';
+        nextActions.push(`An MCP server named "${spec.name}" is already loaded by plugin ${pluginLabel}; installing via peaks would duplicate it`);
+    }
+    return {
+        capabilityId,
+        action,
+        spec,
+        current,
+        envCheck,
+        diff,
+        nextActions
+    };
+}

package/dist/src/services/mcp/mcp-protocol.d.ts

@@ -0,0 +1,24 @@
+export type McpJsonRpcRequest = {
+    jsonrpc: '2.0';
+    id: number;
+    method: string;
+    params?: unknown;
+};
+export type McpJsonRpcError = {
+    code: number;
+    message: string;
+    data?: unknown;
+};
+export type McpJsonRpcResponse = {
+    jsonrpc: '2.0';
+    id: number;
+    result?: unknown;
+    error?: McpJsonRpcError;
+};
+export type ParsedMessages = {
+    messages: McpJsonRpcResponse[];
+    remainder: string;
+};
+export declare function buildRequest(id: number, method: string, params?: unknown): McpJsonRpcRequest;
+export declare function serializeMessage(message: McpJsonRpcRequest | McpJsonRpcResponse): string;
+export declare function parseMessages(buffer: string): ParsedMessages;

package/dist/src/services/mcp/mcp-protocol.js

@@ -0,0 +1,41 @@
+export function buildRequest(id, method, params) {
+    if (params === undefined) {
+        return { jsonrpc: '2.0', id, method };
+    }
+    return { jsonrpc: '2.0', id, method, params };
+}
+export function serializeMessage(message) {
+    return `${JSON.stringify(message)}\n`;
+}
+function isJsonRpcResponse(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    if (record.jsonrpc !== '2.0') {
+        return false;
+    }
+    return typeof record.id === 'number';
+}
+export function parseMessages(buffer) {
+    const lastNewline = buffer.lastIndexOf('\n');
+    const remainder = lastNewline === -1 ? buffer : buffer.slice(lastNewline + 1);
+    const completePart = lastNewline === -1 ? '' : buffer.slice(0, lastNewline);
+    const messages = [];
+    for (const line of completePart.split('\n')) {
+        if (line.length === 0) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (isJsonRpcResponse(parsed)) {
+            messages.push(parsed);
+        }
+    }
+    return { messages, remainder };
+}

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

@@ -0,0 +1,8 @@
+import type { McpScanReport } from './mcp-types.js';
+export type McpScanOptions = {
+    globalSettingsPath?: string;
+    projectRoot?: string;
+    managedMarkerPath?: string;
+    pluginsRegistryPath?: string;
+};
+export declare function scanMcpServers(options?: McpScanOptions): Promise<McpScanReport>;

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

@@ -0,0 +1,214 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathExists, readText } from '../../shared/fs.js';
+import { getErrorMessage } from '../../shared/result.js';
+function defaultGlobalSettingsPath() {
+    return join(homedir(), '.claude', 'settings.json');
+}
+function defaultManagedMarkerPath() {
+    return join(homedir(), '.peaks', 'mcp-managed.json');
+}
+function defaultPluginsRegistryPath() {
+    return join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+}
+function projectSettingsPath(projectRoot) {
+    return join(projectRoot, '.claude', 'settings.json');
+}
+async function readSettings(path) {
+    if (!(await pathExists(path))) {
+        return { exists: false, parsed: { parsed: null } };
+    }
+    try {
+        const raw = await readText(path);
+        const value = JSON.parse(raw);
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            return { exists: true, parsed: { parsed: null } };
+        }
+        return { exists: true, parsed: { parsed: value } };
+    }
+    catch (error) {
+        return { exists: true, parsed: { parsed: null, parseError: getErrorMessage(error) } };
+    }
+}
+async function loadManagedNames(path) {
+    if (!(await pathExists(path))) {
+        return new Set();
+    }
+    try {
+        const value = JSON.parse(await readText(path));
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            return new Set();
+        }
+        const servers = value.servers;
+        if (!Array.isArray(servers)) {
+            return new Set();
+        }
+        return new Set(servers.filter((entry) => typeof entry === 'string'));
+    }
+    catch {
+        return new Set();
+    }
+}
+function toStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === 'string');
+}
+function toEnvKeys(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return [];
+    }
+    return Object.keys(value);
+}
+function buildServerConfig(name, raw, scope, source, pluginName) {
+    const command = raw.command;
+    if (typeof command !== 'string' || command.length === 0) {
+        return null;
+    }
+    const config = {
+        name,
+        command,
+        args: toStringArray(raw.args),
+        envKeys: toEnvKeys(raw.env),
+        scope,
+        source
+    };
+    if (pluginName !== undefined) {
+        config.pluginName = pluginName;
+    }
+    return config;
+}
+function resolveServers(settings, scope, managedNames) {
+    if (settings === null) {
+        return [];
+    }
+    const mcpServers = settings.mcpServers;
+    if (mcpServers === null || typeof mcpServers !== 'object' || Array.isArray(mcpServers)) {
+        return [];
+    }
+    const servers = [];
+    for (const [name, raw] of Object.entries(mcpServers)) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            continue;
+        }
+        const source = managedNames.has(name) ? 'peaks' : 'unknown';
+        const config = buildServerConfig(name, raw, scope, source);
+        if (config !== null) {
+            servers.push(config);
+        }
+    }
+    return servers;
+}
+function toScopeReport(path, exists, parseError) {
+    return parseError === undefined ? { path, exists } : { path, exists, parseError };
+}
+function extractMcpServersBlock(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const wrapped = parsed.mcpServers;
+    if (wrapped !== undefined && wrapped !== null && typeof wrapped === 'object' && !Array.isArray(wrapped)) {
+        return wrapped;
+    }
+    return parsed;
+}
+async function readPluginMcpServers(installPath, pluginName) {
+    const mcpFilePath = join(installPath, '.mcp.json');
+    if (!(await pathExists(mcpFilePath))) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readText(mcpFilePath));
+    }
+    catch {
+        return [];
+    }
+    const block = extractMcpServersBlock(parsed);
+    if (block === null) {
+        return [];
+    }
+    const servers = [];
+    for (const [name, raw] of Object.entries(block)) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            continue;
+        }
+        const config = buildServerConfig(name, raw, 'plugin', 'plugin', pluginName);
+        if (config !== null) {
+            servers.push(config);
+        }
+    }
+    return servers;
+}
+async function scanPluginMcpServers(registryPath) {
+    const exists = await pathExists(registryPath);
+    const baseReport = {
+        path: registryPath,
+        exists,
+        pluginsScanned: 0,
+        pluginsWithMcp: 0
+    };
+    if (!exists) {
+        return { servers: [], report: baseReport };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readText(registryPath));
+    }
+    catch (error) {
+        return { servers: [], report: { ...baseReport, parseError: getErrorMessage(error) } };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { servers: [], report: baseReport };
+    }
+    const pluginsField = parsed.plugins;
+    if (pluginsField === null || typeof pluginsField !== 'object' || Array.isArray(pluginsField)) {
+        return { servers: [], report: baseReport };
+    }
+    const servers = [];
+    let pluginsScanned = 0;
+    let pluginsWithMcp = 0;
+    for (const [pluginId, entries] of Object.entries(pluginsField)) {
+        if (!Array.isArray(entries) || entries.length === 0) {
+            continue;
+        }
+        const first = entries[0];
+        if (first === null || typeof first !== 'object' || Array.isArray(first)) {
+            continue;
+        }
+        const installPath = first.installPath;
+        if (typeof installPath !== 'string' || installPath.length === 0) {
+            continue;
+        }
+        pluginsScanned += 1;
+        const found = await readPluginMcpServers(installPath, pluginId);
+        if (found.length > 0) {
+            pluginsWithMcp += 1;
+            servers.push(...found);
+        }
+    }
+    return { servers, report: { ...baseReport, pluginsScanned, pluginsWithMcp } };
+}
+export async function scanMcpServers(options = {}) {
+    const globalPath = options.globalSettingsPath ?? defaultGlobalSettingsPath();
+    const managedMarkerPath = options.managedMarkerPath ?? defaultManagedMarkerPath();
+    const pluginsRegistryPath = options.pluginsRegistryPath ?? defaultPluginsRegistryPath();
+    const managedNames = await loadManagedNames(managedMarkerPath);
+    const globalSettings = await readSettings(globalPath);
+    const globalScope = toScopeReport(globalPath, globalSettings.exists, globalSettings.parsed.parseError);
+    const globalServers = resolveServers(globalSettings.parsed.parsed, 'global', managedNames);
+    let projectScope = null;
+    const projectServers = [];
+    if (options.projectRoot !== undefined) {
+        const projectPath = projectSettingsPath(options.projectRoot);
+        const projectSettings = await readSettings(projectPath);
+        projectScope = toScopeReport(projectPath, projectSettings.exists, projectSettings.parsed.parseError);
+        projectServers.push(...resolveServers(projectSettings.parsed.parsed, 'project', managedNames));
+    }
+    const plugins = await scanPluginMcpServers(pluginsRegistryPath);
+    return {
+        servers: [...globalServers, ...projectServers, ...plugins.servers],
+        scopes: { global: globalScope, project: projectScope, plugins: plugins.report }
+    };
+}

package/dist/src/services/mcp/mcp-stdio-transport.d.ts

@@ -0,0 +1,10 @@
+import type { McpClientTransport } from './mcp-client-service.js';
+import type { McpInstallSpec } from './mcp-install-registry.js';
+export type StdioTransportOptions = {
+    command: string;
+    args?: string[];
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+};
+export declare function createStdioTransport(options: StdioTransportOptions): McpClientTransport;
+export declare function createStdioTransportFromSpec(spec: McpInstallSpec, env: Record<string, string | undefined>): McpClientTransport;

package/dist/src/services/mcp/mcp-stdio-transport.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+export function createStdioTransport(options) {
+    const env = {};
+    for (const [key, value] of Object.entries({ ...process.env, ...(options.env ?? {}) })) {
+        if (typeof value === 'string') {
+            env[key] = value;
+        }
+    }
+    const child = spawn(options.command, options.args ?? [], {
+        env,
+        cwd: options.cwd,
+        stdio: ['pipe', 'pipe', 'pipe']
+    });
+    let lineHandler = null;
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        if (lineHandler !== null) {
+            lineHandler(chunk);
+        }
+    });
+    return {
+        send: (line) => new Promise((resolve, reject) => {
+            child.stdin.write(line, (error) => {
+                if (error !== null && error !== undefined) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        }),
+        onLine: (handler) => {
+            lineHandler = handler;
+        },
+        close: () => new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null) {
+                resolve();
+                return;
+            }
+            child.once('exit', () => resolve());
+            child.kill();
+        })
+    };
+}
+export function createStdioTransportFromSpec(spec, env) {
+    const transportEnv = {};
+    for (const key of spec.envKeys) {
+        transportEnv[key] = env[key];
+    }
+    return createStdioTransport({ command: spec.command, args: spec.args, env: transportEnv });
+}

package/dist/src/services/mcp/mcp-types.d.ts

@@ -0,0 +1,31 @@
+export type McpServerSource = 'peaks' | 'cc-switch' | 'user' | 'plugin' | 'unknown';
+export type McpServerScope = 'global' | 'project' | 'plugin';
+export type McpServerConfig = {
+    name: string;
+    command: string;
+    args: string[];
+    envKeys: string[];
+    source: McpServerSource;
+    scope: McpServerScope;
+    pluginName?: string;
+};
+export type McpSettingsScopeReport = {
+    path: string;
+    exists: boolean;
+    parseError?: string;
+};
+export type McpPluginsReport = {
+    path: string;
+    exists: boolean;
+    parseError?: string;
+    pluginsScanned: number;
+    pluginsWithMcp: number;
+};
+export type McpScanReport = {
+    servers: McpServerConfig[];
+    scopes: {
+        global: McpSettingsScopeReport;
+        project: McpSettingsScopeReport | null;
+        plugins: McpPluginsReport;
+    };
+};

package/dist/src/services/mcp/mcp-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/openspec/openspec-archive-service.d.ts

@@ -0,0 +1,12 @@
+import type { OpenSpecScanOptions } from './openspec-scan-service.js';
+export type OpenSpecArchiveOptions = OpenSpecScanOptions & {
+    apply?: boolean;
+    archiveDirName?: string;
+};
+export type OpenSpecArchiveResult = {
+    changeId: string;
+    from: string;
+    to: string;
+    applied: boolean;
+};
+export declare function archiveOpenSpecChange(changeId: string, options?: OpenSpecArchiveOptions): Promise<OpenSpecArchiveResult | null>;

package/dist/src/services/openspec/openspec-archive-service.js

@@ -0,0 +1,28 @@
+import { mkdir, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isDirectory } from '../../shared/fs.js';
+const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+export async function archiveOpenSpecChange(changeId, options = {}) {
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+        throw new Error(`Invalid changeId: ${changeId} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const archiveDir = options.archiveDirName ?? 'archive';
+    const from = join(openspecRoot, 'changes', changeId);
+    const to = join(openspecRoot, 'changes', archiveDir, changeId);
+    if (!(await isDirectory(from))) {
+        return null;
+    }
+    if (options.apply !== true) {
+        return { changeId, from, to, applied: false };
+    }
+    if (await isDirectory(to)) {
+        throw new Error(`Refusing to archive: target already exists at ${to}`);
+    }
+    await mkdir(dirname(to), { recursive: true });
+    await rename(from, to);
+    return { changeId, from, to, applied: true };
+}

package/dist/src/services/openspec/openspec-bridge-service.d.ts

@@ -0,0 +1,16 @@
+import { type OpenSpecScanOptions } from './openspec-scan-service.js';
+export type OpenSpecCommitBoundary = {
+    heading: string;
+    todos: string[];
+    doneItems: string[];
+};
+export type OpenSpecRdInputProjection = {
+    changeId: string;
+    acceptance: string[];
+    whatChanges: string[];
+    dependencies: string[];
+    risks: string[];
+    outOfScope: string[];
+    commitBoundaries: OpenSpecCommitBoundary[];
+};
+export declare function projectOpenSpecToRdInput(changeId: string, options?: OpenSpecScanOptions): Promise<OpenSpecRdInputProjection | null>;

package/dist/src/services/openspec/openspec-bridge-service.js

@@ -0,0 +1,76 @@
+import { readText } from '../../shared/fs.js';
+import { loadOpenSpecChange } from './openspec-scan-service.js';
+function splitTaskSections(markdown) {
+    const sections = [];
+    let current = null;
+    for (const line of markdown.split(/\r?\n/)) {
+        if (line.startsWith('## ')) {
+            if (current !== null) {
+                sections.push(current);
+            }
+            current = { heading: line.slice(3).trim(), body: [] };
+        }
+        else if (current !== null) {
+            current.body.push(line);
+        }
+    }
+    if (current !== null) {
+        sections.push(current);
+    }
+    return sections;
+}
+const TODO_PATTERN = /^- \[ \] (.+?)\s*$/;
+const DONE_PATTERN = /^- \[[xX]\] (.+?)\s*$/;
+function extractItems(body) {
+    const todos = [];
+    const doneItems = [];
+    for (const rawLine of body) {
+        const line = rawLine.trim();
+        const todoMatch = TODO_PATTERN.exec(line);
+        if (todoMatch !== null) {
+            todos.push(todoMatch[1]);
+            continue;
+        }
+        const doneMatch = DONE_PATTERN.exec(line);
+        if (doneMatch !== null) {
+            doneItems.push(doneMatch[1]);
+        }
+    }
+    return { todos, doneItems };
+}
+async function buildCommitBoundaries(tasksPath) {
+    if (tasksPath === null) {
+        return [];
+    }
+    const markdown = await readText(tasksPath);
+    const boundaries = [];
+    for (const section of splitTaskSections(markdown)) {
+        const { todos, doneItems } = extractItems(section.body);
+        if (todos.length === 0 && doneItems.length === 0) {
+            continue;
+        }
+        boundaries.push({ heading: section.heading, todos, doneItems });
+    }
+    return boundaries;
+}
+export async function projectOpenSpecToRdInput(changeId, options = {}) {
+    const detail = await loadOpenSpecChange(changeId, options);
+    if (detail === null) {
+        return null;
+    }
+    const acceptance = detail.proposal?.acceptanceCriteria ?? [];
+    const whatChanges = detail.proposal?.whatChanges ?? [];
+    const dependencies = detail.proposal?.dependencies ?? [];
+    const risks = detail.proposal?.risks ?? [];
+    const outOfScope = detail.proposal?.outOfScope ?? [];
+    const commitBoundaries = await buildCommitBoundaries(detail.paths.tasks);
+    return {
+        changeId,
+        acceptance,
+        whatChanges,
+        dependencies,
+        risks,
+        outOfScope,
+        commitBoundaries
+    };
+}