@intent-systems/nexus 2026.1.5-11

package/dist/cli/program.js

@@ -0,0 +1,236 @@
+import { Command } from "commander";
+import { capabilitiesCommand } from "../commands/capabilities.js";
+import { configGetCommand, configListCommand, configSetCommand, } from "../commands/config.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 { statusCommand } from "../commands/status.js";
+import { suggestionsCommand } from "../commands/suggestions.js";
+import { updateCommand } from "../commands/update.js";
+import { isNixMode, migrateLegacyConfig, readConfigFileSnapshot, writeConfigFile, } from "../config/config.js";
+import { danger } from "../globals.js";
+import { recordCliCommandFinish, recordCliCommandStart, } from "../infra/event-log.js";
+import { defaultRuntime } from "../runtime.js";
+import { VERSION } from "../version.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 { registerLogCli } from "./log-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";
+import { resolveIdentitySnapshot } from "../agents/identity-state.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 skipIdentityCheck = process.env.NODE_ENV === "test" || Boolean(process.env.VITEST);
+        if (!skipIdentityCheck && actionCommand.name() !== "status") {
+            const identity = resolveIdentitySnapshot();
+            if (!identity.ok) {
+                defaultRuntime.error("Multiple agents detected in state/agents.");
+                defaultRuntime.error(`Set NEXUS_AGENT_ID to one of: ${identity.agentOptions.join(", ")}`);
+                process.exit(2);
+            }
+            if (!identity.snapshot.hasIdentity) {
+                await statusCommand({ brief: true }, defaultRuntime);
+                process.exit(2);
+            }
+        }
+        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")
+        .option("--usage", "Focus on usage statistics")
+        .option("--quiet", "Minimal output, exit codes only")
+        .action(async (opts) => {
+        await statusCommand({
+            json: Boolean(opts.json),
+            brief: Boolean(opts.brief),
+            capabilities: Boolean(opts.capabilities),
+            credentials: Boolean(opts.credentials),
+            usage: Boolean(opts.usage),
+            quiet: Boolean(opts.quiet),
+        }, defaultRuntime);
+    });
+    program
+        .command("capabilities")
+        .description("Show full capabilities map")
+        .option("--json", "Output as JSON")
+        .option("--category <name>", "Filter to a category")
+        .option("--status <status>", "Filter by status")
+        .option("--compact", "Compact output")
+        .action(async (opts) => {
+        await capabilitiesCommand({
+            json: Boolean(opts.json),
+            category: opts.category ? String(opts.category) : undefined,
+            status: opts.status ? String(opts.status) : undefined,
+            compact: Boolean(opts.compact),
+        }, defaultRuntime);
+    });
+    program
+        .command("map")
+        .description("Alias for capabilities")
+        .option("--json", "Output as JSON")
+        .option("--category <name>", "Filter to a category")
+        .option("--status <status>", "Filter by status")
+        .option("--compact", "Compact output")
+        .action(async (opts) => {
+        await capabilitiesCommand({
+            json: Boolean(opts.json),
+            category: opts.category ? String(opts.category) : undefined,
+            status: opts.status ? String(opts.status) : undefined,
+            compact: Boolean(opts.compact),
+        }, defaultRuntime);
+    });
+    program
+        .command("quest")
+        .description("Show onboarding quests")
+        .option("--json", "Output as JSON")
+        .option("--list", "List all quests")
+        .option("--progress", "Show quest progress summary")
+        .option("--start <quest>", "Mark a quest as started")
+        .option("--secrets", "Include secret quests")
+        .option("--power-path", "Only show power-path quests")
+        .option("--quick-wins", "Only show quick wins")
+        .action(async (opts) => {
+        await questCommand({
+            json: Boolean(opts.json),
+            list: Boolean(opts.list),
+            progress: Boolean(opts.progress),
+            start: opts.start ? String(opts.start) : undefined,
+            secrets: Boolean(opts.secrets),
+            powerPath: Boolean(opts.powerPath),
+            quickWins: Boolean(opts.quickWins),
+        }, 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);
+    });
+    const config = program.command("config").description("Manage config");
+    config
+        .description("Show config path and status")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await configViewCommand({ json: Boolean(opts.json) }, defaultRuntime);
+    });
+    config
+        .command("list")
+        .description("List config values")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        await configListCommand({ json: Boolean(opts.json) }, defaultRuntime);
+    });
+    config
+        .command("get <key>")
+        .description("Get a config value")
+        .option("--json", "Output as JSON")
+        .action(async (key, opts) => {
+        await configGetCommand({ key, json: Boolean(opts.json) }, defaultRuntime);
+    });
+    config
+        .command("set <key> <value>")
+        .description("Set a config value")
+        .option("--json", "Output as JSON")
+        .action(async (key, value, opts) => {
+        await configSetCommand({ key, value, 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);
+    registerLogCli(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");
+}

package/dist/cli/run-main.js

@@ -0,0 +1,48 @@
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { loadDotEnv } from "../infra/dotenv.js";
+import { normalizeEnv } from "../infra/env.js";
+import { initCliEventLogSession, recordCliCommandFailure, recordCliSessionEnd, registerAgentEventLogListener, } from "../infra/event-log.js";
+import { isMainModule } from "../infra/is-main.js";
+import { ensureNexusCliOnPath } from "../infra/path-env.js";
+import { assertSupportedRuntime } from "../infra/runtime-guard.js";
+import { enableConsoleCapture } from "../logging.js";
+export async function runCli(argv = process.argv) {
+    loadDotEnv({ quiet: true });
+    normalizeEnv();
+    ensureNexusCliOnPath();
+    // Capture all console output into structured logs while keeping stdout/stderr behavior.
+    enableConsoleCapture();
+    // Enforce the minimum supported runtime before doing any work.
+    assertSupportedRuntime();
+    initCliEventLogSession({ argv, cwd: process.cwd() });
+    registerAgentEventLogListener();
+    const { buildProgram } = await import("./program.js");
+    const program = buildProgram();
+    // Global error handlers to prevent silent crashes from unhandled rejections/exceptions.
+    // These log the error and exit gracefully instead of crashing without trace.
+    process.on("unhandledRejection", (reason, _promise) => {
+        console.error("[nexus] Unhandled promise rejection:", reason instanceof Error ? (reason.stack ?? reason.message) : reason);
+        process.exit(1);
+    });
+    process.on("uncaughtException", (error) => {
+        console.error("[nexus] Uncaught exception:", error.stack ?? error.message);
+        process.exit(1);
+    });
+    try {
+        await program.parseAsync(argv);
+        recordCliSessionEnd({ status: "ok", exitCode: 0 });
+    }
+    catch (err) {
+        recordCliCommandFailure(err);
+        recordCliSessionEnd({
+            status: "error",
+            exitCode: 1,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+export function isCliMainModule() {
+    return isMainModule({ currentFile: fileURLToPath(import.meta.url) });
+}

package/dist/cli/skills-cli.js

@@ -0,0 +1,290 @@
+import path from "node:path";
+import chalk from "chalk";
+import { getSkillInfo, verifySkill } from "../agents/skill-runner.js";
+import { getAggregateStats, getSkillStats, hasSkillUsage, recordSkillUsage, } from "../agents/skill-usage.js";
+import { getSkillMetadata, loadWorkspaceSkillEntries } from "../agents/skills.js";
+import { buildWorkspaceSkillStatus } from "../agents/skills-status.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "../agents/workspace.js";
+import { generateSkillManifest, getSkillManifestPath, readSkillManifest, writeSkillManifest, } from "../commands/skills-manifest.js";
+import { loadConfig } from "../config/config.js";
+import { NEXUS_ROOT, SKILLS_STATE_DIR, resolveUserPath } from "../utils.js";
+const STATUS_ICON = {
+    active: "✅",
+    ready: "⭐",
+    needs_setup: "🔧",
+    needs_install: "📥",
+    unavailable: "⛔",
+};
+function resolveSkillType(entry) {
+    const metadata = getSkillMetadata(entry);
+    if (metadata?.type)
+        return metadata.type;
+    const requires = metadata?.requires;
+    if (requires?.env?.length || requires?.config?.length)
+        return "connector";
+    if (requires?.bins?.length || requires?.anyBins?.length)
+        return "tool";
+    return "guide";
+}
+function resolveSkillStatus(statusEntry) {
+    if (statusEntry.disabled || statusEntry.blockedByAllowlist) {
+        return "unavailable";
+    }
+    if (statusEntry.missing.os.length > 0)
+        return "unavailable";
+    if (statusEntry.missing.bins.length > 0)
+        return "needs_install";
+    if (statusEntry.missing.env.length > 0 || statusEntry.missing.config.length > 0) {
+        return "needs_setup";
+    }
+    if (hasSkillUsage(statusEntry.name))
+        return "active";
+    return "ready";
+}
+export function registerSkillsCommand(program) {
+    const skill = program.command("skill").description("Use and inspect skills");
+    skill
+        .command("scan")
+        .description("Scan local skills and write the skill index")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const config = loadConfig();
+        const workspaceDir = resolveUserPath(config.agent?.workspace ?? DEFAULT_AGENT_WORKSPACE_DIR);
+        const skillsRoot = path.join(NEXUS_ROOT, "skills");
+        const userSkillsDir = path.join(workspaceDir, "skills");
+        const previous = await readSkillManifest();
+        const manifest = await generateSkillManifest(skillsRoot, userSkillsDir, previous);
+        await writeSkillManifest(manifest);
+        const manifestPath = getSkillManifestPath();
+        if (opts.json) {
+            console.log(JSON.stringify({
+                manifestPath,
+                manifest,
+            }, null, 2));
+            return;
+        }
+        console.log("\n✅ Skill index updated");
+        console.log(`Managed: ${manifest.managed.count}`);
+        console.log(`Local: ${manifest.local.count}`);
+        console.log(`Manifest: ${manifestPath}\n`);
+    });
+    skill
+        .command("list")
+        .description("List all available skills")
+        .option("--json", "Output as JSON")
+        .option("--type <type>", "Filter by type (guide|tool|connector)")
+        .option("--status <status>", "Filter by status (active|ready|needs-setup|needs-install|unavailable)")
+        .option("--active", "Only show active skills")
+        .option("--ready", "Only show ready skills")
+        .option("--needs-setup", "Only show skills needing setup")
+        .option("--needs-install", "Only show skills needing install")
+        .option("--unavailable", "Only show unavailable skills")
+        .option("--all", "Include unavailable skills")
+        .action(async (opts) => {
+        const config = loadConfig();
+        const workspaceDir = resolveUserPath(config.agent?.workspace ?? DEFAULT_AGENT_WORKSPACE_DIR);
+        const entries = loadWorkspaceSkillEntries(workspaceDir, {
+            config,
+        });
+        const status = buildWorkspaceSkillStatus(workspaceDir, {
+            config,
+            entries,
+        });
+        const statusMap = new Map(status.skills.map((item) => [item.name.toLowerCase(), item]));
+        const items = entries.map((entry) => {
+            const statusEntry = statusMap.get(entry.skill.name.toLowerCase());
+            const statusValue = statusEntry
+                ? resolveSkillStatus(statusEntry)
+                : "unavailable";
+            return {
+                name: entry.skill.name,
+                description: entry.skill.description,
+                type: resolveSkillType(entry),
+                status: statusValue,
+                source: entry.skill.source,
+                filePath: entry.skill.filePath,
+            };
+        });
+        const typeFilter = opts.type
+            ? String(opts.type).toLowerCase()
+            : undefined;
+        const statusFilters = new Set();
+        if (opts.status) {
+            const raw = String(opts.status)
+                .split(",")
+                .map((entry) => entry.trim().toLowerCase())
+                .filter(Boolean);
+            for (const entry of raw) {
+                const normalized = entry.replace(/_/g, "-");
+                if (normalized === "needs-setup")
+                    statusFilters.add("needs_setup");
+                else if (normalized === "needs-install")
+                    statusFilters.add("needs_install");
+                else if (normalized === "active")
+                    statusFilters.add("active");
+                else if (normalized === "ready")
+                    statusFilters.add("ready");
+                else if (normalized === "unavailable")
+                    statusFilters.add("unavailable");
+            }
+        }
+        if (opts.active)
+            statusFilters.add("active");
+        if (opts.ready)
+            statusFilters.add("ready");
+        if (opts.needsSetup)
+            statusFilters.add("needs_setup");
+        if (opts.needsInstall)
+            statusFilters.add("needs_install");
+        if (opts.unavailable)
+            statusFilters.add("unavailable");
+        const hasStatusFilter = statusFilters.size > 0;
+        const filtered = items.filter((item) => {
+            if (typeFilter && item.type !== typeFilter)
+                return false;
+            if (hasStatusFilter && !statusFilters.has(item.status))
+                return false;
+            if (!hasStatusFilter && !opts.all && item.status === "unavailable")
+                return false;
+            return true;
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({
+                workspace: workspaceDir,
+                total: items.length,
+                filtered: filtered.length,
+                skills: filtered,
+            }, null, 2));
+            return;
+        }
+        if (filtered.length === 0) {
+            console.log("No skills matched.");
+            return;
+        }
+        console.log(`\n📚 Nexus Skills (${filtered.length} shown)\n`);
+        for (const item of filtered) {
+            const desc = item.description
+                ? ` - ${item.description.slice(0, 60)}${item.description.length > 60 ? "..." : ""}`
+                : "";
+            const icon = STATUS_ICON[item.status] ?? "•";
+            console.log(`  ${icon} ${item.name}${desc}`);
+        }
+        const skillsRoot = path.join(NEXUS_ROOT, "skills");
+        console.log(`\nSkills directory: ${skillsRoot}`);
+        console.log(`Skill types: ${path.join(skillsRoot, "tools")}, ${path.join(skillsRoot, "connectors")}, ${path.join(skillsRoot, "guides")}`);
+        console.log(`Skill state: ${SKILLS_STATE_DIR}`);
+        console.log(`User skills: ${path.join(workspaceDir, "skills")}\n`);
+    });
+    skill
+        .command("info <name>")
+        .description("Show detailed information about a skill")
+        .option("--json", "Output as JSON")
+        .option("--prompt", "Include the full SKILL.md prompt")
+        .action(async (name, opts) => {
+        const info = getSkillInfo(name);
+        const stats = await getSkillStats(name);
+        if (!info.exists) {
+            console.error(`Skill not found: ${name}`);
+            console.error(`\nRun 'nexus skill list' to see available skills.`);
+            process.exit(1);
+        }
+        if (opts.json) {
+            const output = opts.prompt ? info : { ...info, prompt: undefined };
+            const payload = stats ? { ...output, usage: stats } : output;
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        console.log(`\n${chalk.bold.cyan("Skill:")} ${info.name}`);
+        console.log(`${chalk.bold("Type:")} ${info.type}`);
+        if (info.tool) {
+            console.log(`${chalk.bold("Tool:")} ${info.tool}`);
+        }
+        if (info.verify) {
+            console.log(`${chalk.bold("Verify:")} ${info.verify}`);
+        }
+        const statusColor = info.configured ? chalk.green : chalk.yellow;
+        const statusIcon = info.configured ? "✓" : "○";
+        console.log(`${chalk.bold("Status:")} ${statusColor(`${statusIcon} ${info.configured ? "Configured" : "Not configured"}`)}`);
+        if (stats?.lastUsed ?? info.lastUsed) {
+            console.log(`${chalk.bold("Last used:")} ${stats?.lastUsed ?? info.lastUsed}`);
+        }
+        if (info.lastError) {
+            console.log(`${chalk.bold("Last error:")} ${chalk.red(info.lastError)}`);
+        }
+        if (stats) {
+            console.log(`${chalk.bold("Runs:")} ${stats.runs}`);
+            console.log(`${chalk.bold("Errors:")} ${stats.errors}`);
+        }
+        if (opts.prompt && info.prompt) {
+            console.log(`\n${chalk.bold.cyan("--- SKILL.md ---")}\n`);
+            console.log(info.prompt);
+        }
+    });
+    skill
+        .command("use <name>")
+        .description("Show the SKILL.md guide for a skill")
+        .action(async (name) => {
+        const info = getSkillInfo(name);
+        if (!info.exists) {
+            console.error(`Skill not found: ${name}`);
+            console.error(`\nRun 'nexus skill list' to see available skills.`);
+            process.exit(1);
+        }
+        if (!info.prompt) {
+            console.error(`No SKILL.md found for ${name}.`);
+            process.exit(1);
+        }
+        console.log(info.prompt.trimEnd());
+        recordSkillUsage(name, { ts: Date.now(), event: "use", ok: true });
+    });
+    skill
+        .command("verify <name>")
+        .description("Verify skill setup and dependencies")
+        .action(async (name) => {
+        const result = await verifySkill(name);
+        if (!result.ok) {
+            console.error(result.error);
+            process.exit(1);
+        }
+        console.log(result.message);
+    });
+    skill
+        .command("stats [name]")
+        .description("Show skill usage statistics")
+        .option("--json", "Output as JSON")
+        .action(async (name, opts) => {
+        if (name) {
+            const stats = await getSkillStats(name);
+            if (!stats) {
+                console.error(`Skill not found: ${name}`);
+                process.exit(1);
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(stats, null, 2));
+                return;
+            }
+            console.log(`Skill: ${name}`);
+            console.log(`  Runs: ${stats.runs}`);
+            console.log(`  Last used: ${stats.lastUsed ?? "never"}`);
+            console.log(`  Avg duration: ${stats.avgDurationMs ?? "-"} ms`);
+            console.log(`  Errors: ${stats.errors}`);
+            return;
+        }
+        const stats = await getAggregateStats();
+        if (opts.json) {
+            console.log(JSON.stringify(stats, null, 2));
+            return;
+        }
+        console.log(`Total skill runs: ${stats.totalRuns}`);
+        console.log(`Active skills: ${stats.activeSkills}`);
+        if (stats.topUsed && stats.topUsed.length > 0) {
+            console.log(`Most used: ${stats.topUsed
+                .map((item) => `${item.name} (${item.runs})`)
+                .join(", ")}`);
+        }
+        else {
+            console.log("Most used: none");
+        }
+        console.log(`Ready but unused: ${stats.readyButUnused?.join(", ") || "none"}`);
+    });
+}