@intent-systems/nexus 2026.1.5-3

package/dist/commands/onboard-quickstart.js

@@ -0,0 +1,185 @@
+import net from "node:net";
+import { CONFIG_PATH_NEXUS, readConfigFileSnapshot, resolveGatewayPort, writeConfigFile, } from "../config/config.js";
+import { resolveGatewayService } from "../daemon/service.js";
+import { resolveGatewayProgramArguments } from "../daemon/program-args.js";
+import { GATEWAY_LAUNCH_AGENT_LABEL } from "../daemon/constants.js";
+import { ensureControlUiAssetsBuilt } from "../infra/control-ui-assets.js";
+import { defaultRuntime } from "../runtime.js";
+import { resolveUserPath, sleep } from "../utils.js";
+import { healthCommand } from "./health.js";
+import { applyAuthProfileConfig, setAnthropicApiKey } from "./onboard-auth.js";
+import { applyBootstrapPreset } from "./bootstrap-preset.js";
+import { applyWizardMetadata, DEFAULT_WORKSPACE, detectBrowserOpenSupport, ensureWorkspaceAndSessions, openUrl, resolveControlUiLinks, } from "./onboard-helpers.js";
+import { CLAUDE_CLI_PROFILE_ID, CODEX_CLI_PROFILE_ID, ensureAuthProfileStore, } from "../agents/auth-profiles.js";
+import { ensureSystemdUserLingerNonInteractive } from "./systemd-linger.js";
+import { applyOpenAICodexModelDefault } from "./openai-codex-model-default.js";
+async function isPortFree(port) {
+    try {
+        await new Promise((resolve, reject) => {
+            const s = net
+                .createServer()
+                .once("error", (err) => reject(err))
+                .once("listening", () => s.close(() => resolve()))
+                .listen(port, "127.0.0.1");
+        });
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "EADDRINUSE")
+            return false;
+        return false;
+    }
+}
+async function pickGatewayPort(preferred) {
+    // Prefer the canonical port unless it's already taken.
+    if (preferred > 0 && (await isPortFree(preferred)))
+        return preferred;
+    // Fall back to an OS-assigned free port.
+    return await new Promise((resolve, reject) => {
+        const s = net.createServer();
+        s.once("error", (err) => reject(err));
+        s.listen(0, "127.0.0.1", () => {
+            const addr = s.address();
+            if (!addr || typeof addr === "string") {
+                s.close(() => reject(new Error("Unable to allocate free port")));
+                return;
+            }
+            const port = addr.port;
+            s.close(() => resolve(port));
+        });
+    });
+}
+function applyQuickstartAuth(cfg, runtime) {
+    // Sync external credentials (Keychain on macOS, ~/.claude, ~/.codex) into the store.
+    const store = ensureAuthProfileStore();
+    // 1) Prefer OpenAI Codex credentials if present (works without API keys).
+    if (store.profiles[CODEX_CLI_PROFILE_ID]) {
+        const withProfile = applyAuthProfileConfig(cfg, {
+            profileId: CODEX_CLI_PROFILE_ID,
+            provider: "openai-codex",
+            mode: "oauth",
+        });
+        return applyOpenAICodexModelDefault(withProfile).next;
+    }
+    // 2) Anthropic API key (pay-as-you-go) if present in env.
+    const anthropicKey = process.env.ANTHROPIC_API_KEY?.trim();
+    if (anthropicKey) {
+        // Store it in auth profiles so the daemon can use it.
+        void setAnthropicApiKey(anthropicKey).catch(() => {
+            // best-effort; wizard can still proceed without it
+        });
+        return applyAuthProfileConfig(cfg, {
+            profileId: "anthropic:default",
+            provider: "anthropic",
+            mode: "api_key",
+        });
+    }
+    // 3) Claude Code / Claude CLI credentials are detectable, but are not guaranteed to be
+    // valid for general Anthropic API requests. We avoid auto-selecting them here.
+    // Users can still opt in via `nexus onboard` interactive.
+    if (store.profiles[CLAUDE_CLI_PROFILE_ID]) {
+        runtime.log('Detected Claude Code credentials, but Nexus may require an Anthropic API key (or another provider) for API access. Run `nexus onboard` to choose billing/auth.');
+    }
+    runtime.log("No Claude/Codex credentials detected yet. You can set this later via `nexus onboard` or `nexus configure`.");
+    return cfg;
+}
+export async function runQuickstartOnboarding(opts, runtime = defaultRuntime) {
+    const snapshot = await readConfigFileSnapshot();
+    const baseConfig = snapshot.valid ? snapshot.config : {};
+    // Quickstart is intentionally local-only.
+    if (opts.mode === "remote") {
+        runtime.error("Quickstart only supports local gateway mode.");
+        runtime.exit(1);
+        return;
+    }
+    const workspaceDir = resolveUserPath((opts.workspace ?? baseConfig.agent?.workspace ?? DEFAULT_WORKSPACE).trim());
+    // Choose a port (prefer default, fall back if busy).
+    const preferredPort = resolveGatewayPort(baseConfig);
+    const port = await pickGatewayPort(preferredPort);
+    let nextConfig = {
+        ...baseConfig,
+        agent: {
+            ...baseConfig.agent,
+            workspace: workspaceDir,
+        },
+        gateway: {
+            ...baseConfig.gateway,
+            mode: "local",
+            port,
+            bind: "loopback",
+            // Auth omitted means "off" for loopback-only gateway.
+            tailscale: { ...baseConfig.gateway?.tailscale, mode: "off" },
+        },
+    };
+    nextConfig = applyQuickstartAuth(nextConfig, runtime);
+    nextConfig = applyWizardMetadata(nextConfig, { command: "onboard", mode: "local" });
+    await writeConfigFile(nextConfig);
+    runtime.log(`Updated ${CONFIG_PATH_NEXUS}`);
+    await ensureWorkspaceAndSessions(workspaceDir, runtime, {
+        skipBootstrap: Boolean(nextConfig.agent?.skipBootstrap),
+    });
+    // Scripted bootstrap (test harness / automation): fill identity files + delete BOOTSTRAP.md.
+    if (opts.bootstrapPreset || opts.bootstrapAgentName || opts.bootstrapUserName) {
+        await applyBootstrapPreset({
+            workspaceDir,
+            runtime,
+            preset: opts.bootstrapPreset,
+            agentName: opts.bootstrapAgentName,
+            userName: opts.bootstrapUserName,
+            preferredAddress: opts.bootstrapPreferredAddress,
+            useEve: opts.bootstrapUseEve,
+        });
+    }
+    // Install the gateway daemon automatically unless explicitly disabled.
+    const installDaemon = opts.installDaemon !== undefined ? opts.installDaemon : true;
+    if (installDaemon) {
+        await ensureSystemdUserLingerNonInteractive({ runtime, env: process.env });
+        const service = resolveGatewayService();
+        const loaded = await service.isLoaded({ env: process.env });
+        if (!loaded) {
+            const devMode = process.argv[1]?.includes("/src/") && process.argv[1]?.endsWith(".ts");
+            const { programArguments, workingDirectory } = await resolveGatewayProgramArguments({ port, dev: devMode });
+            const environment = {
+                PATH: process.env.PATH,
+                NEXUS_LAUNCHD_LABEL: process.platform === "darwin" ? GATEWAY_LAUNCH_AGENT_LABEL : undefined,
+            };
+            await service.install({
+                env: process.env,
+                stdout: process.stdout,
+                programArguments,
+                workingDirectory,
+                environment,
+            });
+        }
+        else {
+            // If already installed, restart to pick up config changes like port.
+            await service.restart({ stdout: process.stdout });
+        }
+    }
+    if (!opts.skipHealth) {
+        await sleep(1200);
+        try {
+            await healthCommand({ json: false, timeoutMs: 10_000 }, runtime);
+        }
+        catch (err) {
+            runtime.error(`Health check failed: ${String(err)}`);
+        }
+    }
+    // Best-effort build for the Control UI.
+    const controlUiAssets = await ensureControlUiAssetsBuilt(runtime);
+    if (!controlUiAssets.ok && controlUiAssets.message) {
+        runtime.error(controlUiAssets.message);
+    }
+    const links = resolveControlUiLinks({
+        bind: "loopback",
+        port,
+        basePath: baseConfig.gateway?.controlUi?.basePath,
+    });
+    runtime.log(`Control UI: ${links.httpUrl}`);
+    runtime.log(`Gateway WS: ${links.wsUrl}`);
+    const browserSupport = await detectBrowserOpenSupport();
+    if (browserSupport.ok) {
+        await openUrl(links.httpUrl);
+    }
+}

