peaks-cli 1.0.12 → 1.0.14

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

@@ -1,15 +1,14 @@
 import { existsSync, realpathSync, statSync } from 'node:fs';
-import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { dirname, isAbsolute, relative, resolve, sep, win32 } from 'node:path';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
 const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
 const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
 const CODEGRAPH_EXECUTABLE = process.execPath;
 const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
-const CODEGRAPH_PROCESS_TIMEOUT_MS = 600_000;
-const CODEGRAPH_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
 const POSITIONAL_ARGUMENT_PREFIX = '-';
 const ALLOWED_SUBCOMMANDS = ['status', 'init', 'index', 'query', 'files', 'context', 'affected'];
+const NUMERIC_FLAG_NAMES = ['limit', 'maxDepth'];
 const COMMON_OPTION_KEYS = ['subcommand', 'project'];
 const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     status: [],
@@ -20,16 +19,10 @@ const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     context: ['task'],
     affected: ['files', 'json']
 };
-function assertCodegraphBinaryExists(binaryPath) {
-    if (!existsSync(binaryPath)) {
-        throw new Error('Unable to resolve local codegraph binary from @colbymchenry/codegraph');
-    }
-}
 function resolveCodegraphBinaryPath() {
     const require = createRequire(import.meta.url);
     const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
     const binaryPath = resolve(dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js');
-    assertCodegraphBinaryExists(binaryPath);
     return binaryPath;
 }
 function assertSupportedSubcommand(subcommand) {
@@ -37,15 +30,12 @@ function assertSupportedSubcommand(subcommand) {
         throw new Error(`Unsupported codegraph subcommand: ${subcommand}`);
     }
 }
-function assertProjectRootDirectory(projectRoot) {
-    if (!statSync(projectRoot).isDirectory()) {
-        throw new Error('Project path must exist and be a directory');
-    }
-}
 function resolveProjectRoot(project) {
     const projectRoot = resolve(project);
     try {
-        assertProjectRootDirectory(projectRoot);
+        if (!statSync(projectRoot).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
         return realpathSync.native(projectRoot);
     }
     catch {
@@ -90,19 +80,17 @@ function assertInsideProject(projectRoot, absolutePath) {
         throw new Error('Affected files must stay inside the project');
     }
 }
-function climbToExistingBoundary(currentPath, pathExists = existsSync) {
-    while (!pathExists(currentPath)) {
+function resolveExistingBoundary(absoluteFilePath) {
+    if (existsSync(absoluteFilePath)) {
+        return absoluteFilePath;
+    }
+    let currentPath = dirname(absoluteFilePath);
+    while (!existsSync(currentPath)) {
         const parentPath = dirname(currentPath);
-        if (parentPath === currentPath) {
-            return currentPath;
-        }
         currentPath = parentPath;
     }
     return currentPath;
 }
-function resolveExistingBoundary(absoluteFilePath) {
-    return existsSync(absoluteFilePath) ? absoluteFilePath : climbToExistingBoundary(dirname(absoluteFilePath));
-}
 function normalizeProjectRelativeFile(projectRoot, file) {
     assertPositionalArgument(file, 'Affected files');
     const absoluteFilePath = resolve(projectRoot, file);
@@ -111,13 +99,10 @@ function normalizeProjectRelativeFile(projectRoot, file) {
     assertInsideProject(projectRoot, realBoundary);
     return relative(projectRoot, absoluteFilePath).split(sep).join('/');
 }
-function assertAffectedFiles(files) {
+function buildAffectedFileArgs(projectRoot, files) {
     if (!files || files.length < 1) {
         throw new Error('affected requires at least one file');
     }
-}
-function buildAffectedFileArgs(projectRoot, files) {
-    assertAffectedFiles(files);
     return files.map((file) => normalizeProjectRelativeFile(projectRoot, file));
 }
 function buildCommandArgs(options, projectRoot) {
@@ -154,106 +139,6 @@ function buildCommandArgs(options, projectRoot) {
     }
     return args;
 }
-function createCodegraphEnvironment(sourceEnv = process.env) {
-    const preservedKeys = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'WINDIR'];
-    const environment = {};
-    for (const key of preservedKeys) {
-        const value = sourceEnv[key];
-        if (value !== undefined) {
-            environment[key] = value;
-        }
-    }
-    return environment;
-}
-function assertOutputLimit(currentSize, chunkSize) {
-    const nextSize = currentSize + chunkSize;
-    if (nextSize > CODEGRAPH_OUTPUT_LIMIT_BYTES) {
-        throw new Error(`codegraph output exceeded ${CODEGRAPH_OUTPUT_LIMIT_BYTES} bytes`);
-    }
-    return nextSize;
-}
-function getWindowsTaskkillPath(fileExists = existsSync) {
-    const candidates = [
-        win32.join('C:\\Windows', 'System32', 'taskkill.exe'),
-        win32.join('C:\\WINNT', 'System32', 'taskkill.exe')
-    ];
-    return candidates.find((candidate) => fileExists(candidate)) ?? null;
-}
-function terminateCodegraphProcess(childProcess, platform = process.platform, killProcess = process.kill, spawnProcess = spawn, taskkillPath = getWindowsTaskkillPath()) {
-    if (childProcess.pid === undefined) {
-        childProcess.kill();
-        return;
-    }
-    if (platform === 'win32') {
-        if (!taskkillPath) {
-            childProcess.kill();
-            return;
-        }
-        const killerProcess = spawnProcess(taskkillPath, ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
-        killerProcess.on('error', () => childProcess.kill());
-        killerProcess.unref();
-        return;
-    }
-    try {
-        killProcess(-childProcess.pid, 'SIGTERM');
-    }
-    catch {
-        childProcess.kill('SIGTERM');
-    }
-}
-function runCodegraphProcess(invocation, timeoutMs = CODEGRAPH_PROCESS_TIMEOUT_MS) {
-    return new Promise((resolveResult, reject) => {
-        const childProcess = spawn(invocation.executable, invocation.args, {
-            cwd: invocation.cwd,
-            detached: process.platform !== 'win32',
-            env: createCodegraphEnvironment(),
-            shell: false
-        });
-        const timeout = setTimeout(() => {
-            terminateCodegraphProcess(childProcess);
-            reject(new Error(`codegraph process timed out after ${timeoutMs}ms`));
-        }, timeoutMs);
-        const stdoutChunks = [];
-        const stderrChunks = [];
-        let stdoutSize = 0;
-        let stderrSize = 0;
-        childProcess.stdout.on('data', (chunk) => {
-            try {
-                stdoutSize = assertOutputLimit(stdoutSize, chunk.length);
-                stdoutChunks.push(chunk);
-            }
-            catch (error) {
-                terminateCodegraphProcess(childProcess);
-                reject(error);
-            }
-        });
-        childProcess.stderr.on('data', (chunk) => {
-            try {
-                stderrSize = assertOutputLimit(stderrSize, chunk.length);
-                stderrChunks.push(chunk);
-            }
-            catch (error) {
-                terminateCodegraphProcess(childProcess);
-                reject(error);
-            }
-        });
-        childProcess.on('error', (error) => {
-            clearTimeout(timeout);
-            reject(error);
-        });
-        childProcess.on('close', (exitCode) => {
-            clearTimeout(timeout);
-            resolveResult({
-                exitCode,
-                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
-                stderr: Buffer.concat(stderrChunks).toString('utf8')
-            });
-        });
-    });
-}
-function defaultCodegraphProcessRunner(invocation) {
-    return runCodegraphProcess(invocation);
-}
 export function createCodegraphInvocation(options) {
     assertSupportedSubcommand(options.subcommand);
     const projectRoot = resolveProjectRoot(options.project);

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

@@ -156,25 +156,6 @@ function validateUserConfigPathForWrite(configPath) {
         }
     }
 }
-function getExistingBoundary(path) {
-    let currentPath = resolve(path);
-    while (!existsSync(currentPath)) {
-        const parentPath = dirname(currentPath);
-        if (parentPath === currentPath) {
-            return currentPath;
-        }
-        currentPath = parentPath;
-    }
-    return currentPath;
-}
-function validateArtifactWorkspaceRootBeforeCreate(artifactRoot, workspaceRoot) {
-    const workspaceRootReal = realpathSync(workspaceRoot);
-    const existingBoundary = getExistingBoundary(artifactRoot);
-    const existingBoundaryReal = realpathSync(existingBoundary);
-    if (isInsidePath(resolve(artifactRoot), workspaceRoot) || isInsidePath(existingBoundaryReal, workspaceRootReal)) {
-        throw new Error('Artifact workspace must stay outside the project root');
-    }
-}
 function validateArtifactWorkspaceRoot(artifactRoot, workspaceRoot) {
     const artifactStats = lstatSync(artifactRoot);
     if (!artifactStats.isDirectory() || artifactStats.isSymbolicLink()) {
@@ -890,7 +871,6 @@ function ensureArtifactWorkspaceMarker(workspace) {
     const artifactRoot = getWorkspaceArtifactRoot(workspace);
     const peaksPath = resolve(artifactRoot, '.peaks');
     const markerPath = resolve(peaksPath, 'config.json');
-    validateArtifactWorkspaceRootBeforeCreate(artifactRoot, workspace.rootPath);
     ensureDir(artifactRoot);
     validateArtifactWorkspaceRoot(artifactRoot, workspace.rootPath);
     ensureDir(peaksPath);
@@ -907,7 +887,7 @@ export function ensureWorkspaceConfigForPath(path = process.cwd()) {
     const existingWorkspace = findWorkspaceForPath(config.workspaces, path);
     if (existingWorkspace) {
         ensureArtifactWorkspaceMarker(existingWorkspace);
-        if (config.currentWorkspace !== existingWorkspace.workspaceId) {
+        if (!config.currentWorkspace) {
             writeConfig({ currentWorkspace: existingWorkspace.workspaceId }, 'user');
         }
         return existingWorkspace;
@@ -923,7 +903,7 @@ export function ensureWorkspaceConfigForPath(path = process.cwd()) {
     };
     ensureArtifactWorkspaceMarker(workspace);
     const updatedWorkspaces = [...config.workspaces, workspace];
-    writeConfig({ workspaces: updatedWorkspaces, currentWorkspace: workspace.workspaceId }, 'user');
+    writeConfig({ workspaces: updatedWorkspaces, ...(!config.currentWorkspace ? { currentWorkspace: workspace.workspaceId } : {}) }, 'user');
     return workspace;
 }
 export function getWorkspaceConfigForCurrentPath() {

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>;