@wavexzore/sandbox 0.1.0

package/dist/sandbox/cli/wavexzore-sandbox.js

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+import { realpathSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { doctorWavexzoreSandbox, installWavexzoreSandbox, setupWavexzoreSandboxPathCommand, uninstallWavexzoreSandbox, } from './install.js';
+export const WAVEXZORE_SANDBOX_CLI_HELP = `wavexzore-sandbox CLI
+
+Usage:
+  wavexzore-sandbox install [path] [--root <path>] [--scope <user|project>] [--home-dir <path>] [--store-dir <path>] [--bin-dir <path>] [--config-path <file>] [--config-dir <path>] [--package-root <path>] [--json] [--dry-run] [--no-bin] [--setup-path]
+  wavexzore-sandbox uninstall [path] [--root <path>] [--scope <user|project>] [--home-dir <path>] [--store-dir <path>] [--bin-dir <path>] [--config-path <file>] [--config-dir <path>] [--json] [--dry-run] [--keep-config] [--keep-store] [--keep-bin] [--remove-path]
+  wavexzore-sandbox doctor [--scope <user|project>] [--home-dir <path>] [--store-dir <path>] [--bin-dir <path>] [--config-path <file>] [--config-dir <path>] [--project-root <path>] [--json]
+  wavexzore-sandbox setup-path [--scope <user|project>] [--home-dir <path>] [--store-dir <path>] [--bin-dir <path>] [--json] [--dry-run]
+  wavexzore-sandbox help
+
+Commands:
+  install       Deploy @wavexzore/sandbox into a durable local store and configure OpenCode with a file:// plugin loader
+  uninstall     Remove Wavexzore Sandbox from OpenCode config and delete the local store by default
+  doctor        Validate OpenCode config, local loader, manifest, active version, plugin import, and OpenCode helper
+  setup-path    Explicitly add the Wavexzore Sandbox bin directory to PATH/profile
+  help          Show this help message
+
+Options:
+  --root <path>         Invocation workspace. Used for --scope project and relative paths.
+  --scope <value>       user (default) or project. Project scope writes <root>/.wavexzore/opencode/sandbox.
+  --home-dir <path>     Product home. Default: ~/.wavexzore/opencode or WAVEXZORE_SANDBOX_HOME.
+  --store-dir <path>    Explicit local store directory. Default: ~/.wavexzore/opencode/sandbox.
+  --bin-dir <path>      Internal helper directory. Default: ~/.wavexzore/opencode/bin.
+  --config-path <file>  Exact OpenCode config file. Otherwise honors OPENCODE_CONFIG for user scope.
+  --config-dir <path>   OpenCode config directory for user scope.
+  --package-root <path> Install only: package root override for development/testing.
+  --no-bin              Install only: do not create or repair the internal helper/shims under --bin-dir.
+  --setup-path          Install only: explicitly add --bin-dir to PATH/profile.
+  --no-path-hint        Install only: suppress PATH hint output after an explicit --setup-path attempt.
+  --dry-run             Report changes without writing files where supported.
+  --keep-config         Uninstall only: keep OpenCode config unchanged.
+  --keep-store          Uninstall only: keep ~/.wavexzore/opencode/sandbox or --store-dir.
+  --keep-bin            Uninstall only: keep ~/.wavexzore/opencode/bin helper/shims or --bin-dir.
+  --remove-path         Uninstall only: remove the managed PATH/profile marker or Windows user Path entry.
+  --json                Print machine-readable output.
+  -h, --help            Show command help.
+`;
+function writeLine(stream, value = '') {
+    stream.write(`${value}\n`);
+}
+function nextValue(args, index, flag) {
+    const value = args[index + 1];
+    if (!value)
+        return { error: `Missing value for ${flag}` };
+    return { value };
+}
+function parseScope(value) {
+    return value === 'user' || value === 'project' ? value : undefined;
+}
+export function parseInstallArgs(args) {
+    const parsed = {
+        root: '.',
+        scope: 'user',
+        json: false,
+        dryRun: false,
+        noBin: false,
+        setupPath: false,
+        noPathHint: false,
+        help: false,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--json')
+            parsed.json = true;
+        else if (arg === '--dry-run')
+            parsed.dryRun = true;
+        else if (arg === '--no-bin')
+            parsed.noBin = true;
+        else if (arg === '--setup-path')
+            parsed.setupPath = true;
+        else if (arg === '--no-path-hint')
+            parsed.noPathHint = true;
+        else if (arg === '--help' || arg === '-h')
+            parsed.help = true;
+        else if (arg === '--root') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.root = next.value ?? '';
+            index += 1;
+        }
+        else if (arg === '--scope') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            const scope = parseScope(next.value ?? '');
+            if (!scope)
+                return { ...parsed, error: '--scope must be user or project' };
+            parsed.scope = scope;
+            index += 1;
+        }
+        else if (arg === '--home-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.homeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--bin-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.binDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--store-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.storeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--config-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.configDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--config-path') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.configPath = next.value;
+            index += 1;
+        }
+        else if (arg === '--package-root') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.packageRoot = next.value;
+            index += 1;
+        }
+        else if (arg.startsWith('-')) {
+            return { ...parsed, error: `Unknown option: ${arg}` };
+        }
+        else {
+            parsed.root = arg;
+        }
+    }
+    return parsed;
+}
+export function parseUninstallArgs(args) {
+    const parsed = {
+        root: '.',
+        scope: 'user',
+        json: false,
+        dryRun: false,
+        keepConfig: false,
+        keepStore: false,
+        keepBin: false,
+        removePath: false,
+        help: false,
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--json')
+            parsed.json = true;
+        else if (arg === '--dry-run')
+            parsed.dryRun = true;
+        else if (arg === '--keep-config')
+            parsed.keepConfig = true;
+        else if (arg === '--keep-store')
+            parsed.keepStore = true;
+        else if (arg === '--keep-bin')
+            parsed.keepBin = true;
+        else if (arg === '--remove-path')
+            parsed.removePath = true;
+        else if (arg === '--help' || arg === '-h')
+            parsed.help = true;
+        else if (arg === '--root') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.root = next.value ?? '';
+            index += 1;
+        }
+        else if (arg === '--scope') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            const scope = parseScope(next.value ?? '');
+            if (!scope)
+                return { ...parsed, error: '--scope must be user or project' };
+            parsed.scope = scope;
+            index += 1;
+        }
+        else if (arg === '--home-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.homeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--bin-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.binDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--store-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.storeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--config-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.configDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--config-path') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.configPath = next.value;
+            index += 1;
+        }
+        else if (arg.startsWith('-')) {
+            return { ...parsed, error: `Unknown option: ${arg}` };
+        }
+        else {
+            parsed.root = arg;
+        }
+    }
+    return parsed;
+}
+export function parseDoctorArgs(args) {
+    const parsed = { scope: 'user', json: false, help: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--json')
+            parsed.json = true;
+        else if (arg === '--help' || arg === '-h')
+            parsed.help = true;
+        else if (arg === '--scope') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            const scope = parseScope(next.value ?? '');
+            if (!scope)
+                return { ...parsed, error: '--scope must be user or project' };
+            parsed.scope = scope;
+            index += 1;
+        }
+        else if (arg === '--home-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.homeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--bin-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.binDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--store-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.storeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--config-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.configDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--config-path') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.configPath = next.value;
+            index += 1;
+        }
+        else if (arg === '--project-root' || arg === '--root') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.projectRoot = next.value;
+            index += 1;
+        }
+        else if (arg.startsWith('-')) {
+            return { ...parsed, error: `Unknown option: ${arg}` };
+        }
+        else {
+            return { ...parsed, error: `Unexpected positional argument for doctor: ${arg}` };
+        }
+    }
+    return parsed;
+}
+export function parseSetupPathArgs(args) {
+    const parsed = { scope: 'user', json: false, dryRun: false, help: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--json')
+            parsed.json = true;
+        else if (arg === '--dry-run')
+            parsed.dryRun = true;
+        else if (arg === '--help' || arg === '-h')
+            parsed.help = true;
+        else if (arg === '--scope') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            const scope = parseScope(next.value ?? '');
+            if (!scope)
+                return { ...parsed, error: '--scope must be user or project' };
+            parsed.scope = scope;
+            index += 1;
+        }
+        else if (arg === '--home-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.homeDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--bin-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.binDir = next.value;
+            index += 1;
+        }
+        else if (arg === '--store-dir') {
+            const next = nextValue(args, index, arg);
+            if (next.error)
+                return { ...parsed, error: next.error };
+            parsed.storeDir = next.value;
+            index += 1;
+        }
+        else if (arg.startsWith('-')) {
+            return { ...parsed, error: `Unknown option: ${arg}` };
+        }
+        else {
+            return { ...parsed, error: `Unexpected positional argument for setup-path: ${arg}` };
+        }
+    }
+    return parsed;
+}
+function safeErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function resolvePath(cwd, value) {
+    if (!value)
+        return undefined;
+    return isAbsolute(value) || value.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(value) ? value : resolve(cwd, value);
+}
+function printInstallSummary(stream, result, showPathHint = true) {
+    writeLine(stream, 'Wavexzore Sandbox installation complete');
+    writeLine(stream, `workspace: ${result.root}`);
+    writeLine(stream, `scope: ${result.scope}`);
+    writeLine(stream, `home: ${result.homeDir}`);
+    writeLine(stream, `store: ${result.storeDir}`);
+    writeLine(stream, `bin: ${result.binDir} (${result.binStatus})`);
+    writeLine(stream, `opencode-helper: ${result.cliPath}`);
+    writeLine(stream, `active-version: ${result.activeVersion} (${result.versionStatus})`);
+    writeLine(stream, `loader: ${result.loaderDir} (${result.loaderStatus})`);
+    writeLine(stream, `manifest: ${result.manifestPath} (${result.manifestStatus})`);
+    writeLine(stream, `config: ${result.configPath} (${result.configStatus})`);
+    writeLine(stream, `plugin: ${result.pluginEntry} (${result.pluginStatus})`);
+    writeLine(stream, `path: ${result.pathStatus}`);
+    if (result.pathConfigPath)
+        writeLine(stream, `path-config: ${result.pathConfigPath}`);
+    if (showPathHint && result.pathStatus === 'missing')
+        writeLine(stream, `path-hint: ${result.pathHint}`);
+    if (result.dryRun)
+        writeLine(stream, 'dry-run: no changes were made');
+    if (result.removedPluginEntries.length > 0)
+        writeLine(stream, `removed stale plugin entries: ${result.removedPluginEntries.join(', ')}`);
+}
+function printUninstallSummary(stream, result) {
+    writeLine(stream, 'Wavexzore Sandbox uninstall complete');
+    writeLine(stream, `workspace: ${result.root}`);
+    writeLine(stream, `scope: ${result.scope}`);
+    if (result.dryRun)
+        writeLine(stream, 'dry-run: no changes were made');
+    writeLine(stream, `config: ${result.configPath} (${result.configStatus})`);
+    writeLine(stream, `store: ${result.storeDir} (${result.storeStatus})`);
+    writeLine(stream, `bin: ${result.binDir} (${result.binStatus})`);
+    writeLine(stream, `path: ${result.pathStatus}`);
+    if (result.pathConfigPath)
+        writeLine(stream, `path-config: ${result.pathConfigPath}`);
+    if (result.removedPluginEntries.length > 0)
+        writeLine(stream, `removed plugin entries: ${result.removedPluginEntries.join(', ')}`);
+}
+function printDoctorSummary(stream, result) {
+    writeLine(stream, `Wavexzore Sandbox doctor ${result.status}`);
+    writeLine(stream, `home: ${result.homeDir}`);
+    writeLine(stream, `store: ${result.storeDir}`);
+    writeLine(stream, `bin: ${result.binDir}`);
+    writeLine(stream, `opencode-helper: ${result.cliPath}`);
+    writeLine(stream, `config: ${result.configPath}`);
+    writeLine(stream, `plugin: ${result.pluginEntry}`);
+    if (result.activeVersion)
+        writeLine(stream, `active-version: ${result.activeVersion}`);
+    for (const check of result.checks) {
+        writeLine(stream, `${check.status.toUpperCase()} ${check.name}: ${check.message}${check.path ? ` (${check.path})` : ''}`);
+    }
+}
+function printPathSummary(stream, result) {
+    writeLine(stream, `Wavexzore Sandbox setup-path ${result.pathStatus}`);
+    writeLine(stream, `home: ${result.homeDir}`);
+    writeLine(stream, `bin: ${result.binDir}`);
+    if (result.pathConfigPath)
+        writeLine(stream, `path-config: ${result.pathConfigPath}`);
+    if (result.pathStatus !== 'present')
+        writeLine(stream, `path-hint: ${result.pathHint}`);
+}
+export async function runWavexzoreSandboxCli(argv, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const [command = 'help', ...rest] = argv;
+    if (command === 'help' || command === '--help' || command === '-h') {
+        writeLine(stdout, WAVEXZORE_SANDBOX_CLI_HELP.trimEnd());
+        return 0;
+    }
+    if (command === 'install') {
+        const parsed = parseInstallArgs(rest);
+        if (parsed.error) {
+            writeLine(stderr, parsed.error);
+            return 1;
+        }
+        if (parsed.help) {
+            writeLine(stdout, WAVEXZORE_SANDBOX_CLI_HELP.trimEnd());
+            return 0;
+        }
+        const root = resolvePath(cwd, parsed.root) ?? cwd;
+        try {
+            const result = installWavexzoreSandbox(root, {
+                scope: parsed.scope,
+                homeDir: resolvePath(cwd, parsed.homeDir),
+                storeDir: resolvePath(cwd, parsed.storeDir),
+                binDir: resolvePath(cwd, parsed.binDir),
+                configPath: resolvePath(cwd, parsed.configPath),
+                configDir: resolvePath(cwd, parsed.configDir),
+                packageRoot: resolvePath(cwd, parsed.packageRoot),
+                dryRun: parsed.dryRun,
+                installBin: !parsed.noBin,
+                setupPath: parsed.setupPath,
+            });
+            if (parsed.json)
+                writeLine(stdout, JSON.stringify(result, null, 2));
+            else
+                printInstallSummary(stdout, result, parsed.setupPath && !parsed.noPathHint);
+            return 0;
+        }
+        catch (error) {
+            const message = safeErrorMessage(error);
+            if (parsed.json)
+                writeLine(stdout, JSON.stringify({ root, status: 'failed', error: message }, null, 2));
+            else
+                writeLine(stderr, `Wavexzore Sandbox installation failed: ${message}`);
+            return 1;
+        }
+    }
+    if (command === 'uninstall') {
+        const parsed = parseUninstallArgs(rest);
+        if (parsed.error) {
+            writeLine(stderr, parsed.error);
+            return 1;
+        }
+        if (parsed.help) {
+            writeLine(stdout, WAVEXZORE_SANDBOX_CLI_HELP.trimEnd());
+            return 0;
+        }
+        const root = resolvePath(cwd, parsed.root) ?? cwd;
+        const result = uninstallWavexzoreSandbox(root, {
+            scope: parsed.scope,
+            homeDir: resolvePath(cwd, parsed.homeDir),
+            storeDir: resolvePath(cwd, parsed.storeDir),
+            binDir: resolvePath(cwd, parsed.binDir),
+            configPath: resolvePath(cwd, parsed.configPath),
+            configDir: resolvePath(cwd, parsed.configDir),
+            dryRun: parsed.dryRun,
+            keepConfig: parsed.keepConfig,
+            keepStore: parsed.keepStore,
+            keepBin: parsed.keepBin,
+            removePath: parsed.removePath,
+        });
+        if (parsed.json)
+            writeLine(stdout, JSON.stringify(result, null, 2));
+        else
+            printUninstallSummary(stdout, result);
+        return 0;
+    }
+    if (command === 'doctor') {
+        const parsed = parseDoctorArgs(rest);
+        if (parsed.error) {
+            writeLine(stderr, parsed.error);
+            return 1;
+        }
+        if (parsed.help) {
+            writeLine(stdout, WAVEXZORE_SANDBOX_CLI_HELP.trimEnd());
+            return 0;
+        }
+        const result = await doctorWavexzoreSandbox({
+            scope: parsed.scope,
+            homeDir: resolvePath(cwd, parsed.homeDir),
+            storeDir: resolvePath(cwd, parsed.storeDir),
+            binDir: resolvePath(cwd, parsed.binDir),
+            configPath: resolvePath(cwd, parsed.configPath),
+            configDir: resolvePath(cwd, parsed.configDir),
+            projectRoot: resolvePath(cwd, parsed.projectRoot),
+        });
+        if (parsed.json)
+            writeLine(stdout, JSON.stringify(result, null, 2));
+        else
+            printDoctorSummary(result.status === 'failed' ? stderr : stdout, result);
+        return result.status === 'failed' ? 1 : 0;
+    }
+    if (command === 'setup-path') {
+        const parsed = parseSetupPathArgs(rest);
+        if (parsed.error) {
+            writeLine(stderr, parsed.error);
+            return 1;
+        }
+        if (parsed.help) {
+            writeLine(stdout, WAVEXZORE_SANDBOX_CLI_HELP.trimEnd());
+            return 0;
+        }
+        const result = setupWavexzoreSandboxPathCommand({
+            scope: parsed.scope,
+            homeDir: resolvePath(cwd, parsed.homeDir),
+            storeDir: resolvePath(cwd, parsed.storeDir),
+            binDir: resolvePath(cwd, parsed.binDir),
+            dryRun: parsed.dryRun,
+        });
+        if (parsed.json)
+            writeLine(stdout, JSON.stringify(result, null, 2));
+        else
+            printPathSummary(stdout, result);
+        return 0;
+    }
+    writeLine(stderr, `Unknown command: ${command}`);
+    writeLine(stderr, WAVEXZORE_SANDBOX_CLI_HELP.trimEnd());
+    return 1;
+}
+export function isMainModule(metaUrl = import.meta.url, argv1 = process.argv[1]) {
+    if (!argv1)
+        return false;
+    const modulePath = fileURLToPath(metaUrl);
+    const scriptPath = resolve(argv1);
+    if (modulePath === scriptPath)
+        return true;
+    try {
+        return realpathSync(modulePath) === realpathSync(scriptPath);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
+    runWavexzoreSandboxCli(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/sandbox/core/cli-helper.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright Daytona Platforms Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type CliHelperState = {
+    manifestPath: string;
+    cliPath: string;
+    available: boolean;
+    activeVersion?: string;
+    error?: string;
+};
+export type CliHelperDoctorResult = CliHelperState & {
+    ok: boolean;
+    stdout?: string;
+    stderr?: string;
+    status?: number | null;
+};
+export declare function resolveCliHelperState(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CliHelperState;
+export declare function doctorCliHelper(): CliHelperDoctorResult;

package/dist/sandbox/core/cli-helper.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright Daytona Platforms Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+function defaultHome(env) {
+    return env.WAVEXZORE_SANDBOX_HOME || join(homedir(), '.wavexzore', 'opencode');
+}
+function helperName(platform) {
+    return platform === 'win32' ? 'wavexzore-sandbox-helper.cmd' : 'wavexzore-sandbox-helper';
+}
+function readManifest(manifestPath) {
+    if (!existsSync(manifestPath))
+        return undefined;
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+export function resolveCliHelperState(env = process.env, platform = process.platform) {
+    const home = defaultHome(env);
+    const manifestPath = join(home, 'sandbox', 'manifest.json');
+    const fallbackCliPath = join(home, 'bin', helperName(platform));
+    try {
+        const manifest = readManifest(manifestPath);
+        const cliPath = manifest?.cliPath || fallbackCliPath;
+        return {
+            manifestPath,
+            cliPath,
+            available: existsSync(cliPath),
+            activeVersion: manifest?.activeVersion,
+        };
+    }
+    catch (error) {
+        return {
+            manifestPath,
+            cliPath: fallbackCliPath,
+            available: existsSync(fallbackCliPath),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function doctorCliHelper() {
+    const state = resolveCliHelperState();
+    if (!state.available)
+        return { ...state, ok: false, error: state.error || 'OpenCode helper is not installed' };
+    const result = spawnSync(state.cliPath, ['opencode', 'doctor', '--json'], {
+        encoding: 'utf8',
+        shell: false,
+        timeout: 5000,
+    });
+    return {
+        ...state,
+        ok: result.status === 0,
+        status: result.status,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        error: result.error
+            ? result.error.message
+            : result.status === 0
+                ? state.error
+                : result.stderr || result.stdout || 'OpenCode helper doctor failed',
+    };
+}

package/dist/sandbox/core/docker-archive-utils.d.ts

@@ -0,0 +1,3 @@
+import type Dockerode from 'dockerode';
+export declare function getFileFromContainer(container: Dockerode.Container, filePath: string): Promise<Buffer>;
+export declare function putFileToContainer(container: Dockerode.Container, filePath: string, content: Buffer): Promise<void>;