@wavexzore/sandbox 0.1.0

package/dist/sandbox/cli/local-store.js

@@ -0,0 +1,604 @@
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'fs';
+import { basename, dirname, join, relative, resolve } from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { defaultHome, isDirectoryOnPath, pathHintForPlatform, powershellSingleQuote, resolveWavexzoreSandboxBinDir, resolveWavexzoreSandboxHomeDir, runtimeEnv, runtimePlatform, shellProfilePath, shellQuote, } from './path.js';
+import { OPENCODE_HELPER_CLI, WAVEXZORE_SANDBOX_CLI, WAVEXZORE_SANDBOX_LOADER_PACKAGE, WAVEXZORE_SANDBOX_PACKAGE, WAVEXZORE_SANDBOX_PLUGIN_ID, } from './types.js';
+const require = createRequire(import.meta.url);
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+export function nowIso(now = Date.now()) {
+    return new Date(now).toISOString();
+}
+function ensureParent(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+export function writeFileAtomic(path, contents, dryRun) {
+    if (dryRun)
+        return;
+    ensureParent(path);
+    const tmp = join(dirname(path), `.${basename(path)}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        writeFileSync(tmp, contents, 'utf8');
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Ignore best-effort cleanup failures.
+        }
+        throw error;
+    }
+}
+export function writeJsonAtomic(path, value, dryRun) {
+    writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`, dryRun);
+}
+export function statusForText(path, desired) {
+    if (!existsSync(path))
+        return 'created';
+    return readFileSync(path, 'utf8') === desired ? 'existing' : 'updated';
+}
+function combineInstallStatus(statuses) {
+    return statuses.includes('created') ? 'created' : statuses.includes('updated') ? 'updated' : 'existing';
+}
+function combineUninstallStatus(statuses) {
+    if (statuses.includes('removed'))
+        return 'removed';
+    if (statuses.includes('updated'))
+        return 'updated';
+    if (statuses.includes('kept'))
+        return 'kept';
+    if (statuses.includes('skipped'))
+        return 'skipped';
+    if (statuses.includes('unchanged'))
+        return 'unchanged';
+    return 'missing';
+}
+export function assertSafeVersion(version) {
+    if (!version || !/^[0-9A-Za-z._+-]+$/.test(version) || version.includes('..')) {
+        throw new Error(`Unsafe package version for local store path: ${version}`);
+    }
+}
+export function resolveWavexzoreSandboxManifestPath(storeDir) {
+    return join(storeDir, 'manifest.json');
+}
+export function resolveWavexzoreSandboxLoaderDir(storeDir) {
+    return join(storeDir, 'opencode-plugin');
+}
+export function resolveWavexzoreSandboxVersionDir(storeDir, version) {
+    assertSafeVersion(version);
+    return join(storeDir, 'versions', version);
+}
+export function pathToPluginFileSpec(loaderDir) {
+    return pathToFileURL(loaderDir).href;
+}
+export function resolveWavexzoreSandboxBinShimPaths(binDir) {
+    return {
+        js: join(binDir, `${WAVEXZORE_SANDBOX_CLI}.mjs`),
+        unix: join(binDir, WAVEXZORE_SANDBOX_CLI),
+        cmd: join(binDir, `${WAVEXZORE_SANDBOX_CLI}.cmd`),
+    };
+}
+export function resolveOpenCodeHelperPath(binDir, platform = runtimePlatform()) {
+    return join(binDir, platform === 'win32' ? `${OPENCODE_HELPER_CLI}.cmd` : OPENCODE_HELPER_CLI);
+}
+function resolveOpenCodeHelperMjsPath(binDir) {
+    return join(binDir, `${OPENCODE_HELPER_CLI}.mjs`);
+}
+function readPackageJson(packageRoot) {
+    return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+}
+function packageRootFrom(startDir) {
+    let current = startDir;
+    for (let depth = 0; depth < 12; depth += 1) {
+        const pkg = join(current, 'package.json');
+        if (existsSync(pkg)) {
+            try {
+                const parsed = JSON.parse(readFileSync(pkg, 'utf8'));
+                if (parsed.name === WAVEXZORE_SANDBOX_PACKAGE)
+                    return current;
+            }
+            catch {
+                // Ignore best-effort cleanup failures.
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+export function resolveCurrentPackageRoot(explicit, env) {
+    if (explicit)
+        return explicit;
+    const envRoot = runtimeEnv(env).WAVEXZORE_SANDBOX_PACKAGE_ROOT;
+    if (envRoot)
+        return envRoot;
+    const fromModule = packageRootFrom(moduleDir);
+    if (fromModule)
+        return fromModule;
+    const fromCwd = packageRootFrom(process.cwd());
+    if (fromCwd)
+        return fromCwd;
+    throw new Error(`Cannot locate ${WAVEXZORE_SANDBOX_PACKAGE} package root`);
+}
+function assertRequiredPackageFiles(packageRoot, version) {
+    const packageJsonPath = join(packageRoot, 'package.json');
+    const pluginEntry = join(packageRoot, 'dist', 'index.js');
+    const cliEntry = join(packageRoot, 'dist', 'sandbox', 'cli', `${WAVEXZORE_SANDBOX_CLI}.js`);
+    if (!existsSync(packageJsonPath))
+        throw new Error(`Missing package.json in ${packageRoot}`);
+    const parsed = readPackageJson(packageRoot);
+    if (parsed.name !== WAVEXZORE_SANDBOX_PACKAGE)
+        throw new Error(`Invalid package name: expected ${WAVEXZORE_SANDBOX_PACKAGE}, got ${String(parsed.name)}`);
+    if (parsed.version !== version)
+        throw new Error(`Invalid package version metadata: expected ${version}, got ${String(parsed.version)}`);
+    if (!existsSync(pluginEntry)) {
+        throw new Error(`Built plugin entry not found at ${pluginEntry}. Run npm --workspace @wavexzore/sandbox run build before installing from source.`);
+    }
+    if (!existsSync(cliEntry)) {
+        throw new Error(`Built CLI entry not found at ${cliEntry}. Run npm --workspace @wavexzore/sandbox run build before installing from source.`);
+    }
+}
+function directoryFileHashes(root) {
+    const hashes = {};
+    function visit(dir, prefix = '') {
+        for (const name of readdirSync(dir).sort()) {
+            const path = join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const stat = statSync(path);
+            if (stat.isDirectory())
+                visit(path, rel);
+            else if (stat.isFile())
+                hashes[rel] = createHash('sha256').update(readFileSync(path)).digest('hex');
+        }
+    }
+    visit(root);
+    return hashes;
+}
+function sameDirectoryContent(left, right) {
+    if (!existsSync(left) || !existsSync(right))
+        return false;
+    return JSON.stringify(directoryFileHashes(left)) === JSON.stringify(directoryFileHashes(right));
+}
+function copyIfExists(source, target) {
+    if (!existsSync(source))
+        return;
+    cpSync(source, target, { recursive: true, force: true });
+}
+function copyPackageToStaging(packageRoot, stagingPath) {
+    mkdirSync(stagingPath, { recursive: true });
+    copyIfExists(join(packageRoot, 'package.json'), join(stagingPath, 'package.json'));
+    copyIfExists(join(packageRoot, 'dist'), join(stagingPath, 'dist'));
+    copyIfExists(join(packageRoot, 'README.md'), join(stagingPath, 'README.md'));
+    copyIfExists(join(packageRoot, 'Dockerfile'), join(stagingPath, 'Dockerfile'));
+    copyIfExists(join(packageRoot, 'LICENSE'), join(stagingPath, 'LICENSE'));
+    copyIfExists(join(packageRoot, 'NOTICE'), join(stagingPath, 'NOTICE'));
+}
+function packageNamesFromDependencies(packageJsonPath) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return Object.keys(parsed.dependencies ?? {});
+}
+function packageNameFromPackageJson(packageJsonPath) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    if (!parsed.name)
+        throw new Error(`Dependency package at ${packageJsonPath} is missing a name`);
+    return parsed.name;
+}
+function dependencyTargetPath(nodeModulesDir, packageName) {
+    if (packageName.startsWith('@')) {
+        const [scope, name] = packageName.split('/');
+        if (!scope || !name)
+            throw new Error(`Invalid scoped dependency name: ${packageName}`);
+        return join(nodeModulesDir, scope, name);
+    }
+    return join(nodeModulesDir, packageName);
+}
+function packageJsonFromResolvedEntry(entry, packageName) {
+    let current = dirname(entry);
+    for (let depth = 0; depth < 8; depth += 1) {
+        const candidate = join(current, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                if (packageNameFromPackageJson(candidate) === packageName)
+                    return candidate;
+            }
+            catch {
+                // Continue walking when a package.json cannot be parsed.
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+function packageJsonFromNodeModules(packageName, fromDir) {
+    let current = resolve(fromDir);
+    for (let depth = 0; depth < 16; depth += 1) {
+        const candidate = join(current, 'node_modules', ...packageName.split('/'), 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+function resolveDependencyPackageJson(packageName, fromDir) {
+    const fromNodeModules = packageJsonFromNodeModules(packageName, fromDir);
+    if (fromNodeModules)
+        return fromNodeModules;
+    try {
+        return require.resolve(`${packageName}/package.json`, { paths: [fromDir] });
+    }
+    catch {
+        // Some packages intentionally hide package.json through exports. Resolve the package entry instead.
+    }
+    try {
+        const entry = require.resolve(packageName, { paths: [fromDir] });
+        const packageJsonPath = packageJsonFromResolvedEntry(entry, packageName);
+        if (packageJsonPath)
+            return packageJsonPath;
+        throw new Error(`could not find package.json from resolved entry ${entry}`);
+    }
+    catch (error) {
+        throw new Error(`Cannot resolve dependency ${packageName} from ${fromDir}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function copyDependencyClosure(args) {
+    for (const dependencyName of packageNamesFromDependencies(args.packageJsonPath)) {
+        const dependencyPackageJson = resolveDependencyPackageJson(dependencyName, args.fromDir);
+        const actualName = packageNameFromPackageJson(dependencyPackageJson);
+        const packageRoot = dirname(dependencyPackageJson);
+        const seenKey = `${actualName}:${packageRoot}`;
+        if (args.seen.has(seenKey))
+            continue;
+        args.seen.add(seenKey);
+        const target = dependencyTargetPath(args.nodeModulesDir, actualName);
+        if (!existsSync(target)) {
+            mkdirSync(dirname(target), { recursive: true });
+            cpSync(packageRoot, target, { recursive: true, force: true, dereference: true });
+            rmSync(join(target, 'node_modules'), { recursive: true, force: true });
+        }
+        copyDependencyClosure({
+            packageJsonPath: dependencyPackageJson,
+            fromDir: packageRoot,
+            nodeModulesDir: args.nodeModulesDir,
+            seen: args.seen,
+        });
+    }
+}
+function prepareStoreDependencies(packageRoot, storeDir, dryRun) {
+    if (dryRun)
+        return;
+    const packageJsonPath = join(packageRoot, 'package.json');
+    const nodeModulesDir = join(storeDir, 'node_modules');
+    mkdirSync(nodeModulesDir, { recursive: true });
+    copyDependencyClosure({ packageJsonPath, fromDir: packageRoot, nodeModulesDir, seen: new Set() });
+}
+export function readCurrentPackageVersion(packageRoot = resolveCurrentPackageRoot()) {
+    const parsed = readPackageJson(packageRoot);
+    if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+        throw new Error(`Invalid package version in ${join(packageRoot, 'package.json')}`);
+    }
+    return parsed.version;
+}
+export function prepareCurrentPackageVersion(args) {
+    const packageRoot = resolveCurrentPackageRoot(args.packageRoot, args.env);
+    const version = readCurrentPackageVersion(packageRoot);
+    assertSafeVersion(version);
+    const versionPath = resolveWavexzoreSandboxVersionDir(args.storeDir, version);
+    if (existsSync(versionPath)) {
+        assertRequiredPackageFiles(versionPath, version);
+        if (!args.dryRun)
+            prepareStoreDependencies(packageRoot, args.storeDir, args.dryRun);
+        if (args.dryRun)
+            return { version, versionPath, versionStatus: 'existing' };
+    }
+    if (args.dryRun) {
+        assertRequiredPackageFiles(packageRoot, version);
+        return { version, versionPath, versionStatus: existsSync(versionPath) ? 'existing' : 'created' };
+    }
+    assertRequiredPackageFiles(packageRoot, version);
+    prepareStoreDependencies(packageRoot, args.storeDir, args.dryRun);
+    const stagingPath = join(args.storeDir, 'tmp', `install-${version}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    rmSync(stagingPath, { recursive: true, force: true });
+    copyPackageToStaging(packageRoot, stagingPath);
+    assertRequiredPackageFiles(stagingPath, version);
+    mkdirSync(dirname(versionPath), { recursive: true });
+    if (existsSync(versionPath)) {
+        if (sameDirectoryContent(stagingPath, versionPath)) {
+            rmSync(stagingPath, { recursive: true, force: true });
+            return { version, versionPath, versionStatus: 'existing' };
+        }
+        rmSync(versionPath, { recursive: true, force: true });
+        renameSync(stagingPath, versionPath);
+        return { version, versionPath, versionStatus: 'updated' };
+    }
+    renameSync(stagingPath, versionPath);
+    return { version, versionPath, versionStatus: 'created' };
+}
+function localLoaderPackageJson() {
+    return `${JSON.stringify({
+        name: WAVEXZORE_SANDBOX_LOADER_PACKAGE,
+        type: 'module',
+        main: './index.mjs',
+        exports: { '.': './index.mjs' },
+    }, null, 2)}\n`;
+}
+function localLoaderIndex() {
+    return `import { readFileSync } from "node:fs"\nimport { dirname, join } from "node:path"\nimport { fileURLToPath, pathToFileURL } from "node:url"\n\nconst root = dirname(dirname(fileURLToPath(import.meta.url)))\nconst manifest = JSON.parse(readFileSync(join(root, "manifest.json"), "utf8"))\nconst entry = join(root, "versions", manifest.activeVersion, "dist", "index.js")\nconst mod = await import(pathToFileURL(entry).href)\nconst plugin = mod.default?.default ?? mod.default ?? mod\nexport default plugin\n`;
+}
+export function writeLocalLoader(loaderDir, dryRun) {
+    const packageJsonPath = join(loaderDir, 'package.json');
+    const indexPath = join(loaderDir, 'index.mjs');
+    const packageStatus = statusForText(packageJsonPath, localLoaderPackageJson());
+    const indexStatus = statusForText(indexPath, localLoaderIndex());
+    if (!dryRun) {
+        mkdirSync(loaderDir, { recursive: true });
+        writeFileAtomic(packageJsonPath, localLoaderPackageJson());
+        writeFileAtomic(indexPath, localLoaderIndex());
+    }
+    return combineInstallStatus([packageStatus, indexStatus]);
+}
+export function readWavexzoreSandboxManifest(storeDir) {
+    const manifestPath = resolveWavexzoreSandboxManifestPath(storeDir);
+    if (!existsSync(manifestPath))
+        return undefined;
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (parsed.schemaVersion !== 1 ||
+        parsed.packageName !== WAVEXZORE_SANDBOX_PACKAGE ||
+        parsed.pluginId !== WAVEXZORE_SANDBOX_PLUGIN_ID) {
+        throw new Error(`Invalid Wavexzore Sandbox manifest at ${manifestPath}`);
+    }
+    if (typeof parsed.activeVersion !== 'string')
+        throw new Error(`Invalid activeVersion in ${manifestPath}`);
+    return parsed;
+}
+export function nextManifest(args) {
+    const installedVersions = Array.from(new Set([...(args.current?.installedVersions ?? []), args.activeVersion])).sort();
+    const now = nowIso(args.now ?? Date.now());
+    return {
+        schemaVersion: 1,
+        pluginId: WAVEXZORE_SANDBOX_PLUGIN_ID,
+        packageName: WAVEXZORE_SANDBOX_PACKAGE,
+        activeVersion: args.activeVersion,
+        installedVersions,
+        channel: args.channel ?? args.current?.channel ?? 'latest',
+        installedAt: args.current?.installedAt ?? now,
+        updatedAt: now,
+        opencodeConfigPath: args.configPath,
+        opencodePluginSpec: args.pluginSpec,
+        cliPath: args.cliPath,
+    };
+}
+export function writeManifest(manifestPath, manifest, dryRun) {
+    const desired = `${JSON.stringify(manifest, null, 2)}\n`;
+    const status = statusForText(manifestPath, desired);
+    writeFileAtomic(manifestPath, desired, dryRun);
+    return status;
+}
+function stableCliShimMjs(storeDir) {
+    return `#!/usr/bin/env node\nimport { spawnSync } from "node:child_process"\nimport { existsSync, readFileSync } from "node:fs"\nimport { join } from "node:path"\n\nconst storeDir = ${JSON.stringify(storeDir)}\nconst manifestPath = join(storeDir, "manifest.json")\n\nfunction fail(message) {\n  console.error(message)\n  process.exit(1)\n}\n\nif (!existsSync(manifestPath)) fail(\`Wavexzore Sandbox manifest not found: \${manifestPath}\`)\n\nlet manifest\ntry {\n  manifest = JSON.parse(readFileSync(manifestPath, "utf8"))\n} catch (error) {\n  fail(\`Failed to read Wavexzore Sandbox manifest: \${error instanceof Error ? error.message : String(error)}\`)\n}\n\nif (!manifest || typeof manifest.activeVersion !== "string" || manifest.activeVersion.length === 0) {\n  fail(\`Invalid Wavexzore Sandbox manifest: \${manifestPath}\`)\n}\n\nconst cli = join(storeDir, "versions", manifest.activeVersion, "dist", "sandbox", "cli", "${WAVEXZORE_SANDBOX_CLI}.js")\nif (!existsSync(cli)) fail(\`Wavexzore Sandbox CLI entry not found for activeVersion=\${manifest.activeVersion}: \${cli}\`)\n\nconst result = spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { stdio: "inherit", shell: false })\nif (result.error) fail(\`Failed to start Wavexzore Sandbox CLI: \${result.error.message}\`)\nprocess.exit(result.status ?? 1)\n`;
+}
+function stableCliShimUnix() {
+    return `#!/usr/bin/env sh\nset -eu\nSCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\nexec node "$SCRIPT_DIR/${WAVEXZORE_SANDBOX_CLI}.mjs" "$@"\n`;
+}
+function stableCliShimCmd() {
+    return `@echo off\r\nnode "%~dp0${WAVEXZORE_SANDBOX_CLI}.mjs" %*\r\nexit /b %ERRORLEVEL%\r\n`;
+}
+function stableOpenCodeHelperShimMjs(storeDir) {
+    return `#!/usr/bin/env node\nimport { spawnSync } from "node:child_process"\nimport { existsSync, readFileSync } from "node:fs"\nimport { dirname, join } from "node:path"\nimport { fileURLToPath } from "node:url"\n\nconst scriptDir = dirname(fileURLToPath(import.meta.url))\nconst storeDir = ${JSON.stringify(storeDir)}\nconst manifestPath = join(storeDir, "manifest.json")\nconst wavexzoreCli = join(scriptDir, "${WAVEXZORE_SANDBOX_CLI}.mjs")\n\nfunction readManifest() {\n  if (!existsSync(manifestPath)) return undefined\n  try {\n    return JSON.parse(readFileSync(manifestPath, "utf8"))\n  } catch (error) {\n    return { error: error instanceof Error ? error.message : String(error) }\n  }\n}\n\nfunction json(payload, status = 0) {\n  console.log(JSON.stringify(payload, null, 2))\n  process.exit(status)\n}\n\nfunction opencode(args) {\n  const [command] = args\n  const manifest = readManifest()\n  const activeVersion = typeof manifest?.activeVersion === "string" ? manifest.activeVersion : undefined\n  const cliEntry = activeVersion\n    ? join(storeDir, "versions", activeVersion, "dist", "sandbox", "cli", "${WAVEXZORE_SANDBOX_CLI}.js")\n    : undefined\n  const checks = [\n    {\n      name: "manifest",\n      status: manifest && !manifest.error ? "passed" : "failed",\n      path: manifestPath,\n      message: manifest?.error ?? (manifest ? "manifest exists" : "manifest is missing"),\n    },\n    {\n      name: "wavexzore-cli-shim",\n      status: existsSync(wavexzoreCli) ? "passed" : "failed",\n      path: wavexzoreCli,\n      message: existsSync(wavexzoreCli) ? "stable CLI shim exists" : "stable CLI shim is missing",\n    },\n    {\n      name: "active-cli-entry",\n      status: cliEntry && existsSync(cliEntry) ? "passed" : "failed",\n      path: cliEntry,\n      message: cliEntry && existsSync(cliEntry) ? "active CLI entry exists" : "active CLI entry is missing",\n    },\n  ]\n  const ok = checks.every((check) => check.status === "passed")\n\n  if (command === "doctor") {\n    json({\n      ok,\n      data: {\n        storeDir,\n        manifestPath,\n        cliPath: manifest?.cliPath,\n        activeVersion,\n        checks,\n      },\n      error: ok\n        ? undefined\n        : {\n            code: "OPENCODE_HELPER_FAILED",\n            message: "OpenCode helper installation is incomplete",\n          },\n    }, ok ? 0 : 1)\n  }\n\n  if (command === "version") {\n    json({ ok: true, data: { activeVersion, manifestPath, cliPath: manifest?.cliPath } })\n  }\n\n  console.error(\`Unknown OpenCode helper command: \${command ?? ""}\`)\n  process.exit(2)\n}\n\nif (process.argv[2] === "opencode") opencode(process.argv.slice(3))\n\nconst result = spawnSync(process.execPath, [wavexzoreCli, ...process.argv.slice(2)], { stdio: "inherit", shell: false })\nif (result.error) {\n  console.error(\`Failed to start Wavexzore Sandbox CLI: \${result.error.message}\`)\n  process.exit(1)\n}\nprocess.exit(result.status ?? 1)\n`;
+}
+function stableOpenCodeHelperShimUnix() {
+    return `#!/usr/bin/env sh\nset -eu\nSCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\nexec node "$SCRIPT_DIR/${OPENCODE_HELPER_CLI}.mjs" "$@"\n`;
+}
+function stableOpenCodeHelperShimCmd() {
+    return `@echo off\r\nnode "%~dp0${OPENCODE_HELPER_CLI}.mjs" %*\r\nexit /b %ERRORLEVEL%\r\n`;
+}
+export function writeWavexzoreSandboxBinShims(args) {
+    if (args.enabled === false)
+        return { binDir: args.binDir, binStatus: 'skipped' };
+    const platform = runtimePlatform(args.platform);
+    const paths = resolveWavexzoreSandboxBinShimPaths(args.binDir);
+    const helperPath = resolveOpenCodeHelperPath(args.binDir, platform);
+    const helperMjsPath = resolveOpenCodeHelperMjsPath(args.binDir);
+    const entries = [
+        { path: paths.js, contents: stableCliShimMjs(args.storeDir), executable: true },
+        { path: paths.unix, contents: stableCliShimUnix(), executable: true },
+        { path: paths.cmd, contents: stableCliShimCmd(), executable: false },
+        { path: helperMjsPath, contents: stableOpenCodeHelperShimMjs(args.storeDir), executable: true },
+        {
+            path: helperPath,
+            contents: platform === 'win32' ? stableOpenCodeHelperShimCmd() : stableOpenCodeHelperShimUnix(),
+            executable: true,
+        },
+    ];
+    const statuses = entries.map((entry) => statusForText(entry.path, entry.contents));
+    if (!args.dryRun) {
+        mkdirSync(args.binDir, { recursive: true });
+        for (const entry of entries) {
+            writeFileAtomic(entry.path, entry.contents);
+            if (entry.executable && platform !== 'win32') {
+                try {
+                    chmodSync(entry.path, 0o755);
+                }
+                catch {
+                    // Ignore best-effort cleanup failures.
+                }
+            }
+        }
+    }
+    return { binDir: args.binDir, binStatus: combineInstallStatus(statuses) };
+}
+function removeFileIfExists(path, dryRun) {
+    if (!existsSync(path))
+        return 'missing';
+    if (!dryRun)
+        rmSync(path, { force: true });
+    return 'removed';
+}
+export function uninstallWavexzoreSandboxBinShims(args) {
+    if (args.keepBin)
+        return { binDir: args.binDir, binStatus: 'kept' };
+    const paths = resolveWavexzoreSandboxBinShimPaths(args.binDir);
+    const helperPaths = [
+        resolveOpenCodeHelperMjsPath(args.binDir),
+        resolveOpenCodeHelperPath(args.binDir, 'linux'),
+        resolveOpenCodeHelperPath(args.binDir, 'win32'),
+    ];
+    const statuses = [paths.js, paths.unix, paths.cmd, ...helperPaths].map((path) => removeFileIfExists(path, args.dryRun));
+    return { binDir: args.binDir, binStatus: combineUninstallStatus(statuses) };
+}
+export function removePathIfExists(path, dryRun) {
+    if (!existsSync(path))
+        return 'missing';
+    if (!dryRun)
+        rmSync(path, { recursive: true, force: true });
+    return 'removed';
+}
+export function removeEmptyDirectory(path, dryRun) {
+    try {
+        if (!existsSync(path) || readdirSync(path).length > 0)
+            return;
+        if (!dryRun)
+            rmSync(path);
+    }
+    catch {
+        // Ignore best-effort empty directory cleanup failures.
+    }
+}
+const PATH_MARKER_START = '# >>> wavexzore-sandbox >>>';
+const PATH_MARKER_END = '# <<< wavexzore-sandbox <<<';
+function pathMarkerBlock(binDir, profilePath) {
+    const usesFish = profilePath.replace(/\\/g, '/').endsWith('/config.fish');
+    const body = usesFish ? `fish_add_path ${shellQuote(binDir)}` : `export PATH=${shellQuote(binDir)}:"$PATH"`;
+    return `${PATH_MARKER_START}\n${body}\n${PATH_MARKER_END}\n`;
+}
+function replacePathMarker(raw, replacement) {
+    const pattern = /(?:^|\r?\n)# >>> wavexzore-sandbox >>>\r?\n[\s\S]*?# <<< wavexzore-sandbox <<<\r?\n?/m;
+    const match = raw.match(pattern);
+    if (!match) {
+        const prefix = raw.length > 0 && !raw.endsWith('\n') ? '\n' : '';
+        return { text: `${raw}${prefix}${replacement}`, changed: true };
+    }
+    const existing = match[0].replace(/^\r?\n/, '');
+    if (existing === replacement)
+        return { text: raw, changed: false };
+    const leadingNewline = match[0].startsWith('\n') ? '\n' : '';
+    return { text: raw.replace(pattern, `${leadingNewline}${replacement}`), changed: true };
+}
+function removePathMarker(raw) {
+    const pattern = /(?:^|\r?\n)# >>> wavexzore-sandbox >>>\r?\n[\s\S]*?# <<< wavexzore-sandbox <<<\r?\n?/m;
+    const next = raw.replace(pattern, (match) => (match.startsWith('\n') ? '\n' : ''));
+    return { text: next.replace(/\n{3,}/g, '\n\n'), changed: next !== raw };
+}
+function updateWindowsUserPath(args) {
+    const current = args.envPath ?? runtimeEnv(args.env).Path ?? runtimeEnv(args.env).PATH ?? '';
+    const parts = current.split(';').filter((item) => item.trim().length > 0);
+    const normalizedBin = resolve(args.binDir)
+        .replace(/[\\/]+$/, '')
+        .toLowerCase();
+    const hasBin = parts.some((item) => resolve(item.trim())
+        .replace(/[\\/]+$/, '')
+        .toLowerCase() === normalizedBin);
+    if (args.remove) {
+        if (!hasBin)
+            return 'unchanged';
+        if (args.dryRun)
+            return 'removed';
+        const next = parts
+            .filter((item) => resolve(item.trim())
+            .replace(/[\\/]+$/, '')
+            .toLowerCase() !== normalizedBin)
+            .join(';');
+        const command = `[Environment]::SetEnvironmentVariable('Path', ${powershellSingleQuote(next)}, 'User')`;
+        const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], {
+            encoding: 'utf8',
+        });
+        if (result.error || result.status !== 0)
+            throw new Error(result.error?.message || result.stderr || 'Failed to update Windows user Path');
+        return 'removed';
+    }
+    if (hasBin)
+        return 'present';
+    if (args.dryRun)
+        return 'updated';
+    const next = [...parts, args.binDir].join(';');
+    const command = `[Environment]::SetEnvironmentVariable('Path', ${powershellSingleQuote(next)}, 'User')`;
+    const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], {
+        encoding: 'utf8',
+    });
+    if (result.error || result.status !== 0)
+        throw new Error(result.error?.message || result.stderr || 'Failed to update Windows user Path');
+    return 'updated';
+}
+export function setupWavexzoreSandboxPath(options = {}) {
+    const homeDir = resolveWavexzoreSandboxHomeDir(options);
+    const binDir = resolveWavexzoreSandboxBinDir({ ...options, homeDir });
+    const platform = runtimePlatform(options.platform);
+    const pathHint = pathHintForPlatform(binDir, platform);
+    if (isDirectoryOnPath(binDir, options.envPath, platform))
+        return { homeDir, binDir, pathStatus: 'present', pathHint };
+    if (platform === 'win32')
+        return {
+            homeDir,
+            binDir,
+            pathStatus: updateWindowsUserPath({ binDir, dryRun: options.dryRun, envPath: options.envPath, env: options.env }),
+            pathHint,
+        };
+    const pathConfigPath = shellProfilePath({
+        homeDir: defaultHome(options.env),
+        pathConfigPath: options.pathConfigPath,
+        shell: options.shell,
+        env: options.env,
+    });
+    const current = existsSync(pathConfigPath) ? readFileSync(pathConfigPath, 'utf8') : '';
+    const next = replacePathMarker(current, pathMarkerBlock(binDir, pathConfigPath));
+    if (!next.changed)
+        return { homeDir, binDir, pathStatus: 'present', pathConfigPath, pathHint };
+    writeFileAtomic(pathConfigPath, next.text, options.dryRun);
+    return { homeDir, binDir, pathStatus: 'updated', pathConfigPath, pathHint };
+}
+export function removeWavexzoreSandboxPath(options = {}) {
+    const homeDir = resolveWavexzoreSandboxHomeDir(options);
+    const binDir = resolveWavexzoreSandboxBinDir({ ...options, homeDir });
+    const platform = runtimePlatform(options.platform);
+    const pathHint = pathHintForPlatform(binDir, platform);
+    if (platform === 'win32')
+        return {
+            homeDir,
+            binDir,
+            pathStatus: updateWindowsUserPath({
+                binDir,
+                remove: true,
+                dryRun: options.dryRun,
+                envPath: options.envPath,
+                env: options.env,
+            }),
+            pathHint,
+        };
+    const pathConfigPath = shellProfilePath({
+        homeDir: defaultHome(options.env),
+        pathConfigPath: options.pathConfigPath,
+        shell: options.shell,
+        env: options.env,
+    });
+    if (!existsSync(pathConfigPath))
+        return { homeDir, binDir, pathStatus: 'unchanged', pathConfigPath, pathHint };
+    const next = removePathMarker(readFileSync(pathConfigPath, 'utf8'));
+    if (!next.changed)
+        return { homeDir, binDir, pathStatus: 'unchanged', pathConfigPath, pathHint };
+    writeFileAtomic(pathConfigPath, next.text, options.dryRun);
+    return { homeDir, binDir, pathStatus: 'removed', pathConfigPath, pathHint };
+}
+export function relativeWithin(root, target) {
+    return relative(root, target).replace(/\\/g, '/');
+}

package/dist/sandbox/cli/opencode-config.d.ts

@@ -0,0 +1,25 @@
+import { type HostConfigResult, type HostConfigUninstallResult, type InstallStatus } from './types.js';
+type OpenCodeConfig = Record<string, unknown> & {
+    plugin?: unknown;
+    $schema?: unknown;
+};
+export declare function readOpenCodeConfig(configPath: string): OpenCodeConfig;
+export declare function normalizePluginEntries(value: unknown): unknown[];
+export declare function isKnownWavexzoreSandboxPluginEntry(spec: string): boolean;
+export declare function nextPluginEntries(current: unknown[], pluginEntry: string): {
+    plugins: unknown[];
+    removed: string[];
+    pluginStatus: InstallStatus;
+};
+export declare function installOpenCodeConfig(args: {
+    configPath: string;
+    pluginEntry: string;
+    dryRun?: boolean;
+}): HostConfigResult;
+export declare function uninstallOpenCodeConfig(args: {
+    configPath: string;
+    pluginEntry: string;
+    dryRun?: boolean;
+    keepConfig?: boolean;
+}): HostConfigUninstallResult;
+export {};