@intent-systems/nexus 2026.1.5-3

package/dist/cli/nodes-screen.js

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import { writeBase64ToFile } from "./nodes-camera.js";
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function parseScreenRecordPayload(value) {
+    const obj = asRecord(value);
+    const format = asString(obj.format);
+    const base64 = asString(obj.base64);
+    if (!format || !base64) {
+        throw new Error("invalid screen.record payload");
+    }
+    return {
+        format,
+        base64,
+        durationMs: typeof obj.durationMs === "number" ? obj.durationMs : undefined,
+        fps: typeof obj.fps === "number" ? obj.fps : undefined,
+        screenIndex: typeof obj.screenIndex === "number" ? obj.screenIndex : undefined,
+        hasAudio: typeof obj.hasAudio === "boolean" ? obj.hasAudio : undefined,
+    };
+}
+export function screenRecordTempPath(opts) {
+    const tmpDir = opts.tmpDir ?? os.tmpdir();
+    const id = opts.id ?? randomUUID();
+    const ext = opts.ext.startsWith(".") ? opts.ext : `.${opts.ext}`;
+    return path.join(tmpDir, `nexus-screen-record-${id}${ext}`);
+}
+export async function writeScreenRecordToFile(filePath, base64) {
+    return writeBase64ToFile(filePath, base64);
+}

package/dist/cli/pairing-cli.js

@@ -0,0 +1,100 @@
+import { loadConfig } from "../config/config.js";
+import { sendMessageDiscord } from "../discord/send.js";
+import { sendMessageIMessage } from "../imessage/send.js";
+import { approveProviderPairingCode, listProviderPairingRequests, } from "../pairing/pairing-store.js";
+import { sendMessageSignal } from "../signal/send.js";
+import { sendMessageSlack } from "../slack/send.js";
+import { sendMessageTelegram } from "../telegram/send.js";
+import { resolveTelegramToken } from "../telegram/token.js";
+const PROVIDERS = [
+    "telegram",
+    "signal",
+    "imessage",
+    "discord",
+    "slack",
+    "whatsapp",
+];
+function parseProvider(raw) {
+    const value = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (PROVIDERS.includes(value))
+        return value;
+    throw new Error(`Invalid provider: ${value || "(empty)"} (expected one of: ${PROVIDERS.join(", ")})`);
+}
+async function notifyApproved(provider, id) {
+    const message = "✅ Nexus access approved. Send a message to start chatting.";
+    if (provider === "telegram") {
+        const cfg = loadConfig();
+        const { token } = resolveTelegramToken(cfg);
+        if (!token)
+            throw new Error("telegram token not configured");
+        await sendMessageTelegram(id, message, { token });
+        return;
+    }
+    if (provider === "discord") {
+        await sendMessageDiscord(`user:${id}`, message);
+        return;
+    }
+    if (provider === "slack") {
+        await sendMessageSlack(`user:${id}`, message);
+        return;
+    }
+    if (provider === "signal") {
+        await sendMessageSignal(id, message);
+        return;
+    }
+    if (provider === "imessage") {
+        await sendMessageIMessage(id, message);
+        return;
+    }
+    // WhatsApp: approval still works (store); notifying requires an active web session.
+}
+export function registerPairingCli(program) {
+    const pairing = program
+        .command("pairing")
+        .description("Secure DM pairing (approve inbound requests)");
+    pairing
+        .command("list")
+        .description("List pending pairing requests")
+        .requiredOption("--provider <provider>", `Provider (${PROVIDERS.join(", ")})`)
+        .option("--json", "Print JSON", false)
+        .action(async (opts) => {
+        const provider = parseProvider(opts.provider);
+        const requests = await listProviderPairingRequests(provider);
+        if (opts.json) {
+            console.log(JSON.stringify({ provider, requests }, null, 2));
+            return;
+        }
+        if (requests.length === 0) {
+            console.log(`No pending ${provider} pairing requests.`);
+            return;
+        }
+        for (const r of requests) {
+            const meta = r.meta ? JSON.stringify(r.meta) : "";
+            console.log(`${r.code}  id=${r.id}${meta ? `  meta=${meta}` : ""}  ${r.createdAt}`);
+        }
+    });
+    pairing
+        .command("approve")
+        .description("Approve a pairing code and allow that sender")
+        .requiredOption("--provider <provider>", `Provider (${PROVIDERS.join(", ")})`)
+        .argument("<code>", "Pairing code (shown to the requester)")
+        .option("--notify", "Notify the requester on the same provider", false)
+        .action(async (code, opts) => {
+        const provider = parseProvider(opts.provider);
+        const approved = await approveProviderPairingCode({
+            provider,
+            code: String(code),
+        });
+        if (!approved) {
+            throw new Error(`No pending pairing request found for code: ${code}`);
+        }
+        console.log(`Approved ${provider} sender ${approved.id}.`);
+        if (!opts.notify)
+            return;
+        await notifyApproved(provider, approved.id).catch((err) => {
+            console.log(`Failed to notify requester: ${String(err)}`);
+        });
+    });
+}

package/dist/cli/parse-duration.js

@@ -0,0 +1,20 @@
+export function parseDurationMs(raw, opts) {
+    const trimmed = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (!trimmed)
+        throw new Error("invalid duration (empty)");
+    const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(trimmed);
+    if (!m)
+        throw new Error(`invalid duration: ${raw}`);
+    const value = Number(m[1]);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`invalid duration: ${raw}`);
+    }
+    const unit = (m[2] ?? opts?.defaultUnit ?? "ms");
+    const multiplier = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : 3_600_000;
+    const ms = Math.round(value * multiplier);
+    if (!Number.isFinite(ms))
+        throw new Error(`invalid duration: ${raw}`);
+    return ms;
+}

package/dist/cli/plugins-cli.js

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { loadConfig, writeConfigFile } from "../config/config.js";
+import { defaultRuntime } from "../runtime.js";
+import { resolveUserPath } from "../utils.js";
+import { registerPluginCliCommands } from "../plugins/cli.js";
+import { installPluginFromArchive, installPluginFromNpmSpec } from "../plugins/install.js";
+import { buildPluginStatusReport } from "../plugins/status.js";
+function formatPluginsList(report) {
+    const rows = report.plugins.map((p) => {
+        const status = p.status === "loaded"
+            ? chalk.green("loaded")
+            : p.status === "disabled"
+                ? chalk.gray("disabled")
+                : chalk.red("error");
+        const enabled = p.enabled ? chalk.green("yes") : chalk.gray("no");
+        const name = p.name || p.id;
+        const origin = p.origin;
+        const version = p.version ?? "";
+        const tools = p.toolNames.length;
+        const methods = p.gatewayMethods.length;
+        const error = p.error ? chalk.red(p.error) : "";
+        return { id: p.id, name, version, enabled, status, origin, tools, methods, error };
+    });
+    if (rows.length === 0) {
+        defaultRuntime.log(chalk.gray("No plugins discovered."));
+        return;
+    }
+    // Basic fixed-width table (keep it dependency-free).
+    const pad = (s, n) => (s.length >= n ? s : s + " ".repeat(n - s.length));
+    const colId = Math.min(32, Math.max(8, ...rows.map((r) => r.id.length)));
+    const colName = Math.min(32, Math.max(8, ...rows.map((r) => r.name.length)));
+    defaultRuntime.log([
+        `${pad("id", colId)}  ${pad("name", colName)}  enabled  status    origin    v    tools  methods  error`,
+        `${"-".repeat(colId)}  ${"-".repeat(colName)}  ------   ------    ------    -    -----  -------  -----`,
+        ...rows.map((r) => {
+            return `${pad(r.id, colId)}  ${pad(r.name, colName)}  ${pad(String(r.enabled), 7)}  ${pad(String(r.status), 8)}  ${pad(String(r.origin), 8)}  ${pad(String(r.version), 4)}  ${pad(String(r.tools), 5)}  ${pad(String(r.methods), 7)}  ${r.error}`;
+        }),
+    ].join("\n"));
+}
+export function registerPluginsCli(program) {
+    const plugins = program.command("plugins").description("Plugin management");
+    plugins
+        .command("list")
+        .description("List discovered plugins")
+        .action(async () => {
+        const report = buildPluginStatusReport();
+        formatPluginsList(report);
+    });
+    plugins
+        .command("status")
+        .description("Show plugin registry (diagnostics, tools, gateway methods)")
+        .action(async () => {
+        const report = buildPluginStatusReport();
+        formatPluginsList(report);
+        if (report.diagnostics.length > 0) {
+            defaultRuntime.log("");
+            defaultRuntime.log(chalk.bold("Diagnostics:"));
+            for (const diag of report.diagnostics) {
+                const prefix = diag.level === "error" ? chalk.red("error") : chalk.yellow("warn");
+                defaultRuntime.log(`- ${prefix}: ${diag.message}`);
+            }
+        }
+    });
+    plugins
+        .command("install")
+        .description("Install a plugin (path, archive, or npm spec)")
+        .argument("<path-or-spec>", "Path (.ts/.js/.tgz) or an npm package spec")
+        .action(async (raw) => {
+        const resolved = resolveUserPath(raw);
+        const cfg = loadConfig();
+        if (fs.existsSync(resolved)) {
+            const ext = path.extname(resolved).toLowerCase();
+            if (ext === ".tgz" || resolved.endsWith(".tar.gz")) {
+                const result = await installPluginFromArchive({
+                    archivePath: resolved,
+                    logger: {
+                        info: (msg) => defaultRuntime.log(msg),
+                        warn: (msg) => defaultRuntime.log(chalk.yellow(msg)),
+                    },
+                });
+                if (!result.ok) {
+                    defaultRuntime.error(result.error);
+                    process.exit(1);
+                }
+                const next = {
+                    ...cfg,
+                    plugins: {
+                        ...cfg.plugins,
+                        entries: {
+                            ...(cfg.plugins?.entries ?? {}),
+                            [result.pluginId]: {
+                                ...cfg.plugins?.entries?.[result.pluginId],
+                                enabled: true,
+                            },
+                        },
+                    },
+                };
+                await writeConfigFile(next);
+                defaultRuntime.log(`Installed plugin: ${result.pluginId}`);
+                defaultRuntime.log("Restart the gateway to load plugins.");
+                return;
+            }
+            // Treat as a direct load path.
+            const existing = cfg.plugins?.load?.paths ?? [];
+            const merged = Array.from(new Set([...existing, resolved]));
+            const next = {
+                ...cfg,
+                plugins: {
+                    ...cfg.plugins,
+                    load: {
+                        ...cfg.plugins?.load,
+                        paths: merged,
+                    },
+                    enabled: cfg.plugins?.enabled,
+                    allow: cfg.plugins?.allow,
+                    deny: cfg.plugins?.deny,
+                    entries: cfg.plugins?.entries,
+                },
+            };
+            await writeConfigFile(next);
+            defaultRuntime.log(`Added plugin load path: ${resolved}`);
+            defaultRuntime.log("Restart the gateway to load plugins.");
+            return;
+        }
+        // Not a path: treat as npm spec
+        const result = await installPluginFromNpmSpec({
+            spec: raw,
+            logger: {
+                info: (msg) => defaultRuntime.log(msg),
+                warn: (msg) => defaultRuntime.log(chalk.yellow(msg)),
+            },
+        });
+        if (!result.ok) {
+            defaultRuntime.error(result.error);
+            process.exit(1);
+        }
+        const next = {
+            ...cfg,
+            plugins: {
+                ...cfg.plugins,
+                entries: {
+                    ...(cfg.plugins?.entries ?? {}),
+                    [result.pluginId]: {
+                        ...cfg.plugins?.entries?.[result.pluginId],
+                        enabled: true,
+                    },
+                },
+            },
+        };
+        await writeConfigFile(next);
+        defaultRuntime.log(`Installed plugin: ${result.pluginId}`);
+        defaultRuntime.log("Restart the gateway to load plugins.");
+    });
+    // Allow plugins to attach their own CLI commands.
+    registerPluginCliCommands(program);
+}

package/dist/cli/ports.js

@@ -0,0 +1,97 @@
+import { execFileSync } from "node:child_process";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function parseLsofOutput(output) {
+    const lines = output.split(/\r?\n/).filter(Boolean);
+    const results = [];
+    let current = {};
+    for (const line of lines) {
+        if (line.startsWith("p")) {
+            if (current.pid)
+                results.push(current);
+            current = { pid: Number.parseInt(line.slice(1), 10) };
+        }
+        else if (line.startsWith("c")) {
+            current.command = line.slice(1);
+        }
+    }
+    if (current.pid)
+        results.push(current);
+    return results;
+}
+export function listPortListeners(port) {
+    try {
+        const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-FpFc"], { encoding: "utf-8" });
+        return parseLsofOutput(out);
+    }
+    catch (err) {
+        const status = err.status;
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new Error("lsof not found; required for --force");
+        }
+        if (status === 1)
+            return []; // no listeners
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+}
+export function forceFreePort(port) {
+    const listeners = listPortListeners(port);
+    for (const proc of listeners) {
+        try {
+            process.kill(proc.pid, "SIGTERM");
+        }
+        catch (err) {
+            throw new Error(`failed to kill pid ${proc.pid}${proc.command ? ` (${proc.command})` : ""}: ${String(err)}`);
+        }
+    }
+    return listeners;
+}
+function killPids(listeners, signal) {
+    for (const proc of listeners) {
+        try {
+            process.kill(proc.pid, signal);
+        }
+        catch (err) {
+            throw new Error(`failed to kill pid ${proc.pid}${proc.command ? ` (${proc.command})` : ""}: ${String(err)}`);
+        }
+    }
+}
+export async function forceFreePortAndWait(port, opts = {}) {
+    const timeoutMs = Math.max(opts.timeoutMs ?? 1500, 0);
+    const intervalMs = Math.max(opts.intervalMs ?? 100, 1);
+    const sigtermTimeoutMs = Math.min(Math.max(opts.sigtermTimeoutMs ?? 600, 0), timeoutMs);
+    const killed = forceFreePort(port);
+    if (killed.length === 0) {
+        return { killed, waitedMs: 0, escalatedToSigkill: false };
+    }
+    let waitedMs = 0;
+    const triesSigterm = intervalMs > 0 ? Math.ceil(sigtermTimeoutMs / intervalMs) : 0;
+    for (let i = 0; i < triesSigterm; i++) {
+        if (listPortListeners(port).length === 0) {
+            return { killed, waitedMs, escalatedToSigkill: false };
+        }
+        await sleep(intervalMs);
+        waitedMs += intervalMs;
+    }
+    if (listPortListeners(port).length === 0) {
+        return { killed, waitedMs, escalatedToSigkill: false };
+    }
+    const remaining = listPortListeners(port);
+    killPids(remaining, "SIGKILL");
+    const remainingBudget = Math.max(timeoutMs - waitedMs, 0);
+    const triesSigkill = intervalMs > 0 ? Math.ceil(remainingBudget / intervalMs) : 0;
+    for (let i = 0; i < triesSigkill; i++) {
+        if (listPortListeners(port).length === 0) {
+            return { killed, waitedMs, escalatedToSigkill: true };
+        }
+        await sleep(intervalMs);
+        waitedMs += intervalMs;
+    }
+    const still = listPortListeners(port);
+    if (still.length === 0) {
+        return { killed, waitedMs, escalatedToSigkill: true };
+    }
+    throw new Error(`port ${port} still has listeners after --force: ${still.map((p) => p.pid).join(", ")}`);
+}