package/dist/commands/onboard-remote.js

@@ -0,0 +1,120 @@
+import { discoverGatewayBeacons } from "../infra/bonjour-discovery.js";
+import { detectBinary } from "./onboard-helpers.js";
+const DEFAULT_GATEWAY_URL = "ws://127.0.0.1:18789";
+function pickHost(beacon) {
+    return beacon.tailnetDns || beacon.lanHost || beacon.host;
+}
+function buildLabel(beacon) {
+    const host = pickHost(beacon);
+    const port = beacon.gatewayPort ?? beacon.port ?? 18789;
+    const title = beacon.displayName ?? beacon.instanceName;
+    const hint = host ? `${host}:${port}` : "host unknown";
+    return `${title} (${hint})`;
+}
+function ensureWsUrl(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return DEFAULT_GATEWAY_URL;
+    return trimmed;
+}
+export async function promptRemoteGatewayConfig(cfg, prompter) {
+    let selectedBeacon = null;
+    let suggestedUrl = cfg.gateway?.remote?.url ?? DEFAULT_GATEWAY_URL;
+    const hasBonjourTool = (await detectBinary("dns-sd")) || (await detectBinary("avahi-browse"));
+    const wantsDiscover = hasBonjourTool
+        ? await prompter.confirm({
+            message: "Discover gateway on LAN (Bonjour)?",
+            initialValue: true,
+        })
+        : false;
+    if (!hasBonjourTool) {
+        await prompter.note("Bonjour discovery requires dns-sd (macOS) or avahi-browse (Linux).", "Discovery");
+    }
+    if (wantsDiscover) {
+        const spin = prompter.progress("Searching for gateways…");
+        const beacons = await discoverGatewayBeacons({ timeoutMs: 2000 });
+        spin.stop(beacons.length > 0
+            ? `Found ${beacons.length} gateway(s)`
+            : "No gateways found");
+        if (beacons.length > 0) {
+            const selection = await prompter.select({
+                message: "Select gateway",
+                options: [
+                    ...beacons.map((beacon, index) => ({
+                        value: String(index),
+                        label: buildLabel(beacon),
+                    })),
+                    { value: "manual", label: "Enter URL manually" },
+                ],
+            });
+            if (selection !== "manual") {
+                const idx = Number.parseInt(String(selection), 10);
+                selectedBeacon = Number.isFinite(idx) ? (beacons[idx] ?? null) : null;
+            }
+        }
+    }
+    if (selectedBeacon) {
+        const host = pickHost(selectedBeacon);
+        const port = selectedBeacon.gatewayPort ?? 18789;
+        if (host) {
+            const mode = await prompter.select({
+                message: "Connection method",
+                options: [
+                    {
+                        value: "direct",
+                        label: `Direct gateway WS (${host}:${port})`,
+                    },
+                    { value: "ssh", label: "SSH tunnel (loopback)" },
+                ],
+            });
+            if (mode === "direct") {
+                suggestedUrl = `ws://${host}:${port}`;
+            }
+            else {
+                suggestedUrl = DEFAULT_GATEWAY_URL;
+                await prompter.note([
+                    "Start a tunnel before using the CLI:",
+                    `ssh -N -L 18789:127.0.0.1:18789 <user>@${host}${selectedBeacon.sshPort ? ` -p ${selectedBeacon.sshPort}` : ""}`,
+                ].join("\n"), "SSH tunnel");
+            }
+        }
+    }
+    const urlInput = await prompter.text({
+        message: "Gateway WebSocket URL",
+        initialValue: suggestedUrl,
+        validate: (value) => String(value).trim().startsWith("ws://") ||
+            String(value).trim().startsWith("wss://")
+            ? undefined
+            : "URL must start with ws:// or wss://",
+    });
+    const url = ensureWsUrl(String(urlInput));
+    const authChoice = (await prompter.select({
+        message: "Gateway auth",
+        options: [
+            { value: "token", label: "Token (recommended)" },
+            { value: "off", label: "No auth" },
+        ],
+    }));
+    let token = cfg.gateway?.remote?.token ?? "";
+    if (authChoice === "token") {
+        token = String(await prompter.text({
+            message: "Gateway token",
+            initialValue: token,
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+        })).trim();
+    }
+    else {
+        token = "";
+    }
+    return {
+        ...cfg,
+        gateway: {
+            ...cfg.gateway,
+            mode: "remote",
+            remote: {
+                url,
+                token: token || undefined,
+            },
+        },
+    };
+}

package/dist/commands/onboard-skills.js

@@ -0,0 +1,148 @@
+import { installSkill } from "../agents/skills-install.js";
+import { buildWorkspaceSkillStatus } from "../agents/skills-status.js";
+import { detectBinary, resolveNodeManagerOptions } from "./onboard-helpers.js";
+function summarizeInstallFailure(message) {
+    const cleaned = message
+        .replace(/^Install failed(?:\s*\([^)]*\))?\s*:?\s*/i, "")
+        .trim();
+    if (!cleaned)
+        return undefined;
+    const maxLen = 140;
+    return cleaned.length > maxLen ? `${cleaned.slice(0, maxLen - 1)}…` : cleaned;
+}
+function formatSkillHint(skill) {
+    const desc = skill.description?.trim();
+    const installLabel = skill.install[0]?.label?.trim();
+    const combined = desc && installLabel ? `${desc} — ${installLabel}` : desc || installLabel;
+    if (!combined)
+        return "install";
+    const maxLen = 90;
+    return combined.length > maxLen
+        ? `${combined.slice(0, maxLen - 1)}…`
+        : combined;
+}
+function upsertSkillEntry(cfg, skillKey, patch) {
+    const entries = { ...cfg.skills?.entries };
+    const existing = entries[skillKey] ?? {};
+    entries[skillKey] = { ...existing, ...patch };
+    return {
+        ...cfg,
+        skills: {
+            ...cfg.skills,
+            entries,
+        },
+    };
+}
+export async function setupSkills(cfg, workspaceDir, runtime, prompter) {
+    const report = buildWorkspaceSkillStatus(workspaceDir, { config: cfg });
+    const eligible = report.skills.filter((s) => s.eligible);
+    const missing = report.skills.filter((s) => !s.eligible && !s.disabled && !s.blockedByAllowlist);
+    const blocked = report.skills.filter((s) => s.blockedByAllowlist);
+    const needsBrewPrompt = process.platform !== "win32" &&
+        report.skills.some((skill) => skill.install.some((option) => option.kind === "brew")) &&
+        !(await detectBinary("brew"));
+    await prompter.note([
+        `Eligible: ${eligible.length}`,
+        `Missing requirements: ${missing.length}`,
+        `Blocked by allowlist: ${blocked.length}`,
+    ].join("\n"), "Skills status");
+    const shouldConfigure = await prompter.confirm({
+        message: "Configure skills now? (recommended)",
+        initialValue: true,
+    });
+    if (!shouldConfigure)
+        return cfg;
+    if (needsBrewPrompt) {
+        await prompter.note([
+            "Many skill dependencies are shipped via Homebrew.",
+            "Without brew, you'll need to build from source or download releases manually.",
+        ].join("\n"), "Homebrew recommended");
+        const showBrewInstall = await prompter.confirm({
+            message: "Show Homebrew install command?",
+            initialValue: true,
+        });
+        if (showBrewInstall) {
+            await prompter.note([
+                "Run:",
+                '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"',
+            ].join("\n"), "Homebrew install");
+        }
+    }
+    const nodeManager = (await prompter.select({
+        message: "Preferred node manager for skill installs",
+        options: resolveNodeManagerOptions(),
+    }));
+    let next = {
+        ...cfg,
+        skills: {
+            ...cfg.skills,
+            install: {
+                ...cfg.skills?.install,
+                nodeManager,
+            },
+        },
+    };
+    const installable = missing.filter((skill) => skill.install.length > 0 && skill.missing.bins.length > 0);
+    if (installable.length > 0) {
+        const toInstall = await prompter.multiselect({
+            message: "Install missing skill dependencies",
+            options: [
+                {
+                    value: "__skip__",
+                    label: "Skip for now",
+                    hint: "Continue without installing dependencies",
+                },
+                ...installable.map((skill) => ({
+                    value: skill.name,
+                    label: `${skill.emoji ?? "🧩"} ${skill.name}`,
+                    hint: formatSkillHint(skill),
+                })),
+            ],
+        });
+        const selected = toInstall.filter((name) => name !== "__skip__");
+        for (const name of selected) {
+            const target = installable.find((s) => s.name === name);
+            if (!target || target.install.length === 0)
+                continue;
+            const installId = target.install[0]?.id;
+            if (!installId)
+                continue;
+            const spin = prompter.progress(`Installing ${name}…`);
+            const result = await installSkill({
+                workspaceDir,
+                skillName: target.name,
+                installId,
+                config: next,
+            });
+            if (result.ok) {
+                spin.stop(`Installed ${name}`);
+            }
+            else {
+                const code = result.code == null ? "" : ` (exit ${result.code})`;
+                const detail = summarizeInstallFailure(result.message);
+                spin.stop(`Install failed: ${name}${code}${detail ? ` — ${detail}` : ""}`);
+                if (result.stderr)
+                    runtime.log(result.stderr.trim());
+                else if (result.stdout)
+                    runtime.log(result.stdout.trim());
+                runtime.log("Tip: run `nexus doctor` to review skills + requirements.");
+            }
+        }
+    }
+    for (const skill of missing) {
+        if (!skill.primaryEnv || skill.missing.env.length === 0)
+            continue;
+        const wantsKey = await prompter.confirm({
+            message: `Set ${skill.primaryEnv} for ${skill.name}?`,
+            initialValue: false,
+        });
+        if (!wantsKey)
+            continue;
+        const apiKey = String(await prompter.text({
+            message: `Enter ${skill.primaryEnv}`,
+            validate: (value) => (value?.trim() ? undefined : "Required"),
+        }));
+        next = upsertSkillEntry(next, skill.skillKey, { apiKey: apiKey.trim() });
+    }
+    return next;
+}

package/dist/commands/onboard-types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/onboard.js

@@ -0,0 +1,19 @@
+import { assertSupportedRuntime } from "../infra/runtime-guard.js";
+import { defaultRuntime } from "../runtime.js";
+import { runInteractiveOnboarding } from "./onboard-interactive.js";
+import { runNonInteractiveOnboarding } from "./onboard-non-interactive.js";
+import { runQuickstartOnboarding } from "./onboard-quickstart.js";
+export async function onboardCommand(opts, runtime = defaultRuntime) {
+    assertSupportedRuntime(runtime);
+    // QuickStart is already non-interactive; allow combining with --non-interactive
+    // (useful for test harness flows).
+    if (opts.quickstart) {
+        await runQuickstartOnboarding(opts, runtime);
+        return;
+    }
+    if (opts.nonInteractive) {
+        await runNonInteractiveOnboarding(opts, runtime);
+        return;
+    }
+    await runInteractiveOnboarding(opts, runtime);
+}

package/dist/commands/openai-codex-model-default.js

@@ -0,0 +1,38 @@
+export const OPENAI_CODEX_DEFAULT_MODEL = "openai-codex/gpt-5.2";
+function shouldSetOpenAICodexModel(model) {
+    const trimmed = model?.trim();
+    if (!trimmed)
+        return true;
+    const normalized = trimmed.toLowerCase();
+    if (normalized.startsWith("openai-codex/"))
+        return false;
+    if (normalized.startsWith("openai/"))
+        return true;
+    return normalized === "gpt" || normalized === "gpt-mini";
+}
+function resolvePrimaryModel(model) {
+    if (typeof model === "string")
+        return model;
+    if (model && typeof model === "object" && typeof model.primary === "string") {
+        return model.primary;
+    }
+    return undefined;
+}
+export function applyOpenAICodexModelDefault(cfg) {
+    const current = resolvePrimaryModel(cfg.agent?.model);
+    if (!shouldSetOpenAICodexModel(current)) {
+        return { next: cfg, changed: false };
+    }
+    return {
+        next: {
+            ...cfg,
+            agent: {
+                ...cfg.agent,
+                model: cfg.agent?.model && typeof cfg.agent.model === "object"
+                    ? { ...cfg.agent.model, primary: OPENAI_CODEX_DEFAULT_MODEL }
+                    : { primary: OPENAI_CODEX_DEFAULT_MODEL },
+            },
+        },
+        changed: true,
+    };
+}

package/dist/commands/poll.js

@@ -0,0 +1,64 @@
+import { callGateway, randomIdempotencyKey } from "../gateway/call.js";
+import { success } from "../globals.js";
+import { normalizePollInput } from "../polls.js";
+function parseIntOption(value, label) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`${label} must be a number`);
+    }
+    return parsed;
+}
+export async function pollCommand(opts, _deps, runtime) {
+    const provider = (opts.provider ?? "whatsapp").toLowerCase();
+    if (provider !== "whatsapp" && provider !== "discord") {
+        throw new Error(`Unsupported poll provider: ${provider}`);
+    }
+    const maxSelections = parseIntOption(opts.maxSelections, "max-selections");
+    const durationHours = parseIntOption(opts.durationHours, "duration-hours");
+    const pollInput = {
+        question: opts.question,
+        options: opts.option,
+        maxSelections,
+        durationHours,
+    };
+    const maxOptions = provider === "discord" ? 10 : 12;
+    const normalized = normalizePollInput(pollInput, { maxOptions });
+    if (opts.dryRun) {
+        runtime.log(`[dry-run] would send poll via ${provider} -> ${opts.to}:\n  Question: ${normalized.question}\n  Options: ${normalized.options.join(", ")}\n  Max selections: ${normalized.maxSelections}`);
+        return;
+    }
+    const result = await callGateway({
+        method: "poll",
+        params: {
+            to: opts.to,
+            question: normalized.question,
+            options: normalized.options,
+            maxSelections: normalized.maxSelections,
+            durationHours: normalized.durationHours,
+            provider,
+            idempotencyKey: randomIdempotencyKey(),
+        },
+        timeoutMs: 10_000,
+        clientName: "cli",
+        mode: "cli",
+    });
+    runtime.log(success(`✅ Poll sent via gateway (${provider}). Message ID: ${result.messageId ?? "unknown"}`));
+    if (opts.json) {
+        runtime.log(JSON.stringify({
+            provider,
+            via: "gateway",
+            to: opts.to,
+            toJid: result.toJid ?? null,
+            channelId: result.channelId ?? null,
+            messageId: result.messageId,
+            question: normalized.question,
+            options: normalized.options,
+            maxSelections: normalized.maxSelections,
+            durationHours: normalized.durationHours ?? null,
+        }, null, 2));
+    }
+}

