vgxness 1.21.1 → 1.21.2

package/dist/adapters/opencode/install/client-install-opencode-contract.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, } from './opencode-default-agent-config.js';
+import { planVgxnessPathProfileUpdate, resolveVgxnessPathEnvironment, } from './vgxness-path-environment.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 const opencodeUserGlobalOnlyMessage = 'VGX-managed OpenCode configuration is user-global only. Project/local OpenCode files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';
 export function resolveOpenCodeMcpInstallTarget(input) {
@@ -40,7 +41,7 @@ export function planOpenCodeMcpInstall(input) {
     if (scope === 'user') {
         return planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy);
     }
-    return refusal('unsupported_config_shape', opencodeUserGlobalOnlyMessage, input.databasePath, databasePathSource, scope, undefined, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+    return refusal('unsupported_config_shape', opencodeUserGlobalOnlyMessage, input.databasePath, databasePathSource, scope, undefined, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
 }
 function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan, overwriteVgxness, bashPermissionPolicy) {
     const target = resolveOpenCodeMcpInstallTarget({
@@ -49,15 +50,15 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
         env: input.env,
     });
     if (!target.ok) {
-        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user', undefined, [], undefined, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_config_shape', target.message, input.databasePath, databasePathSource, 'user', undefined, [], undefined, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     const jsoncPath = `${target.path}c`;
     if (existsSync(jsoncPath)) {
-        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_jsonc', 'OpenCode user JSONC config opencode.jsonc is not supported yet; use JSON or remove comments first.', input.databasePath, databasePathSource, 'user', jsoncPath, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (!existsSync(target.path)) {
         return {
-            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan, overwriteVgxness, bashPermissionPolicy),
+            ...baseContract(input.databasePath, databasePathSource, 'user', target.path, false, 'create', agentPlan, overwriteVgxness, bashPermissionPolicy, input.env),
             status: 'would_install',
             action: 'create',
             targetPath: target.path,
@@ -69,13 +70,13 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
     }
     const parsed = parseConfig(target.path);
     if (!parsed.ok)
-        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal(parsed.reason, parsed.message, input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     const config = parsed.value;
     if (config.mcp !== undefined && !isRecord(config.mcp)) {
-        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('invalid_mcp_shape', 'Existing top-level mcp must be a JSON object before vgxness can be merged.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (isRecord(config.mcp) && Object.hasOwn(config.mcp, 'vgxness') && !overwriteVgxness) {
-        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('existing_vgxness_mcp', 'Existing OpenCode config already contains mcp.vgxness; overwrite is refused by default.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     const agentConflict = findConflictingVgxnessAgents(config, agentPlan);
     if (agentConflict.length > 0 && !overwriteVgxness) {
@@ -84,16 +85,16 @@ function planUserOpenCodeMcpInstall(input, databasePathSource, server, agentPlan
                 kind: 'manual-check',
                 message: `Manually reconcile conflicting VGXNESS agent entries: ${agentConflict.join(', ')}.`,
             },
-        ], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        ], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (agentPlan.installsAgents && config.agent !== undefined && !isRecord(config.agent)) {
-        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_config_shape', 'Existing top-level agent must be a JSON object before VGXNESS agent entries can be merged or overwritten.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     if (config.permission !== undefined && !isRecord(config.permission)) {
-        return refusal('unsupported_config_shape', 'Existing top-level permission must be a JSON object before VGXNESS can set top-level permission.bash to ask.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy);
+        return refusal('unsupported_config_shape', 'Existing top-level permission must be a JSON object before VGXNESS can set top-level permission.bash to ask.', input.databasePath, databasePathSource, 'user', target.path, [], agentPlan, overwriteVgxness, bashPermissionPolicy, input.env);
     }
     return {
-        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan, overwriteVgxness, bashPermissionPolicy),
+        ...baseContract(input.databasePath, databasePathSource, 'user', target.path, true, 'merge-preserve-existing', agentPlan, overwriteVgxness, bashPermissionPolicy, input.env),
         status: 'would_install',
         action: 'merge',
         targetPath: target.path,
@@ -157,7 +158,9 @@ function deepEqual(left, right) {
     const rightKeys = Object.keys(right).sort();
     return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index] && deepEqual(left[key], right[key]));
 }
-function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {
+function baseContract(databasePath, source, scope, targetPath, backupRequired, mergePolicy, agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan), env) {
+    const pathEnvironment = resolveVgxnessPathEnvironment({ env });
+    const pathProfileUpdate = planVgxnessPathProfileUpdate({ env });
     return {
         version: 1,
         kind: 'mcp-client-install-opencode',
@@ -172,18 +175,20 @@ function baseContract(databasePath, source, scope, targetPath, backupRequired, m
             mergePolicy,
         },
         scope,
-        warnings: warningsForScope(scope, overwriteVgxness, agentPlan, bashPermissionPolicy),
-        verificationHints: verificationHints(databasePath, source),
+        warnings: warningsForScope(scope, overwriteVgxness, agentPlan, bashPermissionPolicy, pathEnvironment),
+        verificationHints: verificationHints(databasePath, source, pathEnvironment),
         manualTest: manualTestForScope(scope, databasePath, source),
         installsAgents: agentPlan.installsAgents,
         agentNames: agentPlan.agentNames,
         overwriteVgxness,
         bashPermissionPolicy,
+        pathEnvironment,
+        ...(pathProfileUpdate.supported && pathProfileUpdate.changed ? { pathProfileUpdate } : {}),
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }
-function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {
-    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan, overwriteVgxness, bashPermissionPolicy);
+function refusal(reason, message, databasePath, source, scope, targetPath, extraVerificationHints = [], agentPlan = createOpenCodeDefaultAgentInstallPlan({ mcpOnly: true }), overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan), env) {
+    const contract = baseContract(databasePath, source, scope, targetPath, false, 'refuse-no-clobber', agentPlan, overwriteVgxness, bashPermissionPolicy, env);
     return {
         ...contract,
         verificationHints: [...extraVerificationHints, ...contract.verificationHints],
@@ -193,7 +198,7 @@ function refusal(reason, message, databasePath, source, scope, targetPath, extra
         ...(targetPath !== undefined ? { targetPath } : {}),
     };
 }
-function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPolicy) {
+function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPolicy, pathEnvironment) {
     const overwriteWarnings = overwriteVgxness
         ? [
             `Reinstall/overwrite is enabled: existing VGXNESS-managed OpenCode entries will be replaced (${agentPlan.installsAgents ? 'mcp.vgxness, default_agent, instructions AGENTS.md, and known VGXNESS agents' : 'mcp.vgxness only'}); unrelated OpenCode config is preserved.`,
@@ -207,6 +212,7 @@ function warningsForScope(_scope, overwriteVgxness, agentPlan, bashPermissionPol
     return [
         'Restart OpenCode after installation so it reloads the user MCP config.',
         'OpenCode project config may override user config for a workspace; check project-level config if vgxness is not visible.',
+        ...pathEnvironment.warnings,
         ...overwriteWarnings,
         ...bashWarnings,
     ];
@@ -225,7 +231,7 @@ function manualTestForScope(_scope, databasePath, source) {
         doctorCommand: createVgxnessMcpDoctorCommand(databasePath, source),
     };
 }
-function verificationHints(databasePath, source) {
+function verificationHints(databasePath, source, pathEnvironment) {
     return [
         {
             kind: 'restart-client',
@@ -240,5 +246,6 @@ function verificationHints(databasePath, source) {
             message: 'Run the MCP doctor command after installation.',
             command: createVgxnessMcpDoctorCommand(databasePath, source),
         },
+        ...(pathEnvironment.vgxness.onPath ? [] : pathEnvironment.remediation.map((message) => ({ kind: 'manual-check', message }))),
     ];
 }

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

@@ -3,6 +3,7 @@ import { dirname, join } from 'node:path';
 import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createManagedProviderConfigBackup } from '../../../setup/backup-rollback-service.js';
 import { findConflictingVgxnessAgents, planOpenCodeMcpInstall, } from './client-install-opencode-contract.js';
+import { applyVgxnessPathProfileUpdate } from './vgxness-path-environment.js';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, createOpenCodeGlobalInstructionsContent, createOpenCodeGlobalInstructionsManagedBlock, vgxnessOpenCodeGlobalInstructionsBlockEnd, vgxnessOpenCodeGlobalInstructionsBlockStart, vgxnessOpenCodeInstructionsPath, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 export { createInstalledVgxnessMcpServerCommand };
@@ -50,7 +51,8 @@ export async function installOpenCodeMcpClient(input) {
             return refusal('post_write_validation_failed', globalInstructions.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
         writeConfig(plan.targetPath, mergeVgxnessOpenCodeConfig({ $schema: opencodeConfigSchema }, plan.server, plan.installsAgents, input.effectiveManagerInstructions));
         writeOpenCodeGlobalInstructions(globalInstructions.value);
-        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
+        const pathProfileUpdate = applyVgxnessPathProfileUpdate({ env: input.env });
+        return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy, plan.pathEnvironment, pathProfileUpdate);
     }
     const parsed = parseConfig(plan.targetPath);
     if (!parsed.ok)
@@ -70,7 +72,8 @@ export async function installOpenCodeMcpClient(input) {
     const mergedConfig = mergeVgxnessOpenCodeConfig({ ...config, $schema: plan.existingSchema ?? opencodeConfigSchema }, plan.server, plan.installsAgents, input.effectiveManagerInstructions);
     writeConfig(plan.targetPath, mergedConfig);
     writeOpenCodeGlobalInstructions(globalInstructions.value);
-    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
+    const pathProfileUpdate = applyVgxnessPathProfileUpdate({ env: input.env });
+    return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy, plan.pathEnvironment, pathProfileUpdate);
 }
 function mergeVgxnessOpenCodeConfig(config, server, installsAgents, effectiveManagerInstructions) {
     const merged = {
@@ -174,7 +177,7 @@ function createBackup(path, scope, allowedManagedHome, override) {
         ...(allowedManagedHome !== undefined ? { allowedManagedHome } : {}),
     });
 }
-function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan)) {
+function validateInstalledResult(targetPath, backup, server, databasePath, source, safety, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness = false, bashPermissionPolicy = bashPermissionPolicyFor(agentPlan), pathEnvironment, pathProfileUpdate) {
     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, overwriteVgxness, bashPermissionPolicy);
@@ -212,6 +215,8 @@ function validateInstalledResult(targetPath, backup, server, databasePath, sourc
         agentNames: agentPlan.agentNames,
         overwriteVgxness,
         bashPermissionPolicy,
+        pathEnvironment,
+        ...(pathProfileUpdate.supported ? { pathProfileUpdate } : {}),
         ...(agentPlan.defaultAgent !== undefined ? { defaultAgent: agentPlan.defaultAgent } : {}),
     };
 }

package/dist/adapters/opencode/install/opencode-visibility.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { SUPPORTED_VGX_MCP_TOOL_NAMES } from '../../../mcp/schema.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
+import { resolveVgxnessPathEnvironment } from './vgxness-path-environment.js';
 const serverName = 'vgxness';
 const expectedToolCount = SUPPORTED_VGX_MCP_TOOL_NAMES.length;
 export function createOpenCodeMcpVisibilityReport(options) {
@@ -17,6 +18,7 @@ export function createOpenCodeMcpVisibilityReport(options) {
     const userReport = userTarget.ok ? userVisibilityReport(userTarget.path, projectVisibleFromCurrentCwd) : undefined;
     const selectedTargetPath = userTarget.ok ? userTarget.path : '$HOME/.config/opencode/opencode.json';
     const selectedReady = targetScope === 'user' ? userReport?.configExists === true && userReport.hasVgxnessServer : projectVisibleFromCurrentCwd;
+    const pathEnvironment = resolveVgxnessPathEnvironment({ env: options.env });
     return {
         version: 1,
         kind: 'mcp-doctor-opencode-visibility',
@@ -36,6 +38,7 @@ export function createOpenCodeMcpVisibilityReport(options) {
         },
         visibility: { cwdInsideProject, configExists: projectConfigExists, hasVgxnessServer: projectHasVgxnessServer },
         expected: { serverName, toolCount: expectedToolCount, visibleFromCurrentCwd: selectedReady },
+        pathEnvironment,
         guidance: buildGuidance({
             cwdInsideProject,
             configExists: projectConfigExists,

package/dist/adapters/opencode/install/vgxness-path-environment.js

@@ -0,0 +1,186 @@
+import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, extname, join, resolve } from 'node:path';
+export const vgxnessPathProfileBlockStart = '# >>> VGXNESS managed PATH >>>';
+export const vgxnessPathProfileBlockEnd = '# <<< VGXNESS managed PATH <<<';
+export function resolveVgxnessPathEnvironment(input) {
+    const env = input.env ?? process.env;
+    const home = homeFromEnv(env);
+    const pathEntries = splitPath(Object.hasOwn(env, 'PATH') ? env.PATH : process.env.PATH, home);
+    const bunGlobalBinPath = bunGlobalBin(env, home);
+    const vgxness = resolveCommandOnPath('vgxness', pathEntries);
+    const opencodeCli = resolveCommandOnPath('opencode', pathEntries);
+    const bunGlobalBinStatus = {
+        path: bunGlobalBinPath,
+        exists: existsSync(bunGlobalBinPath),
+        onPath: pathEntries.some((entry) => samePath(entry, bunGlobalBinPath)),
+        hasVgxnessExecutable: resolveCommandInDirectory('vgxness', bunGlobalBinPath).onPath,
+    };
+    const warnings = pathWarnings(vgxness, bunGlobalBinStatus);
+    return {
+        command: 'vgxness',
+        pathEntries,
+        vgxness,
+        opencodeCli,
+        bunGlobalBin: bunGlobalBinStatus,
+        warnings,
+        remediation: pathRemediation(vgxness, bunGlobalBinStatus, opencodeCli),
+    };
+}
+export function planVgxnessPathProfileUpdate(input) {
+    const env = input.env ?? process.env;
+    const home = homeFromEnv(env);
+    const targetBinDir = bunGlobalBin(env, home);
+    const managedBlock = createManagedPathBlock(targetBinDir, home);
+    if (home === undefined) {
+        return {
+            supported: false,
+            changed: false,
+            backupRequired: false,
+            managedBlock,
+            reason: 'HOME is not set; VGXNESS cannot safely update a shell profile PATH block.',
+            targetBinDir,
+        };
+    }
+    const profilePath = shellProfilePath(env, home);
+    const existing = existsSync(profilePath) ? readFileSync(profilePath, 'utf8') : undefined;
+    const nextContent = reconcileManagedPathBlock(existing, managedBlock);
+    const pathEnvironment = resolveVgxnessPathEnvironment({ env });
+    const blockExists = existing?.includes(vgxnessPathProfileBlockStart) === true || existing?.includes(vgxnessPathProfileBlockEnd) === true;
+    const shouldEnsureProfile = blockExists || (!pathEnvironment.vgxness.onPath && !pathEnvironment.bunGlobalBin.onPath);
+    const changed = shouldEnsureProfile && existing !== nextContent;
+    return {
+        supported: true,
+        changed,
+        backupRequired: changed && existing !== undefined,
+        managedBlock,
+        reason: changed
+            ? 'A VGXNESS-managed shell PATH block is planned so path-based OpenCode MCP command `vgxness mcp start` can resolve after restarting terminal/OpenCode.'
+            : 'No shell profile PATH update is needed for the current environment.',
+        profilePath,
+        targetBinDir,
+    };
+}
+export function applyVgxnessPathProfileUpdate(input) {
+    const plan = planVgxnessPathProfileUpdate(input);
+    if (!plan.supported || !plan.changed || plan.profilePath === undefined)
+        return plan;
+    const existing = existsSync(plan.profilePath) ? readFileSync(plan.profilePath, 'utf8') : undefined;
+    const backupPath = existing === undefined ? undefined : createProfileBackup(plan.profilePath);
+    if (backupPath !== undefined)
+        copyFileSync(plan.profilePath, backupPath);
+    mkdirSync(dirname(plan.profilePath), { recursive: true });
+    writeFileSync(plan.profilePath, reconcileManagedPathBlock(existing, plan.managedBlock));
+    return { ...plan, ...(backupPath === undefined ? {} : { backupPath }) };
+}
+function pathWarnings(vgxness, bunGlobalBinStatus) {
+    if (vgxness.onPath)
+        return [];
+    return [
+        `PATH-based OpenCode MCP command \`vgxness mcp start\` may fail because \`vgxness\` was not found on the current PATH. OpenCode may report "Executable not found in $PATH" until ${bunGlobalBinStatus.path} is on PATH.`,
+    ];
+}
+function pathRemediation(vgxness, bunGlobalBinStatus, opencodeCli) {
+    const steps = vgxness.onPath
+        ? ['`vgxness` resolves from the current PATH; keep OpenCode config path-based as `vgxness mcp start`.']
+        : [
+            'Keep OpenCode config portable as `mcp.vgxness.command: ["vgxness", "mcp", "start"]`; do not replace it with an absolute binary path by default.',
+            `Add Bun global binaries to your shell PATH, for example: export PATH="$HOME/.bun/bin:$PATH" (${bunGlobalBinStatus.path}).`,
+            'Restart terminal/OpenCode after PATH profile changes so the provider process inherits the updated PATH.',
+        ];
+    return opencodeCli.onPath
+        ? [...steps, 'After restarting, verify with `opencode mcp list` and confirm the `vgxness` server is listed.']
+        : [...steps, 'Skipped `opencode mcp list` verification because the OpenCode CLI was not found on the current PATH.'];
+}
+function createManagedPathBlock(targetBinDir, home) {
+    const pathExpression = home !== undefined && samePath(targetBinDir, join(home, '.bun', 'bin')) ? '$HOME/.bun/bin' : targetBinDir;
+    return [
+        vgxnessPathProfileBlockStart,
+        '# Ensures OpenCode can resolve the path-based VGXNESS MCP command.',
+        `export PATH="${pathExpression}:$PATH"`,
+        vgxnessPathProfileBlockEnd,
+    ].join('\n');
+}
+function reconcileManagedPathBlock(existing, managedBlock) {
+    if (existing === undefined || existing.length === 0)
+        return `${managedBlock}\n`;
+    const start = existing.indexOf(vgxnessPathProfileBlockStart);
+    const end = existing.indexOf(vgxnessPathProfileBlockEnd);
+    if (start >= 0 && end >= start) {
+        const afterEnd = end + vgxnessPathProfileBlockEnd.length;
+        return `${existing.slice(0, start).trimEnd()}\n\n${managedBlock}\n${existing.slice(afterEnd).trimStart()}`;
+    }
+    return `${existing.trimEnd()}\n\n${managedBlock}\n`;
+}
+function shellProfilePath(env, home) {
+    const explicit = env.VGXNESS_SHELL_PROFILE;
+    if (explicit !== undefined && explicit.trim().length > 0)
+        return resolve(home, explicit);
+    const shell = env.SHELL ?? '';
+    if (shell.endsWith('/zsh') || shell === 'zsh')
+        return join(home, '.zshrc');
+    if (shell.endsWith('/bash') || shell === 'bash')
+        return join(home, '.bashrc');
+    return join(home, '.profile');
+}
+function createProfileBackup(profilePath) {
+    const stamp = new Date().toISOString().replaceAll('-', '').replaceAll(':', '').replace(/\.\d{3}Z$/, 'Z');
+    return `${profilePath}.backup-${stamp}-vgxness-path`;
+}
+function bunGlobalBin(env, home) {
+    const bunInstall = env.BUN_INSTALL;
+    if (bunInstall !== undefined && bunInstall.trim().length > 0)
+        return resolve(expandHome(bunInstall, home), 'bin');
+    return home === undefined ? resolve('.bun', 'bin') : join(home, '.bun', 'bin');
+}
+function homeFromEnv(env) {
+    const home = env.HOME;
+    return home === undefined || home.trim().length === 0 ? undefined : home;
+}
+function splitPath(pathValue, home) {
+    if (pathValue === undefined || pathValue.length === 0)
+        return [];
+    return pathValue
+        .split(delimiter)
+        .filter((entry) => entry.length > 0)
+        .map((entry) => resolve(expandHome(entry, home)));
+}
+function expandHome(pathValue, home) {
+    if (home !== undefined && (pathValue === '~' || pathValue.startsWith('~/')))
+        return join(home, pathValue.slice(2));
+    return pathValue;
+}
+function resolveCommandOnPath(command, pathEntries) {
+    for (const pathEntry of pathEntries) {
+        const resolved = resolveCommandInDirectory(command, pathEntry);
+        if (resolved.onPath)
+            return resolved;
+    }
+    return { onPath: false };
+}
+function resolveCommandInDirectory(command, directory) {
+    for (const candidateName of commandCandidateNames(command)) {
+        const candidate = join(directory, candidateName);
+        if (isExecutable(candidate))
+            return { onPath: true, resolvedPath: candidate };
+    }
+    return { onPath: false };
+}
+function commandCandidateNames(command) {
+    if (process.platform !== 'win32' || extname(command).length > 0)
+        return [command];
+    return [command, `${command}.cmd`, `${command}.exe`, `${command}.bat`, `${command}.ps1`];
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function samePath(left, right) {
+    const resolvedLeft = resolve(left);
+    const resolvedRight = resolve(right);
+    return process.platform === 'win32' ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase() : resolvedLeft === resolvedRight;
+}

package/dist/interfaces/cli/setup-plan-renderer.js

@@ -22,6 +22,11 @@ function renderOpenCode(plan) {
         field('Installs agents', yesNo(plan.opencode.installsAgents)),
         field('Reinstall entries', yesNo(plan.opencode.overwriteVgxness === true)),
         field('Bash policy', formatBashPermissionPolicy(plan.opencode.bashPermissionPolicy)),
+        field('VGXNESS on PATH', yesNo(plan.opencode.pathEnvironment.vgxness.onPath)),
+        field('Bun bin on PATH', yesNo(plan.opencode.pathEnvironment.bunGlobalBin.onPath)),
+        ...(plan.opencode.pathProfileUpdate === undefined
+            ? []
+            : [field('PATH profile', `${plan.opencode.pathProfileUpdate.changed ? 'planned' : 'unchanged'} — ${plan.opencode.pathProfileUpdate.profilePath ?? 'not supported'}`)]),
         field('Agent names', plan.opencode.agentNames.length === 0 ? 'none' : plan.opencode.agentNames.join(', ')),
     ], { status });
 }

package/dist/setup/setup-plan.js

@@ -141,6 +141,8 @@ function setupPlanFromOpenCode(input) {
                 agentNames: input.opencode.agentNames,
                 ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
                 bashPermissionPolicy: input.opencode.bashPermissionPolicy,
+                pathEnvironment: input.opencode.pathEnvironment,
+                ...(input.opencode.pathProfileUpdate === undefined ? {} : { pathProfileUpdate: input.opencode.pathProfileUpdate }),
             },
             actions: [],
             conflicts: [
@@ -171,6 +173,8 @@ function setupPlanFromOpenCode(input) {
             agentNames: input.opencode.agentNames,
             ...(input.opencode.overwriteVgxness ? { overwriteVgxness: true } : {}),
             bashPermissionPolicy: input.opencode.bashPermissionPolicy,
+            pathEnvironment: input.opencode.pathEnvironment,
+            ...(input.opencode.pathProfileUpdate === undefined ? {} : { pathProfileUpdate: input.opencode.pathProfileUpdate }),
         },
         actions: [
             {
@@ -180,18 +184,22 @@ function setupPlanFromOpenCode(input) {
                 targetPath: input.opencode.targetPath,
                 backupRequired: input.opencode.backupRequired,
             },
+            ...pathProfileUpdateActions(input.opencode.pathProfileUpdate),
         ],
         conflicts: [],
-        backupsPlanned: input.opencode.backupRequired
-            ? [
-                {
-                    targetPath: input.opencode.targetPath,
-                    reason: input.opencode.overwriteVgxness
-                        ? 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before VGXNESS entries are overwritten/reinstalled.'
-                        : 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
-                },
-            ]
-            : [],
+        backupsPlanned: [
+            ...(input.opencode.backupRequired
+                ? [
+                    {
+                        targetPath: input.opencode.targetPath,
+                        reason: input.opencode.overwriteVgxness
+                            ? 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before VGXNESS entries are overwritten/reinstalled.'
+                            : 'Existing OpenCode config would receive a managed VGXNESS backup with rollback metadata before merge.',
+                    },
+                ]
+                : []),
+            ...pathProfileUpdateBackups(input.opencode.pathProfileUpdate),
+        ],
         nextCommands: [
             input.opencode.overwriteVgxness ? 'vgxness setup reinstall --yes' : 'vgxness setup apply --yes',
             'vgxness doctor',
@@ -202,6 +210,29 @@ function setupPlanFromOpenCode(input) {
 function bashPermissionDescription(policy) {
     return policy.manager === 'deny' ? '; sets top-level permission.bash to ask and manager bash to deny' : '; sets top-level permission.bash to ask';
 }
+function pathProfileUpdateActions(update) {
+    if (update === undefined || !update.supported || !update.changed || update.profilePath === undefined)
+        return [];
+    return [
+        {
+            id: 'opencode-path-profile-update',
+            description: `${update.reason} Target shell profile: ${update.profilePath}`,
+            mutating: false,
+            targetPath: update.profilePath,
+            backupRequired: update.backupRequired,
+        },
+    ];
+}
+function pathProfileUpdateBackups(update) {
+    if (update === undefined || !update.supported || !update.changed || !update.backupRequired || update.profilePath === undefined)
+        return [];
+    return [
+        {
+            targetPath: update.profilePath,
+            reason: 'Existing shell profile would receive a managed VGXNESS backup before updating the PATH block used by the path-based OpenCode MCP command.',
+        },
+    ];
+}
 function resolveSetupDatabase(input) {
     if (input.mode === 'global') {
         const resolved = resolveMemoryDatabasePath({ cwd: input.workspaceRoot, env: input.env });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.21.1",
+  "version": "1.21.2",
   "description": "Local-first governance OS, CLI and MCP control plane for existing coding agents, SDD, memory, runs, permissions, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {