vgxness 1.5.1 → 1.6.0

package/dist/governance/governance-report-builder.js

@@ -59,18 +59,53 @@ export class GovernanceReportBuilder {
             warnings.push('missing-change-sdd-snapshot-skipped');
             return { ok: true, value: report };
         }
-        const status = this.services.sdd.getStatus({
-            project: input.project,
+        if (this.tryBuildOptimizedSddSnapshot(report, input.project, change, phase, payloadMode, warnings)) {
+            report.warnings = dedupe(warnings);
+            report.openCode.warnings = dedupe(report.openCode.warnings ?? []);
+            return { ok: true, value: report };
+        }
+        this.buildFallbackSddSnapshot(report, input.project, change, phase, payloadMode, warnings);
+        report.warnings = dedupe(warnings);
+        report.openCode.warnings = dedupe(report.openCode.warnings ?? []);
+        return { ok: true, value: report };
+    }
+    tryBuildOptimizedSddSnapshot(report, project, change, phase, payloadMode, warnings) {
+        if (this.services.sdd.getGovernanceSnapshot === undefined)
+            return false;
+        if (phase !== undefined && !isSddPhase(phase)) {
+            warnings.push('sdd-readiness-skipped-non-sdd-phase');
+            return false;
+        }
+        const snapshot = this.services.sdd.getGovernanceSnapshot({
+            project,
             change,
+            payloadMode,
+            ...(phase === undefined ? {} : { phase }),
         });
+        if (!snapshot.ok) {
+            warnings.push(`sdd-snapshot-unavailable:${snapshot.error.code}`);
+            return false;
+        }
+        report.sdd.status = snapshot.value.status;
+        report.sdd.artifacts = snapshot.value.artifacts;
+        warnings.push(...snapshot.value.warnings);
+        if (snapshot.value.readiness !== undefined) {
+            report.sdd.readiness = snapshot.value.readiness;
+            for (const blocker of snapshot.value.readiness.blockedPrerequisites ?? [])
+                warnings.push(`missing-accepted-prerequisite:${blocker.phase}:${blocker.reason}`);
+        }
+        else {
+            warnings.push('sdd-readiness-skipped-missing-phase');
+        }
+        return true;
+    }
+    buildFallbackSddSnapshot(report, project, change, phase, payloadMode, warnings) {
+        const status = this.services.sdd.getStatus({ project, change });
         if (status.ok)
             report.sdd.status = status.value;
         else
             warnings.push(`sdd-status-unavailable:${status.error.code}`);
-        const listed = this.services.sdd.listArtifacts({
-            project: input.project,
-            change,
-        });
+        const listed = this.services.sdd.listArtifacts({ project, change });
         if (listed.ok) {
             report.sdd.artifacts = listed.value.artifacts.map((artifact) => {
                 const envelope = normalizeSddArtifact(artifact);
@@ -81,34 +116,21 @@ export class GovernanceReportBuilder {
                         phase: artifact.phase,
                         topicKey: artifact.topicKey,
                         artifact: compactArtifact,
-                        envelope: {
-                            ...envelope,
-                            artifact: compactArtifact,
-                        },
+                        envelope: { ...envelope, artifact: compactArtifact },
                     };
                 }
-                return {
-                    phase: artifact.phase,
-                    topicKey: artifact.topicKey,
-                    artifact,
-                    envelope,
-                };
+                return { phase: artifact.phase, topicKey: artifact.topicKey, artifact, envelope };
             });
         }
         else {
             warnings.push(`sdd-artifacts-unavailable:${listed.error.code}`);
         }
         if (phase !== undefined && isSddPhase(phase)) {
-            const readiness = this.services.sdd.getReady({
-                project: input.project,
-                change,
-                phase,
-            });
+            const readiness = this.services.sdd.getReady({ project, change, phase });
             if (readiness.ok) {
                 report.sdd.readiness = readiness.value;
-                for (const blocker of readiness.value.blockedPrerequisites ?? []) {
+                for (const blocker of readiness.value.blockedPrerequisites ?? [])
                     warnings.push(`missing-accepted-prerequisite:${blocker.phase}:${blocker.reason}`);
-                }
             }
             else {
                 warnings.push(`sdd-readiness-unavailable:${readiness.error.code}`);
@@ -120,9 +142,6 @@ export class GovernanceReportBuilder {
         else {
             warnings.push('sdd-readiness-skipped-missing-phase');
         }
-        report.warnings = dedupe(warnings);
-        report.openCode.warnings = dedupe(report.openCode.warnings ?? []);
-        return { ok: true, value: report };
     }
     buildOverlay(input, run, agent, warnings) {
         if (this.services.managerProfiles === undefined)

package/dist/mcp/claude-code-agent-config.js

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { projectCanonicalAgentManifestToClaudeCode } from '../agents/canonical-agent-projection.js';
+import { assertInsideWorkspace } from './claude-code-config.js';
+export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
+export function expectedClaudeCodeAgentFiles(input) {
+    const target = typeof input === 'string' ? resolveClaudeAgentTarget({ workspaceRoot: input, scope: 'project' }) : resolveClaudeAgentTarget(input);
+    return projectCanonicalAgentManifestToClaudeCode().agents.map((agent) => {
+        const path = resolve(target.directoryPath, agent.fileName);
+        if (target.scope === 'project')
+            assertInsideWorkspace(target.workspaceRoot, path);
+        return { ...agent, path };
+    });
+}
+export function renderClaudeCodeAgentMarkdown(agent) {
+    return `---\nname: ${yamlScalar(agent.name)}\ndescription: ${yamlScalar(agent.description)}\n---\n\n<!-- ${claudeCodeGeneratedMarker} claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=${agent.promptContractVersion} safe-update=true -->\n\n${agent.instructions.trim()}\n`;
+}
+export function inspectClaudeCodeAgents(input) {
+    const target = typeof input === 'string' ? resolveClaudeAgentTarget({ workspaceRoot: input, scope: 'project' }) : resolveClaudeAgentTarget(input);
+    const expected = expectedClaudeCodeAgentFiles({ workspaceRoot: target.workspaceRoot, scope: target.scope, ...(target.env === undefined ? {} : { env: target.env }) });
+    return { scope: target.scope, directoryPath: target.directoryPath, directoryExists: existsSync(target.directoryPath), external: target.scope === 'user', agents: expected.map(inspectAgent) };
+}
+export function resolveClaudeAgentTarget(input) {
+    const scope = input.scope ?? 'project';
+    if (scope === 'project')
+        return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(input.workspaceRoot, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
+    const home = safeHomeDirectory(input.env);
+    return { workspaceRoot: input.workspaceRoot, scope, directoryPath: join(home, '.claude', 'agents'), ...(input.env === undefined ? {} : { env: input.env }) };
+}
+export function safeHomeDirectory(env = process.env) {
+    const candidate = env.HOME?.trim() || homedir();
+    if (!candidate || candidate === '/' || candidate.includes('\0') || candidate.includes('~'))
+        throw new Error('Unable to resolve a safe home directory for Claude user agents.');
+    return resolve(candidate);
+}
+export function isVgxnessOwnedClaudeAgentMarkdown(contents) {
+    return contents.includes(claudeCodeGeneratedMarker) && contents.includes('provider=claude') && contents.includes('artifact=claude-code-subagent');
+}
+export function parseClaudeAgentFrontmatter(contents) {
+    if (!contents.startsWith('---\n'))
+        return { ok: false, reason: 'Missing YAML frontmatter.' };
+    const end = contents.indexOf('\n---\n', 4);
+    if (end < 0)
+        return { ok: false, reason: 'Unclosed YAML frontmatter.' };
+    const lines = contents.slice(4, end).split('\n');
+    const data = {};
+    for (const line of lines) {
+        const index = line.indexOf(':');
+        if (index <= 0)
+            return { ok: false, reason: `Invalid frontmatter line: ${line}` };
+        const key = line.slice(0, index).trim();
+        const value = line.slice(index + 1).trim();
+        data[key] = unquoteYamlScalar(value);
+    }
+    if (!data.name?.trim())
+        return { ok: false, reason: 'Frontmatter name is required.' };
+    if (!data.description?.trim())
+        return { ok: false, reason: 'Frontmatter description is required.' };
+    return { ok: true, data: { name: data.name, description: data.description } };
+}
+function inspectAgent(agent) {
+    if (!existsSync(agent.path))
+        return { agentName: agent.name, path: agent.path, exists: false, status: 'missing', frontmatter: 'missing', generatedMarker: false, detail: 'Expected Claude agent file is missing.' };
+    try {
+        const contents = readFileSync(agent.path, 'utf8');
+        const frontmatter = parseClaudeAgentFrontmatter(contents);
+        const generatedMarker = isVgxnessOwnedClaudeAgentMarkdown(contents);
+        if (!frontmatter.ok)
+            return { agentName: agent.name, path: agent.path, exists: true, status: 'invalid', frontmatter: 'invalid', generatedMarker, detail: frontmatter.reason };
+        if (frontmatter.data.name !== agent.name)
+            return { agentName: agent.name, path: agent.path, exists: true, status: 'conflicting', frontmatter: 'valid', generatedMarker, detail: `Frontmatter name ${frontmatter.data.name} does not match expected ${agent.name}.` };
+        if (!generatedMarker)
+            return { agentName: agent.name, path: agent.path, exists: true, status: 'conflicting', frontmatter: 'valid', generatedMarker, detail: 'Existing agent file is not marked as VGXNESS-generated.' };
+        return { agentName: agent.name, path: agent.path, exists: true, status: 'managed', frontmatter: 'valid', generatedMarker, detail: 'Claude agent file is VGXNESS-managed.' };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { agentName: agent.name, path: agent.path, exists: true, status: 'invalid', frontmatter: 'invalid', generatedMarker: false, detail: `Unable to read Claude agent file: ${message}` };
+    }
+}
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+function unquoteYamlScalar(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        try {
+            return value.startsWith('"') ? JSON.parse(value) : value.slice(1, -1).replaceAll("''", "'");
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}

package/dist/mcp/claude-code-cli.js

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+export function buildClaudeCodeMcpAddCommand(input = {}) {
+    const scope = resolveClaudeCodeScope(input.scope);
+    if (!scope.ok)
+        return scope;
+    const serverName = input.serverName ?? 'vgxness';
+    const command = input.command ?? 'vgxness';
+    const args = input.args ?? ['mcp', 'start'];
+    return commandEnvelope(['mcp', 'add', '--scope', scope.value.canonical, serverName, '--', command, ...args]);
+}
+export function buildClaudeCodeMcpAddJsonCommand(input) {
+    const scope = resolveClaudeCodeScope(input.scope);
+    if (!scope.ok)
+        return scope;
+    return commandEnvelope(['mcp', 'add-json', '--scope', scope.value.canonical, input.serverName ?? 'vgxness', sanitizeJsonArgument(input.json)]);
+}
+export async function runClaudeCodeCliCommand(command, runner = defaultClaudeCodeCliRunner) {
+    return runner(command);
+}
+export function createClaudeCodeCliRegistrationPreview(scope) {
+    const command = buildClaudeCodeMcpAddCommand({ scope });
+    return command.ok ? command.value.preview : ['claude', 'mcp', 'add', '--scope', scope, 'vgxness', '--', 'vgxness', 'mcp', 'start'];
+}
+function commandEnvelope(argv) {
+    return { ok: true, value: { executable: 'claude', argv, preview: ['claude', ...argv].map(redactArg), redacted: true } };
+}
+function sanitizeJsonArgument(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return JSON.stringify(redactUnknown(parsed));
+    }
+    catch {
+        return '<redacted-json>';
+    }
+}
+function redactUnknown(value) {
+    if (Array.isArray(value))
+        return value.map(redactUnknown);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const redacted = {};
+    for (const [key, nested] of Object.entries(value))
+        redacted[key] = /token|secret|password|key/i.test(key) ? '<redacted>' : redactUnknown(nested);
+    return redacted;
+}
+function redactArg(value) {
+    return /token|secret|password/i.test(value) ? '<redacted>' : value;
+}
+function defaultClaudeCodeCliRunner(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command.executable, command.argv, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (cause) => {
+            resolve({ command, exitCode: null, stdout: '', stderr: cause.message });
+        });
+        child.on('close', (exitCode) => {
+            resolve({ command, exitCode, stdout: redactOutput(stdout), stderr: redactOutput(stderr) });
+        });
+    });
+}
+function redactOutput(value) {
+    return value.replace(/(token|secret|password)=\S+/gi, '$1=<redacted>');
+}

package/dist/mcp/claude-code-config.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+export function resolveClaudeCodeMcpJsonPath(workspaceRoot) {
+    const target = resolve(workspaceRoot, '.mcp.json');
+    assertInsideWorkspace(workspaceRoot, target);
+    return target;
+}
+export function createClaudeCodeMcpServerConfig(databasePath, source = 'flag') {
+    return { type: 'stdio', command: 'vgxness', args: source === 'global-default' ? ['mcp', 'start'] : ['mcp', 'start', '--db', databasePath] };
+}
+export function createClaudeCodeMcpDoctorCommand(databasePath, source) {
+    return source === 'global-default' ? ['vgxness', 'mcp', 'doctor'] : ['vgxness', 'mcp', 'doctor', '--db', databasePath];
+}
+export function isManagedClaudeCodeMcpServer(value) {
+    return isRecord(value) && value.type === 'stdio' && value.command === 'vgxness' && isManagedClaudeArgs(value.args);
+}
+export function isManagedClaudeArgs(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string'))
+        return false;
+    const dbPath = value[3];
+    return arraysEqual(value, ['mcp', 'start']) || (value.length === 4 && value[0] === 'mcp' && value[1] === 'start' && value[2] === '--db' && typeof dbPath === 'string' && dbPath.trim().length > 0);
+}
+export function inspectClaudeCodeMcpConfig(workspaceRoot) {
+    const path = resolveClaudeCodeMcpJsonPath(workspaceRoot);
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, parsed: false, message: 'Claude project .mcp.json does not exist.' };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!isRecord(parsed))
+            return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude project .mcp.json must be a JSON object.' };
+        if (parsed.mcpServers !== undefined && !isRecord(parsed.mcpServers)) {
+            return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude project .mcp.json mcpServers must be a JSON object.' };
+        }
+        const entry = isRecord(parsed.mcpServers) ? parsed.mcpServers.vgxness : undefined;
+        if (entry === undefined)
+            return { status: 'stale', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json is readable but mcpServers.vgxness is missing.' };
+        if (isManagedClaudeCodeMcpServer(entry))
+            return { status: 'configured', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json has a managed mcpServers.vgxness entry.' };
+        return { status: 'conflicting', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json has a conflicting mcpServers.vgxness entry.' };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { status: 'invalid', path, exists: true, parsed: false, message: `Claude project .mcp.json could not be read or parsed: ${message}` };
+    }
+}
+export function mergeClaudeCodeMcpConfig(existing, server) {
+    return { ...existing, mcpServers: { ...(isRecord(existing.mcpServers) ? existing.mcpServers : {}), vgxness: server } };
+}
+export function claudeMcpConfigPathStatus(state) {
+    return {
+        label: 'project .mcp.json',
+        path: state.path,
+        exists: state.exists,
+        readable: state.status !== 'invalid',
+        parsed: state.parsed,
+        status: state.status === 'configured' ? 'pass' : state.status === 'invalid' || state.status === 'conflicting' ? 'fail' : 'not-configured',
+        detail: state.message,
+    };
+}
+export function claudeMcpEntryStatus(state) {
+    if (state.status === 'configured')
+        return { configured: true, status: 'pass', serverName: 'vgxness', enabled: true, detail: state.message };
+    if (state.status === 'conflicting')
+        return { configured: true, status: 'fail', serverName: 'vgxness', detail: state.message };
+    if (state.status === 'invalid')
+        return { configured: false, status: 'fail', serverName: 'vgxness', detail: state.message };
+    return { configured: false, status: 'not-configured', serverName: 'vgxness', detail: state.message };
+}
+export function assertInsideWorkspace(workspaceRoot, targetPath) {
+    const root = resolve(workspaceRoot);
+    const target = resolve(targetPath);
+    const rel = relative(root, target);
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || rel === '' && target !== root)
+        throw new Error(`Target path is outside workspace root: ${targetPath}`);
+}
+export function claudeAdvisoryPaths(workspaceRoot) {
+    return [join(workspaceRoot, '.claude', 'settings.json'), join(workspaceRoot, '.claude', 'settings.local.json'), join(workspaceRoot, '.claude', 'CLAUDE.md')];
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/mcp/claude-code-project-memory.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../agents/canonical-agent-projection.js';
+import { assertInsideWorkspace } from './claude-code-config.js';
+export const claudeProjectMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
+export const claudeProjectMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
+export function resolveClaudeProjectMemoryPath(workspaceRoot) {
+    const target = resolve(workspaceRoot, 'CLAUDE.md');
+    assertInsideWorkspace(workspaceRoot, target);
+    return target;
+}
+export function renderClaudeProjectMemoryBlock() {
+    const projection = projectCanonicalAgentManifestToClaudeProjectMemory();
+    return [
+        claudeProjectMemoryBeginMarker,
+        `<!-- VGXNESS-GENERATED owner=vgxness provider=claude artifact=claude-project-memory safe-update=true defaultAgent=${projection.defaultAgent} promptContractVersion=${projection.promptContractVersion} canonicalSource=canonical-agent-manifest repositoryInstructions=${projection.repositoryInstructions} -->`,
+        '',
+        '# VGXNESS Claude Project Memory',
+        '',
+        projection.guidance[0] ?? '',
+        '',
+        ...projection.guidance.slice(1).map((line) => `- ${line}`),
+        '',
+        claudeProjectMemoryEndMarker,
+    ].join('\n');
+}
+export function inspectClaudeProjectMemory(workspaceRoot) {
+    let path;
+    try {
+        path = resolveClaudeProjectMemoryPath(workspaceRoot);
+    }
+    catch (cause) {
+        return blocked(resolve(workspaceRoot, 'CLAUDE.md'), false, 'outside_workspace', cause instanceof Error ? cause.message : String(cause));
+    }
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, action: 'create', backupRequired: false, message: 'Claude project memory CLAUDE.md does not exist.' };
+    let contents;
+    try {
+        const bytes = readFileSync(path);
+        contents = bytes.toString('utf8');
+        if (!Buffer.from(contents, 'utf8').equals(bytes))
+            return blocked(path, true, 'non_utf8', 'Claude project memory is not valid UTF-8; refusing safe managed-block updates.');
+    }
+    catch (cause) {
+        return blocked(path, true, 'unreadable', `Claude project memory could not be read: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const beginCount = countOccurrences(contents, claudeProjectMemoryBeginMarker);
+    const endCount = countOccurrences(contents, claudeProjectMemoryEndMarker);
+    if (beginCount === 0 && endCount === 0)
+        return { status: 'unmanaged', path, exists: true, action: 'append-managed-block', backupRequired: true, message: 'Claude project memory exists without a VGXNESS managed block; future apply would append one after backup.', contents };
+    if (beginCount === 0)
+        return blocked(path, true, 'missing_begin_marker', 'Claude project memory has an end marker without a begin marker.');
+    if (endCount === 0)
+        return blocked(path, true, 'missing_end_marker', 'Claude project memory has a begin marker without an end marker.');
+    if (beginCount > 1 || endCount > 1)
+        return blocked(path, true, 'duplicate_markers', 'Claude project memory has duplicate VGXNESS managed-block markers.');
+    const start = contents.indexOf(claudeProjectMemoryBeginMarker);
+    const endMarkerStart = contents.indexOf(claudeProjectMemoryEndMarker);
+    if (endMarkerStart < start)
+        return blocked(path, true, 'reordered_markers', 'Claude project memory end marker appears before begin marker.');
+    const end = endMarkerStart + claudeProjectMemoryEndMarker.length;
+    const inner = contents.slice(start + claudeProjectMemoryBeginMarker.length, endMarkerStart);
+    if (inner.includes(claudeProjectMemoryBeginMarker) || inner.includes(claudeProjectMemoryEndMarker))
+        return blocked(path, true, 'nested_markers', 'Claude project memory has nested VGXNESS managed-block markers.');
+    const metadata = parseMetadata(inner);
+    if (metadata === undefined)
+        return blocked(path, true, 'invalid_metadata', 'Claude project memory managed block is missing VGXNESS metadata.');
+    const ownership = validateMetadataOwnership(metadata);
+    if (!ownership.ok)
+        return blocked(path, true, ownership.reason, ownership.message);
+    const expected = renderClaudeProjectMemoryBlock();
+    const actual = contents.slice(start, end);
+    if (actual === expected)
+        return { status: 'managed-current', path, exists: true, action: 'none', backupRequired: false, message: 'Claude project memory has the current VGXNESS managed block.', blockRange: { start, end }, contents };
+    return { status: 'managed-stale', path, exists: true, action: 'update-managed-block', backupRequired: true, message: 'Claude project memory has a stale VGXNESS managed block; future apply would update only that block after backup.', blockRange: { start, end }, staleReasons: ['managed_block_differs_from_canonical_render'], contents };
+}
+export function mergeClaudeProjectMemory(state) {
+    const block = renderClaudeProjectMemoryBlock();
+    if (state.status === 'missing')
+        return { ok: true, value: { path: state.path, contents: `${block}\n` } };
+    if (state.status === 'unmanaged') {
+        const separator = state.contents.length === 0 ? '' : state.contents.endsWith('\n') ? '\n' : '\n\n';
+        return { ok: true, value: { path: state.path, contents: `${state.contents}${separator}${block}\n` } };
+    }
+    if (state.status === 'managed-stale')
+        return { ok: true, value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) } };
+    if (state.status === 'managed-current')
+        return { ok: true, value: { path: state.path, contents: state.contents } };
+    return { ok: false, error: { code: 'validation_failed', message: state.message } };
+}
+function blocked(path, exists, reason, message) {
+    return { status: 'blocked', path, exists, action: 'blocked', backupRequired: false, reason, message };
+}
+function countOccurrences(contents, needle) {
+    let count = 0;
+    let index = contents.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = contents.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function parseMetadata(inner) {
+    const line = inner.split(/\r?\n/).find((item) => item.includes('VGXNESS-GENERATED'));
+    if (line === undefined)
+        return undefined;
+    const metadata = {};
+    for (const part of line.replace('<!--', '').replace('-->', '').trim().split(/\s+/)) {
+        const [key, value] = part.split('=');
+        if (key !== undefined && value !== undefined)
+            metadata[key] = value;
+    }
+    return metadata;
+}
+function validateMetadataOwnership(metadata) {
+    if (metadata['VGXNESS-GENERATED'] !== undefined)
+        return { ok: false, reason: 'invalid_metadata', message: 'Claude project memory metadata is malformed.' };
+    if (metadata.owner !== 'vgxness')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not owned by VGXNESS.' };
+    if (metadata.provider !== 'claude')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not for the Claude provider.' };
+    if (metadata.artifact !== 'claude-project-memory')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block has a conflicting artifact type.' };
+    if (metadata['safe-update'] !== 'true')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not marked safe for update.' };
+    return { ok: true };
+}

package/dist/mcp/claude-code-scope.js

@@ -0,0 +1,18 @@
+export const claudeCodeCanonicalScopes = ['local', 'project', 'user'];
+export function resolveClaudeCodeScope(input, fallback = 'project') {
+    if (input !== undefined && input.trim().length === 0)
+        return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+    const raw = input?.trim() || fallback;
+    if (raw === 'local' || raw === 'project' || raw === 'user')
+        return { ok: true, value: { canonical: raw, input: raw, warnings: [] } };
+    if (raw === 'personal') {
+        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code scope `personal` is accepted for VGXNESS compatibility and maps to Claude `user`.'] } };
+    }
+    if (raw === 'global') {
+        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code legacy scope `global` is deprecated and maps to Claude `user`.'] } };
+    }
+    return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+}
+export function isClaudeCodeUserScope(scope) {
+    return scope === 'user';
+}

package/dist/mcp/client-install-claude-code-contract.js

@@ -0,0 +1,114 @@
+import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
+import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
+import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
+import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+export function planClaudeCodeMcpInstall(input) {
+    const source = input.databasePathSource ?? 'flag';
+    const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
+    const overwriteVgxness = input.overwriteVgxness === true;
+    const resolvedScope = resolveClaudeCodeScope(input.scope);
+    if (!resolvedScope.ok)
+        return refused(input, server, 'unsupported_scope', resolvedScope.error.message, [], [], overwriteVgxness);
+    const cliCommand = buildClaudeCodeMcpAddCommand({ scope: resolvedScope.value.canonical });
+    if (!cliCommand.ok)
+        return refused(input, server, 'unsupported_scope', cliCommand.error.message, [], [], overwriteVgxness);
+    if (resolvedScope.value.canonical !== 'project') {
+        const targets = [{ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' }];
+        return { ...base(input, server, targets, [], false, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings), status: 'would_install' };
+    }
+    let mcpPath;
+    try {
+        mcpPath = resolveClaudeCodeMcpJsonPath(input.cwd);
+    }
+    catch (cause) {
+        return refused(input, server, 'outside_workspace', cause instanceof Error ? cause.message : String(cause), [], [], overwriteVgxness);
+    }
+    const mcpState = inspectClaudeCodeMcpConfig(input.cwd);
+    const targets = [];
+    targets.push({ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' });
+    const preservedTopLevelKeys = mcpState.parsed ? Object.keys(mcpState.config) : [];
+    if (mcpState.status === 'missing')
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'create' });
+    else if (mcpState.status === 'stale')
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'merge' });
+    else if (mcpState.status === 'configured')
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'update-vgxness' });
+    else
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'blocked', reason: mcpState.message });
+    const agentInspection = inspectClaudeCodeAgents(input.cwd);
+    for (const agent of agentInspection.agents) {
+        if (agent.status === 'missing')
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'create' });
+        else if (agent.status === 'managed')
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'update-vgxness' });
+        else
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'blocked', reason: agent.detail });
+    }
+    const projectMemory = inspectClaudeProjectMemory(input.cwd);
+    targets.push({ kind: 'project-memory', path: projectMemory.path, action: projectMemory.action, status: projectMemory.status, backupRequired: projectMemory.backupRequired, ...(projectMemory.status === 'blocked' ? { reason: projectMemory.message } : {}) });
+    const blocked = targets.find((target) => target.action === 'blocked');
+    if (blocked !== undefined) {
+        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : blocked.kind === 'project-memory' ? projectMemoryRefusalReason(projectMemory) : 'existing_vgxness_agent';
+        return refused(input, server, reason, blocked.reason ?? 'Claude Code install plan is blocked by an existing conflicting target.', targets, preservedTopLevelKeys, overwriteVgxness);
+    }
+    const backupRequired = targets.some((target) => (target.kind === 'mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness') || (target.kind === 'project-memory' && target.backupRequired));
+    return {
+        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings),
+        status: 'would_install',
+    };
+}
+export function expectedClaudeCodeRenderedAgents(workspaceRoot) {
+    return expectedClaudeCodeAgentFiles(workspaceRoot).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
+}
+function refused(input, server, reason, message, targets, preservedTopLevelKeys, overwriteVgxness) {
+    const resolved = resolveClaudeCodeScope(input.scope);
+    const canonical = resolved.ok ? resolved.value.canonical : 'project';
+    const cli = buildClaudeCodeMcpAddCommand({ scope: canonical });
+    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []), status: 'refused', reason, message };
+}
+function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, canonicalClaudeScope, cliCommand, scopeWarnings) {
+    const source = input.databasePathSource ?? 'flag';
+    const targetPath = canonicalClaudeScope === 'project' ? resolveClaudeCodeMcpJsonPath(input.cwd) : `claude-cli:${canonicalClaudeScope}:vgxness`;
+    return {
+        version: 1,
+        kind: 'mcp-client-install-claude-code',
+        installable: true,
+        mutating: false,
+        provider: 'claude',
+        scope: input.scope ?? 'project',
+        targetPath,
+        targets,
+        backupRequired,
+        safety: { operation: 'plan', mutating: false, writesProviderConfig: false, targetPath, backupRequired, mergePolicy: backupRequired ? 'merge-preserve-existing' : 'create' },
+        warnings: [
+            ...scopeWarnings,
+            'Claude Code MCP registration is modeled as Claude CLI argv, never shell strings or manual ~/.claude.json mutation.',
+            'Project compatibility may write .mcp.json, .claude/agents/*.md, and a guarded project-root CLAUDE.md managed block after explicit confirmation/preflight; user/local scopes do not inspect or write private Claude config.',
+            'VGXNESS never manually writes ~/.claude.json or .claude/CLAUDE.md; project-root CLAUDE.md is only touched through the guarded project install managed block.',
+        ],
+        verificationHints: [
+            { kind: 'restart-client', message: 'Restart or reload Claude Code after confirmed project config installation.' },
+            { kind: 'manual-check', message: 'Open the project in Claude Code and verify the vgxness MCP server and project agents are visible.' },
+            { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createClaudeCodeMcpDoctorCommand(input.databasePath, source) },
+        ],
+        server,
+        ...(cliCommand === undefined ? {} : { cliCommand }),
+        canonicalClaudeScope,
+        preservedTopLevelKeys,
+        agentNames: targets.filter((target) => target.kind === 'agent-file').map((target) => target.agentName),
+        overwriteVgxness,
+    };
+}
+function mcpRefusalReason(status) {
+    if (status === 'invalid')
+        return 'malformed_json';
+    if (status === 'conflicting')
+        return 'existing_vgxness_mcp';
+    return 'invalid_mcp_shape';
+}
+function projectMemoryRefusalReason(state) {
+    if (state.status === 'blocked' && state.reason === 'conflicting_ownership')
+        return 'conflicting_claude_project_memory';
+    return 'malformed_claude_project_memory';
+}