package/dist/cli/profile.js

@@ -0,0 +1,81 @@
+import os from "node:os";
+import path from "node:path";
+function takeValue(raw, next) {
+    if (raw.includes("=")) {
+        const [, value] = raw.split("=", 2);
+        const trimmed = (value ?? "").trim();
+        return { value: trimmed || null, consumedNext: false };
+    }
+    const trimmed = (next ?? "").trim();
+    return { value: trimmed || null, consumedNext: Boolean(next) };
+}
+function isValidProfileName(value) {
+    if (!value)
+        return false;
+    // Keep it path-safe + shell-friendly.
+    return /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(value);
+}
+export function parseCliProfileArgs(argv) {
+    if (argv.length < 2)
+        return { ok: true, profile: null, argv };
+    const out = argv.slice(0, 2);
+    let profile = null;
+    let sawDev = false;
+    const args = argv.slice(2);
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--dev") {
+            if (profile && profile !== "dev") {
+                return { ok: false, error: "Cannot combine --dev with --profile" };
+            }
+            sawDev = true;
+            profile = "dev";
+            continue;
+        }
+        if (arg === "--profile" || arg.startsWith("--profile=")) {
+            if (sawDev) {
+                return { ok: false, error: "Cannot combine --dev with --profile" };
+            }
+            const next = args[i + 1];
+            const { value, consumedNext } = takeValue(arg, next);
+            if (consumedNext)
+                i += 1;
+            if (!value)
+                return { ok: false, error: "--profile requires a value" };
+            if (!isValidProfileName(value)) {
+                return {
+                    ok: false,
+                    error: 'Invalid --profile (use letters, numbers, "_", "-" only)',
+                };
+            }
+            profile = value;
+            continue;
+        }
+        out.push(arg);
+    }
+    return { ok: true, profile, argv: out };
+}
+function resolveProfileStateDir(profile, homedir) {
+    const suffix = profile.toLowerCase() === "default" ? "" : `-${profile}`;
+    return path.join(homedir(), "nexus", `state${suffix}`);
+}
+export function applyCliProfileEnv(params) {
+    const env = params.env ?? process.env;
+    const homedir = params.homedir ?? os.homedir;
+    const profile = params.profile.trim();
+    if (!profile)
+        return;
+    // Convenience only: fill defaults, never override explicit env values.
+    env.NEXUS_PROFILE = profile;
+    const stateDir = env.NEXUS_STATE_DIR?.trim() || resolveProfileStateDir(profile, homedir);
+    if (!env.NEXUS_STATE_DIR?.trim())
+        env.NEXUS_STATE_DIR = stateDir;
+    const configPath = path.join(stateDir, "nexus", "config.json");
+    if (!env.NEXUS_CONFIG_PATH?.trim())
+        env.NEXUS_CONFIG_PATH = configPath;
+    if (profile === "dev" && !env.NEXUS_GATEWAY_PORT?.trim()) {
+        env.NEXUS_GATEWAY_PORT = "19001";
+    }
+}

