vgxness 0.1.0

package/dist/mcp/client-install-opencode.js

@@ -0,0 +1,194 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createConfigBackupPath } from '../setup/backup-rollback-service.js';
+import { findConflictingVgxnessAgents, planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
+import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan } from './opencode-default-agent-config.js';
+const opencodeConfigSchema = 'https://opencode.ai/config.json';
+export { createInstalledVgxnessMcpServerCommand };
+function createInstalledVgxnessMcpServerCommand(databasePath, source = 'flag') {
+    return source === 'global-default' ? ['vgxness', 'mcp', 'start'] : ['vgxness', 'mcp', 'start', '--db', databasePath];
+}
+function createVgxnessMcpDoctorCommand(databasePath, source) {
+    return source === 'global-default' ? ['vgxness', 'mcp', 'doctor'] : ['vgxness', 'mcp', 'doctor', '--db', databasePath];
+}
+export function createOpenCodeLocalMcpServerConfig(databasePath, source = 'flag') {
+    return { type: 'local', command: createInstalledVgxnessMcpServerCommand(databasePath, source), enabled: true };
+}
+export async function installOpenCodeMcpClient(input) {
+    const databasePathSource = input.databasePathSource ?? 'flag';
+    const server = createOpenCodeLocalMcpServerConfig(input.databasePath, databasePathSource);
+    const agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: input.mcpOnly });
+    const plan = planOpenCodeMcpInstall({
+        cwd: input.cwd,
+        databasePath: input.databasePath,
+        databasePathSource,
+        ...(input.scope !== undefined ? { scope: input.scope } : {}),
+        ...(input.env !== undefined ? { env: input.env } : {}),
+        ...(input.mcpOnly !== undefined ? { mcpOnly: input.mcpOnly } : {}),
+    });
+    if (!input.confirmed) {
+        return refusal('confirmation_required', confirmationRequiredMessage(plan.scope), input.databasePath, databasePathSource, server, confirmationRequiredSafety(plan), 'targetPath' in plan ? plan.targetPath : undefined, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+    }
+    if (plan.status === 'refused')
+        return refusalFromPlan(plan, input.databasePath, databasePathSource, server);
+    if (plan.action === 'create') {
+        if (existsSync(plan.targetPath)) {
+            const reparsed = parseConfig(plan.targetPath);
+            if (!reparsed.ok)
+                return refusal(reparsed.reason, reparsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+            const conflictingAgents = findConflictingVgxnessAgents(reparsed.value, agentPlan);
+            if (conflictingAgents.length > 0)
+                return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+            return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+        }
+        writeConfig(plan.targetPath, mergeVgxnessOpenCodeConfig({ $schema: opencodeConfigSchema }, plan.server, plan.installsAgents));
+        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+    }
+    const parsed = parseConfig(plan.targetPath);
+    if (!parsed.ok)
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+    const conflictingAgents = findConflictingVgxnessAgents(parsed.value, agentPlan);
+    if (conflictingAgents.length > 0)
+        return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+    const backupPath = createBackup(plan.targetPath);
+    const config = parsed.value;
+    const mergedConfig = mergeVgxnessOpenCodeConfig({ ...config, $schema: plan.existingSchema ?? opencodeConfigSchema }, plan.server, plan.installsAgents);
+    writeConfig(plan.targetPath, mergedConfig);
+    return validateInstalledResult(plan.targetPath, backupPath, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan);
+}
+function mergeVgxnessOpenCodeConfig(config, server, installsAgents) {
+    const merged = {
+        ...config,
+        $schema: typeof config.$schema === 'string' ? config.$schema : opencodeConfigSchema,
+        mcp: { ...(isRecord(config.mcp) ? config.mcp : {}), vgxness: server },
+    };
+    if (installsAgents) {
+        const defaults = createOpenCodeDefaultAgentConfig();
+        merged.default_agent = defaults.defaultAgent;
+        merged.agent = { ...(isRecord(config.agent) ? config.agent : {}), ...defaults.agents };
+    }
+    return merged;
+}
+function parseConfig(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed)
+            ? { ok: true, value: parsed }
+            : { ok: false, reason: 'unsupported_config_shape', message: 'OpenCode config must be a JSON object.' };
+    }
+    catch {
+        return { ok: false, reason: 'malformed_json', message: 'OpenCode config must be valid JSON; malformed JSON and JSONC comments are refused.' };
+    }
+}
+function writeConfig(path, config) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+function createBackup(path) {
+    const backupPath = createConfigBackupPath(path);
+    copyFileSync(path, backupPath);
+    return backupPath;
+}
+function validateInstalledResult(targetPath, backupPath, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan) {
+    const parsed = parseConfig(targetPath);
+    if (!parsed.ok)
+        return refusal('post_write_validation_failed', 'OpenCode config could not be re-read after write.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);
+    const mcp = parsed.value.mcp;
+    const installed = isRecord(mcp) ? mcp.vgxness : undefined;
+    if (!isOpenCodeLocalMcpServerConfig(installed)) {
+        return refusal('post_write_validation_failed', 'OpenCode config was written but mcp.vgxness did not validate.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);
+    }
+    if (agentPlan.installsAgents) {
+        const agent = parsed.value.agent;
+        if (!isRecord(agent) || parsed.value.default_agent !== agentPlan.defaultAgent || agentPlan.agentNames.some((name) => !isRecord(agent[name]))) {
+            return refusal('post_write_validation_failed', 'OpenCode config was written but VGXNESS agent entries did not validate.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);
+        }
+    }
+    return {
+        version: 1,
+        kind: 'mcp-client-install-opencode',
+        status: 'installed',
+        targetPath,
+        ...(backupPath !== undefined ? { backupPath } : {}),
+        safety,
+        server,
+        warnings: warningMessages,
+        verificationHints,
+        manualTest: manualTestGuidance,
+        installsAgents: agentPlan.installsAgents,
+        agentNames: agentPlan.agentNames,
+        ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
+    };
+}
+function isOpenCodeLocalMcpServerConfig(value) {
+    return isRecord(value)
+        && value.type === 'local'
+        && value.enabled === true
+        && Array.isArray(value.command)
+        && value.command.every((item) => typeof item === 'string');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function refusal(reason, message, databasePath, source, server, safety, targetPath, verificationHints = defaultVerificationHints(databasePath, source), warningMessages = warnings(), manualTestGuidance = manualTest(databasePath, source), agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true })) {
+    return {
+        version: 1,
+        kind: 'mcp-client-install-opencode',
+        status: 'refused',
+        reason,
+        message,
+        ...(targetPath !== undefined ? { targetPath } : {}),
+        safety,
+        server,
+        warnings: warningMessages,
+        verificationHints,
+        manualTest: manualTestGuidance,
+        installsAgents: agentPlan.installsAgents,
+        agentNames: agentPlan.agentNames,
+        ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
+    };
+}
+function refusalFromPlan(plan, databasePath, source, server) {
+    return refusal(plan.reason, plan.message, databasePath, source, server, plan.safety, plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, plan);
+}
+function agentConflictRefusal(conflictingAgents, databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan) {
+    return refusal('existing_vgxness_agent', `Existing OpenCode config contains custom VGXNESS agent entries that would be overwritten: ${conflictingAgents.join(', ')}. Remove, rename, or manually reconcile them before installing.`, databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan);
+}
+function applySafety(plan) {
+    return {
+        ...plan.safety,
+        operation: 'apply',
+        mutating: true,
+        writesProviderConfig: true,
+    };
+}
+function confirmationRequiredSafety(plan) {
+    return {
+        operation: 'apply',
+        mutating: false,
+        writesProviderConfig: false,
+        ...('targetPath' in plan && plan.targetPath !== undefined ? { targetPath: plan.targetPath } : {}),
+        backupRequired: false,
+        mergePolicy: 'refuse-no-clobber',
+    };
+}
+function confirmationRequiredMessage(scope) {
+    return `\`mcp install opencode\` requires explicit --yes before any ${scope} config write.`;
+}
+function warnings() {
+    return ['Restart OpenCode after installation so it reloads the project MCP config.'];
+}
+function manualTest(databasePath, source) {
+    return {
+        restart: 'Restart OpenCode after the config is installed.',
+        verify: 'Open the project in OpenCode and verify the vgxness MCP server is available.',
+        doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
+    };
+}
+function defaultVerificationHints(databasePath, source) {
+    return [
+        { kind: 'restart-client', message: 'Restart OpenCode after the config is installed.' },
+        { kind: 'manual-check', message: 'Open the project in OpenCode and verify the vgxness MCP server is available.' },
+        { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createVgxnessMcpDoctorCommand(databasePath, source) },
+    ];
+}

package/dist/mcp/client-setup-preview.js

@@ -0,0 +1,38 @@
+export function createVgxnessMcpServerCommand(databasePath, source = 'flag') {
+    return source === 'global-default'
+        ? ['npm', 'run', 'cli', '--', 'mcp', 'start']
+        : ['npm', 'run', 'cli', '--', 'mcp', 'start', '--db', databasePath];
+}
+export function createMcpClientSetupPreview(input) {
+    const databasePathSource = input.databasePathSource ?? 'flag';
+    const server = {
+        name: 'vgxness',
+        command: 'npm',
+        args: createVgxnessMcpServerCommand(input.databasePath, databasePathSource).slice(1),
+    };
+    return {
+        version: 1,
+        kind: 'mcp-client-setup-preview',
+        provider: input.provider,
+        installable: false,
+        readOnly: true,
+        writesProviderConfig: false,
+        server,
+        snippets: snippetsFor(input.provider, server),
+        warnings: [
+            'This is preview-only output; it does not install or write provider config.',
+            databasePathSource === 'global-default'
+                ? 'Copy the snippet manually only after reviewing that it uses the vgxness global default database path.'
+                : 'Copy the snippet manually only after reviewing the command and database path.',
+        ],
+    };
+}
+export function isMcpClientSetupProvider(value) {
+    return value === 'opencode' || value === 'claude';
+}
+function snippetsFor(provider, server) {
+    if (provider === 'opencode') {
+        return [{ label: 'OpenCode MCP server JSON', format: 'json', value: { mcp: { vgxness: server } } }];
+    }
+    return [{ label: 'Claude-style MCP server JSON', format: 'json', value: { mcpServers: { vgxness: server } } }];
+}

package/dist/mcp/control-plane.js

@@ -0,0 +1,175 @@
+import { AgentRegistryService } from '../agents/agent-registry-service.js';
+import { AgentActivationService } from '../agents/agent-activation-service.js';
+import { ManagerProfileOverlayService } from '../agents/manager-profile-overlay-service.js';
+import { ManagerProfileOverlayRepository } from '../agents/repositories/manager-profile-overlays.js';
+import { MemoryService } from '../memory/memory-service.js';
+import { openMemoryDatabase } from '../memory/sqlite/database.js';
+import { prepareMemoryDatabasePath, resolveMemoryDatabasePath } from '../memory/storage-paths.js';
+import { SddWorkflowService } from '../sdd/sdd-workflow-service.js';
+import { SkillRegistryService } from '../skills/skill-registry-service.js';
+import { OpenCodeManagerPayloadService } from '../providers/opencode/manager-payload.js';
+import { RunService } from '../runs/run-service.js';
+import { errorEnvelope, successEnvelope } from './schema.js';
+import { validateVgxMcpToolCall } from './validation.js';
+export function callVgxTool(call, services) {
+    const validated = validateVgxMcpToolCall(call);
+    if (!validated.ok)
+        return validated;
+    switch (validated.tool) {
+        case 'vgxness_sdd_status':
+            return toEnvelope(validated.tool, services.sdd.getStatus(validated.input));
+        case 'vgxness_sdd_ready':
+            return toEnvelope(validated.tool, services.sdd.getReady(validated.input));
+        case 'vgxness_sdd_save_artifact':
+            return toEnvelope(validated.tool, services.sdd.saveArtifact(validated.input));
+        case 'vgxness_sdd_get_artifact':
+            return toEnvelope(validated.tool, services.sdd.getArtifact(validated.input));
+        case 'vgxness_sdd_list_artifacts':
+            return toEnvelope(validated.tool, services.sdd.listArtifacts(validated.input));
+        case 'vgxness_sdd_next':
+            return toEnvelope(validated.tool, services.sdd.getNext(validated.input));
+        case 'vgxness_memory_save':
+            return saveMemoryObservationEnvelope(validated.input, services);
+        case 'vgxness_memory_search':
+            return toEnvelope(validated.tool, services.memory.searchObservations(validated.input, memoryContext()));
+        case 'vgxness_memory_get':
+            return getMemoryObservationEnvelope(validated.input, services);
+        case 'vgxness_memory_update':
+            return updateMemoryObservationEnvelope(validated.input, services);
+        case 'vgxness_session_start':
+            return toEnvelope(validated.tool, services.memory.saveSession(validated.input, memoryContext(validated.input.id)));
+        case 'vgxness_session_append_activity':
+            return toEnvelope(validated.tool, services.memory.appendActivity(validated.input, memoryContext(validated.input.sessionId)));
+        case 'vgxness_session_close':
+            return toEnvelope(validated.tool, services.memory.closeSession(validated.input, memoryContext(validated.input.sessionId)));
+        case 'vgxness_session_restore':
+            return toEnvelope(validated.tool, services.memory.restoreSession(validated.input));
+        case 'vgxness_agent_resolve':
+            return toEnvelope(validated.tool, services.agents.resolveAgents(validated.input));
+        case 'vgxness_agent_activate':
+            return toEnvelope(validated.tool, services.activation.activate(validated.input));
+        case 'vgxness_manager_profile_get':
+            return getManagerProfileEnvelope(validated.input, services);
+        case 'vgxness_manager_profile_set':
+            return setManagerProfileEnvelope(validated.input, services);
+        case 'vgxness_skill_payload':
+            return buildSkillPayloadEnvelope(validated.input, services);
+        case 'vgxness_opencode_manager_payload':
+            return toEnvelope(validated.tool, services.opencodeManagerPayload.build(validated.input));
+        case 'vgxness_run_list':
+            return listRunsEnvelope(validated.input, services);
+        case 'vgxness_run_get':
+            return toEnvelope(validated.tool, services.runs.getRun(validated.input.id));
+        case 'vgxness_run_preflight':
+            return toEnvelope(validated.tool, services.runs.preflightOperation(validated.input));
+        case 'vgxness_run_start':
+            return toEnvelope(validated.tool, services.runs.createRun(validated.input));
+        case 'vgxness_run_checkpoint':
+            return toEnvelope(validated.tool, services.runs.appendCheckpoint(validated.input));
+        case 'vgxness_run_finalize':
+            return toEnvelope(validated.tool, services.runs.updateFinalStatus(validated.input));
+    }
+    return errorEnvelope('validation_failed', 'Tool dispatch is not implemented');
+}
+export function createVgxMcpControlPlane(options = {}) {
+    const databasePath = resolveControlPlaneDatabasePath(options);
+    if (!databasePath.ok)
+        throw new VgxMcpControlPlaneError(databasePath.error);
+    const prepared = prepareMemoryDatabasePath(databasePath.value);
+    if (!prepared.ok)
+        throw new VgxMcpControlPlaneError(prepared.error);
+    const opened = openMemoryDatabase({ path: databasePath.value });
+    if (!opened.ok)
+        throw new VgxMcpControlPlaneError(opened.error);
+    const database = opened.value;
+    const services = createServices(database);
+    let closed = false;
+    return {
+        callVgxTool: (tool, input) => callVgxTool({ tool, input }, services),
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            database.close();
+        },
+    };
+}
+export class VgxMcpControlPlaneError extends Error {
+    code;
+    cause;
+    constructor(failure) {
+        super(failure.message);
+        this.name = 'VgxMcpControlPlaneError';
+        this.code = failure.code;
+        if (failure.cause !== undefined)
+            this.cause = failure.cause;
+    }
+}
+function createServices(database) {
+    const memory = new MemoryService(database);
+    const agents = new AgentRegistryService(database);
+    const skills = new SkillRegistryService(database);
+    const runs = new RunService(database);
+    const managerProfiles = new ManagerProfileOverlayService({ agents, overlays: new ManagerProfileOverlayRepository(database) });
+    const opencodeManagerPayload = new OpenCodeManagerPayloadService({ agents, managerProfiles, skills });
+    return {
+        sdd: new SddWorkflowService(memory, { actor: 'mcp-control-plane' }),
+        memory,
+        agents,
+        managerProfiles,
+        skills,
+        opencodeManagerPayload,
+        activation: new AgentActivationService({ agents, managerProfiles, runs, opencodeManagerPayload }),
+        runs,
+    };
+}
+function getManagerProfileEnvelope(input, services) {
+    if (services.managerProfiles === undefined)
+        return errorEnvelope('validation_failed', 'Manager profile service is not available', 'vgxness_manager_profile_get');
+    return toEnvelope('vgxness_manager_profile_get', services.managerProfiles.resolveEffectiveManager({ project: input.project, scope: input.scope ?? 'project', managerName: input.managerName ?? 'vgxness-manager' }));
+}
+function setManagerProfileEnvelope(input, services) {
+    if (services.managerProfiles === undefined)
+        return errorEnvelope('validation_failed', 'Manager profile service is not available', 'vgxness_manager_profile_set');
+    const baseline = services.managerProfiles.resolveEffectiveManager({ project: input.project, scope: input.scope, managerName: input.managerName });
+    if (!baseline.ok)
+        return errorEnvelope(baseline.error.code, baseline.error.message, 'vgxness_manager_profile_set');
+    const saved = services.managerProfiles.save(input);
+    if (!saved.ok)
+        return errorEnvelope(saved.error.code, saved.error.message, 'vgxness_manager_profile_set');
+    return toEnvelope('vgxness_manager_profile_set', services.managerProfiles.resolveEffectiveManager({ project: input.project, scope: input.scope, managerName: input.managerName }));
+}
+function saveMemoryObservationEnvelope(input, services) {
+    return toEnvelope('vgxness_memory_save', services.memory.saveObservation({ ...input, scope: input.scope ?? 'project' }, memoryContext()));
+}
+function getMemoryObservationEnvelope(input, services) {
+    return toEnvelope('vgxness_memory_get', services.memory.getObservation(input.id, memoryContext()));
+}
+function updateMemoryObservationEnvelope(input, services) {
+    return toEnvelope('vgxness_memory_update', services.memory.updateObservation(input, memoryContext()));
+}
+function memoryContext(sessionId) {
+    const context = { actor: 'mcp-control-plane' };
+    if (sessionId !== undefined)
+        context.sessionId = sessionId;
+    return context;
+}
+function buildSkillPayloadEnvelope(input, services) {
+    const { workspaceRoot, maxSourceBytes, ...resolverInput } = input;
+    const options = maxSourceBytes === undefined ? { workspaceRoot } : { workspaceRoot, maxSourceBytes };
+    return toEnvelope('vgxness_skill_payload', services.skills.buildSkillPayload(resolverInput, options));
+}
+function listRunsEnvelope(input, services) {
+    const { limit, ...filters } = input;
+    const result = services.runs.listRuns(filters);
+    return result.ok ? successEnvelope('vgxness_run_list', result.value.slice(0, limit)) : errorEnvelope(result.error.code, result.error.message, 'vgxness_run_list');
+}
+function toEnvelope(tool, result) {
+    return result.ok ? successEnvelope(tool, result.value) : errorEnvelope(result.error.code, result.error.message, tool);
+}
+function resolveControlPlaneDatabasePath(options) {
+    if (options.databasePath !== undefined)
+        return { ok: true, value: options.databasePath };
+    const resolved = resolveMemoryDatabasePath({ cwd: process.cwd(), env: process.env });
+    return resolved.ok ? { ok: true, value: resolved.value.path } : resolved;
+}

package/dist/mcp/doctor.js

@@ -0,0 +1,193 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openMemoryDatabase } from '../memory/sqlite/database.js';
+import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
+import { SUPPORTED_VGX_MCP_TOOL_NAMES } from './schema.js';
+export async function createMcpDoctorReport(options) {
+    const cwd = options.cwd;
+    const databasePath = resolve(cwd, options.databasePath ?? join('.vgx', 'memory.sqlite'));
+    const project = options.project ?? 'vgxness';
+    const change = options.change ?? 'doctor-smoke';
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const providerTargets = resolveProviderConfigTargets(cwd, options.env);
+    const beforeProviderPaths = providerConfigSnapshot(providerTargets);
+    const checks = [];
+    checks.push(checkNodeVersion());
+    checks.push(checkDatabasePath(databasePath));
+    const sqlite = checkSqliteMigrations(databasePath);
+    checks.push(sqlite);
+    if (sqlite.status === 'pass') {
+        const smoke = await checkMcpSmoke({ cwd, databasePath, project, change, timeoutMs, smoke: options.smoke ?? runRealMcpSmoke });
+        checks.push(smoke.spawn, smoke.toolsList, smoke.safeStatusCall);
+    }
+    else {
+        checks.push(skipped('mcp-spawn', 'Skipped because SQLite/migrations readiness failed'));
+        checks.push(skipped('tools-list', 'Skipped because MCP stdio spawn did not pass'));
+        checks.push(skipped('safe-status-call', 'Skipped because MCP tools/list did not pass'));
+    }
+    checks.push(checkProviderConfigSafety(providerTargets, beforeProviderPaths));
+    return {
+        version: 1,
+        kind: 'mcp-doctor',
+        ready: checks.every((check) => check.status === 'pass'),
+        checks,
+        safety: { writesProviderConfig: false, checkedPaths: providerTargets.map((target) => target.label), checkedTargets: checkedTargets(providerTargets) },
+    };
+}
+async function checkMcpSmoke(options) {
+    try {
+        const result = await runWithTimeout(options.timeoutMs, (signal) => options.smoke({ cwd: options.cwd, databasePath: options.databasePath, project: options.project, change: options.change, signal }));
+        const expectedTools = [...SUPPORTED_VGX_MCP_TOOL_NAMES].sort();
+        const listedTools = [...result.tools].sort();
+        const toolsMatch = JSON.stringify(listedTools) === JSON.stringify(expectedTools);
+        return {
+            spawn: passed('mcp-spawn', 'MCP stdio server responded'),
+            toolsList: toolsMatch
+                ? passed('tools-list', `Listed expected tools: ${expectedTools.join(', ')}`)
+                : failed('tools-list', `Expected tools ${expectedTools.join(', ')}, got ${listedTools.join(', ')}`, 'Check the MCP server tool registration.'),
+            safeStatusCall: result.statusCallOk
+                ? passed('safe-status-call', `vgxness_sdd_status completed for ${options.project}/${options.change}`)
+                : failed('safe-status-call', 'vgxness_sdd_status did not complete successfully', 'Inspect the selected DB path and SDD status tool validation.'),
+        };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return {
+            spawn: failed('mcp-spawn', message.includes('timed out') ? message : `MCP stdio smoke failed: ${message}`, 'Run mcp start with the selected --db path and inspect stderr.'),
+            toolsList: skipped('tools-list', 'Skipped because MCP stdio spawn did not pass'),
+            safeStatusCall: skipped('safe-status-call', 'Skipped because MCP tools/list did not pass'),
+        };
+    }
+}
+async function runRealMcpSmoke(options) {
+    const client = new Client({ name: 'vgxness-doctor', version: '0.1.0' }, { capabilities: {} });
+    const invocation = resolveDoctorCliInvocation(options.databasePath);
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: invocation.args,
+        cwd: options.cwd,
+        stderr: 'pipe',
+    });
+    const closeOnAbort = () => {
+        void client.close().catch(() => undefined);
+    };
+    options.signal.addEventListener('abort', closeOnAbort, { once: true });
+    try {
+        await client.connect(transport);
+        const listed = await client.listTools();
+        const status = await client.callTool({ name: 'vgxness_sdd_status', arguments: { project: options.project, change: options.change } });
+        return { tools: listed.tools.map((tool) => tool.name), statusCallOk: parseMcpToolResult(status).ok === true };
+    }
+    finally {
+        options.signal.removeEventListener('abort', closeOnAbort);
+        await client.close().catch(() => undefined);
+    }
+}
+async function runWithTimeout(timeoutMs, operation) {
+    const controller = new AbortController();
+    let timeout;
+    try {
+        return await Promise.race([
+            operation(controller.signal),
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`MCP stdio smoke timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+    }
+}
+function checkNodeVersion() {
+    const major = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+    return major >= 22
+        ? passed('node', `Node ${process.version} satisfies >=22`)
+        : failed('node', `Node ${process.version} does not satisfy >=22`, 'Install Node.js 22 or newer.');
+}
+function checkDatabasePath(databasePath) {
+    try {
+        mkdirSync(dirname(databasePath), { recursive: true });
+        return passed('db-path', `Selected DB path is ${databasePath}`);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return failed('db-path', `Unable to prepare selected DB path ${databasePath}: ${message}`, 'Choose a writable --db path.');
+    }
+}
+function checkSqliteMigrations(databasePath) {
+    const opened = openMemoryDatabase({ path: databasePath });
+    if (!opened.ok)
+        return failed('sqlite-migrations', opened.error.message, 'Check DB permissions and migration SQL files.');
+    try {
+        return passed('sqlite-migrations', 'SQLite opened and migrations are ready');
+    }
+    finally {
+        opened.value.close();
+    }
+}
+function resolveProviderConfigTargets(cwd, env) {
+    const targets = [
+        { label: '.opencode', path: join(cwd, '.opencode'), kind: 'project-opencode' },
+        { label: '.claude', path: join(cwd, '.claude'), kind: 'project-claude' },
+    ];
+    const userTarget = resolveOpenCodeMcpInstallTarget({ cwd, scope: 'user', env });
+    if (userTarget.ok)
+        targets.push({ label: '$HOME/.config/opencode/opencode.json', path: userTarget.path, kind: 'user-opencode' });
+    return targets;
+}
+function checkProviderConfigSafety(targets, before) {
+    const mutated = targets.filter((target) => before[target.label] !== existsSync(target.path));
+    const detail = providerSafetyDetail(targets);
+    return mutated.length === 0
+        ? passed('provider-config-safety', `No provider config paths were created or removed. ${detail}`)
+        : failed('provider-config-safety', `Provider config paths changed: ${mutated.map((target) => target.label).join(', ')}. ${detail}`, 'Doctor must not write provider config; inspect the command implementation.');
+}
+function providerConfigSnapshot(targets) {
+    return Object.fromEntries(targets.map((target) => [target.label, existsSync(target.path)]));
+}
+function providerSafetyDetail(targets) {
+    const projectOpenCode = projectOpenCodeConfigPath(targets);
+    const userOpenCode = targets.find((target) => target.kind === 'user-opencode')?.path ?? 'unresolved because HOME is not set';
+    return `Project OpenCode target: ${projectOpenCode}; User OpenCode target: ${userOpenCode}. Project OpenCode config can override user config.`;
+}
+function checkedTargets(targets) {
+    const projectOpenCode = projectOpenCodeConfigPath(targets);
+    const userOpenCode = targets.find((target) => target.kind === 'user-opencode')?.path;
+    return { projectOpenCode, ...(userOpenCode !== undefined ? { userOpenCode } : {}) };
+}
+function projectOpenCodeConfigPath(targets) {
+    const projectDirectory = targets.find((target) => target.kind === 'project-opencode')?.path;
+    return projectDirectory === undefined ? 'unresolved' : join(projectDirectory, 'opencode.json');
+}
+function parseMcpToolResult(result) {
+    const envelope = result;
+    const text = envelope.content?.[0]?.text;
+    if (typeof text !== 'string')
+        return { ok: false, error: { code: 'validation_failed', message: 'MCP response did not contain text JSON' } };
+    return JSON.parse(text);
+}
+export function resolveDoctorCliInvocation(databasePath, moduleUrl = import.meta.url) {
+    const builtCliPath = fileURLToPath(new URL('../cli/index.js', moduleUrl));
+    if (existsSync(builtCliPath))
+        return { args: [builtCliPath, 'mcp', 'start', '--db', databasePath] };
+    return { args: ['--import', import.meta.resolve('tsx'), cliSourcePath(moduleUrl), 'mcp', 'start', '--db', databasePath] };
+}
+function cliSourcePath(moduleUrl) {
+    return fileURLToPath(new URL('../cli/index.ts', moduleUrl));
+}
+function passed(id, detail) {
+    return { id, status: 'pass', detail };
+}
+function failed(id, detail, remediation) {
+    return { id, status: 'fail', detail, remediation };
+}
+function skipped(id, detail) {
+    return { id, status: 'skip', detail };
+}

package/dist/mcp/index.js

@@ -0,0 +1,10 @@
+export * from './schema.js';
+export * from './validation.js';
+export * from './control-plane.js';
+export * from './stdio-server.js';
+export * from './client-setup-preview.js';
+export * from './client-install-opencode-contract.js';
+export * from './client-install-opencode.js';
+export * from './doctor.js';
+export * from './opencode-visibility.js';
+export * from '../providers/opencode/manager-payload.js';