package/dist/commands/quest.js

@@ -0,0 +1,27 @@
+import { defaultRuntime } from "../runtime.js";
+import { detectCapabilities } from "../capabilities/detector.js";
+export async function questCommand(opts, runtime = defaultRuntime) {
+    const snapshot = detectCapabilities();
+    const suggestions = snapshot.capabilities
+        .filter((cap) => ["needs_setup", "needs_install", "ready"].includes(cap.status))
+        .slice(0, 5)
+        .map((cap) => ({
+        id: cap.id,
+        status: cap.status,
+        providers: cap.providers.map((p) => p.id),
+    }));
+    if (opts?.json) {
+        runtime.log(JSON.stringify({
+            suggestions,
+        }, null, 2));
+        return;
+    }
+    if (suggestions.length === 0) {
+        runtime.log("No quests found. You're fully configured.");
+        return;
+    }
+    runtime.log("Quests");
+    for (const [idx, item] of suggestions.entries()) {
+        runtime.log(`  ${idx + 1}. ${item.id} (${item.status})`);
+    }
+}

package/dist/commands/reset.js

@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { defaultRuntime } from "../runtime.js";
+/**
+ * Removes Nexus directories for testing purposes.
+ * Requires --confirm flag to actually delete.
+ */
+export async function resetCommand(opts = {}, runtime = defaultRuntime) {
+    const { local = false, state = false, all = false, confirm = false, workspace } = opts;
+    // Validate: at least one target must be specified
+    if (!local && !state && !all) {
+        throw new Error("Must specify at least one target: --local, --state, or --all");
+    }
+    // Validate: --confirm is required for safety
+    if (!confirm) {
+        runtime.log("⚠️  Dry run mode (no files will be deleted)");
+        runtime.log("   Add --confirm to actually delete directories\n");
+    }
+    // Determine which directories to remove
+    const shouldRemoveLocal = local || all;
+    const shouldRemoveState = state || all;
+    const workspaceDir = workspace?.trim() || path.join(process.env.HOME || "~", "nexus", "home");
+    const stateDir = resolveStateDir();
+    // Show what will be removed
+    if (shouldRemoveLocal) {
+        runtime.log(`${confirm ? "🗑️" : "Would delete"} workspace: ${workspaceDir}`);
+    }
+    if (shouldRemoveState) {
+        runtime.log(`${confirm ? "🗑️" : "Would delete"} state: ${stateDir}`);
+    }
+    // Actually remove directories if --confirm is set
+    if (confirm) {
+        runtime.log("");
+        if (shouldRemoveLocal) {
+            try {
+                await fs.rm(workspaceDir, { recursive: true, force: true });
+                runtime.log(`✓ Removed workspace: ${workspaceDir}`);
+            }
+            catch (err) {
+                const error = err;
+                runtime.log(`✗ Failed to remove workspace: ${error.message}`);
+            }
+        }
+        if (shouldRemoveState) {
+            try {
+                await fs.rm(stateDir, { recursive: true, force: true });
+                runtime.log(`✓ Removed state: ${stateDir}`);
+            }
+            catch (err) {
+                const error = err;
+                runtime.log(`✗ Failed to remove state: ${error.message}`);
+            }
+        }
+        runtime.log("\nReset complete!");
+        runtime.log("Run 'nexus init' to recreate directories");
+    }
+    else {
+        runtime.log("\nNo changes made. Add --confirm to proceed.");
+    }
+}