package/dist/cli/program.js

@@ -0,0 +1,162 @@
+import { Command } from "commander";
+import { capabilitiesCommand } from "../commands/capabilities.js";
+import { configViewCommand } from "../commands/config-view.js";
+import { identityCommand } from "../commands/identity.js";
+import { initCommand } from "../commands/init.js";
+import { questCommand } from "../commands/quest.js";
+import { suggestionsCommand } from "../commands/suggestions.js";
+import { statusCommand } from "../commands/status.js";
+import { updateCommand } from "../commands/update.js";
+import { isNixMode, migrateLegacyConfig, readConfigFileSnapshot, writeConfigFile, } from "../config/config.js";
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+import { VERSION } from "../version.js";
+import { recordCliCommandFinish, recordCliCommandStart } from "../infra/event-log.js";
+import { registerCloudCommand } from "./cloud-cli.js";
+import { registerCredentialCli } from "./credential-cli.js";
+import { registerDnsCli } from "./dns-cli.js";
+import { registerGatewayCli } from "./gateway-cli.js";
+import { registerSkillsCommand } from "./skills-cli.js";
+import { registerSkillsHubCommand } from "./skills-hub-cli.js";
+import { registerToolConnectorCli } from "./tool-connector-cli.js";
+import { registerUsageCli } from "./usage-cli.js";
+function buildCommandPath(cmd) {
+    const parts = [];
+    let current = cmd;
+    while (current) {
+        const name = current.name();
+        if (name)
+            parts.unshift(name);
+        current = current.parent;
+    }
+    if (parts[0] === "nexus")
+        parts.shift();
+    return parts.join(" ").trim();
+}
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name("nexus")
+        .description("Nexus CLI")
+        .version(VERSION)
+        .option("--dev", "Use dev profile")
+        .option("--profile <name>", "Use named profile");
+    program.hook("preAction", async (_thisCommand, actionCommand) => {
+        recordCliCommandStart({
+            commandPath: buildCommandPath(actionCommand),
+            args: actionCommand.args?.map((arg) => String(arg)),
+            options: actionCommand.optsWithGlobals
+                ? actionCommand.optsWithGlobals()
+                : actionCommand.opts(),
+        });
+        if (actionCommand.name() === "init")
+            return;
+        const snapshot = await readConfigFileSnapshot();
+        if (snapshot.legacyIssues.length === 0)
+            return;
+        if (isNixMode) {
+            defaultRuntime.error(danger("Legacy config entries detected while running in Nix mode. Update your Nix config to the latest schema and retry."));
+            process.exit(1);
+        }
+        const migrated = migrateLegacyConfig(snapshot.parsed);
+        if (migrated.config) {
+            await writeConfigFile(migrated.config);
+        }
+    });
+    program.hook("postAction", async () => {
+        recordCliCommandFinish("ok");
+    });
+    program
+        .command("init [workspace]")
+        .description("Create a new nexus workspace")
+        .action(async (workspace) => {
+        await initCommand({ workspace }, defaultRuntime);
+    });
+    program
+        .command("status")
+        .description("Show current status and onboarding guidance")
+        .option("--json", "Output as JSON")
+        .option("--brief", "Compact output")
+        .option("--capabilities", "Focus on capabilities")
+        .option("--credentials", "Focus on credentials")
+        .action(async (opts) => {
+        await statusCommand({
+            json: Boolean(opts.json),
+            brief: Boolean(opts.brief),
+            capabilities: Boolean(opts.capabilities),
+            credentials: Boolean(opts.credentials),
+        }, defaultRuntime);
+    });
+    program
+        .command("capabilities")
+        .description("Show full capabilities map")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await capabilitiesCommand({ json: Boolean(opts.json) }, defaultRuntime);
+    });
+    program
+        .command("map")
+        .description("Alias for capabilities")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await capabilitiesCommand({ json: Boolean(opts.json) }, defaultRuntime);
+    });
+    program
+        .command("quest")
+        .description("Show onboarding quests")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await questCommand({ json: Boolean(opts.json) }, defaultRuntime);
+    });
+    program
+        .command("identity [target]")
+        .description("Show identity files")
+        .option("--json", "Output as JSON")
+        .action(async (target, opts) => {
+        const normalized = target && (target === "user" || target === "agent") ? target : undefined;
+        await identityCommand({ target: normalized, json: Boolean(opts.json) }, defaultRuntime);
+    });
+    program
+        .command("config")
+        .description("Show config path and status")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await configViewCommand({ json: Boolean(opts.json) }, defaultRuntime);
+    });
+    program
+        .command("update")
+        .description("Update nexus CLI")
+        .action(async () => {
+        await updateCommand();
+    });
+    program
+        .command("suggestions")
+        .description("Suggest next actions from local usage history")
+        .option("--json", "Output as JSON")
+        .option("--limit <n>", "Max suggestions to show", (v) => Number.parseInt(v, 10))
+        .option("--history <n>", "Number of prior actions to use", (v) => Number.parseInt(v, 10))
+        .option("--session <id>", "Session ID to analyze (defaults to latest)")
+        .option("--source <source>", "Filter by event source (e.g., nexus_cli)")
+        .option("--kind <kinds>", "Filter by kinds (cli,tool)", "cli,tool")
+        .option("--scope <scope>", "Scope for suggestions (global, session)", "global")
+        .action(async (opts) => {
+        await suggestionsCommand({
+            json: Boolean(opts.json),
+            limit: Number.isFinite(opts.limit) ? opts.limit : undefined,
+            history: Number.isFinite(opts.history) ? opts.history : undefined,
+            session: typeof opts.session === "string" ? opts.session : undefined,
+            source: typeof opts.source === "string" ? opts.source : undefined,
+            kind: typeof opts.kind === "string" ? opts.kind : undefined,
+            scope: typeof opts.scope === "string" ? opts.scope : undefined,
+        }, defaultRuntime);
+    });
+    registerSkillsCommand(program);
+    registerSkillsHubCommand(program);
+    registerCloudCommand(program);
+    registerCredentialCli(program);
+    registerDnsCli(program);
+    registerGatewayCli(program);
+    registerToolConnectorCli(program);
+    registerUsageCli(program);
+    return program;
+}

package/dist/cli/prompt.js

@@ -0,0 +1,19 @@
+import { stdin as input, stdout as output } from "node:process";
+import readline from "node:readline/promises";
+import { isVerbose, isYes } from "../globals.js";
+export async function promptYesNo(question, defaultYes = false) {
+    // Simple Y/N prompt honoring global --yes and verbosity flags.
+    if (isVerbose() && isYes())
+        return true; // redundant guard when both flags set
+    if (isYes())
+        return true;
+    const rl = readline.createInterface({ input, output });
+    const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
+    const answer = (await rl.question(`${question}${suffix}`))
+        .trim()
+        .toLowerCase();
+    rl.close();
+    if (!answer)
+        return defaultYes;
+    return answer.startsWith("y");
+}