@nexusbloom/cli 0.3.4 → 0.9.0

package/src/index.js

@@ -12,14 +12,15 @@
  *   nxb run <slug> --file input.json   — Execute with file input
  *   nxb run <slug> --local             — Execute coreLogic locally (cached)
  *   nxb run                            — Interactive: select tool → pick inputs → auto-build command
+ *   nxb run -s <query>                 — Filter the tool picker (non-TTY: print the list)
  *   nxb info <slug>                    — Show tool schema
- *   nxb abbr                           — Show tool abbreviations (paginated)
+ *   nxb abbr [-s <query>]              — Show tool abbreviations (paginated)
  *   nxb transform <slug>               — Pipe stdin through a tool
  *   nxb config set <key> [value]       — Set config (interactive if value omitted)
- *   nxb config get [key]               — Get config
+ *   nxb config get [key]               — Get config (secrets redacted)
  *   nxb cache clear                    — Clear local tool cache
  *   nxb cache list                     — List cached tools
- *   nxb create                         — Scaffold a new tool locally
+ *   nxb cache path                     — Print where config/cache live
  *   nxb json --template <slug>         — Create JSON input for tools
  */
 
@@ -34,16 +35,58 @@ const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 
 // ─── Local modules ──────────────────────────────────────────────────────────
-import { API_BASE } from "./tools.js";
 import {
-  loadConfig, saveConfig, configGet, configSet,
+  loadConfig, configGet, configSet, configUnset, redactedConfig, isSecretKey,
   fetchTools, fetchToolSource, resolveToolSlug,
-  generateAbbreviations, readStdin,
+  generateAbbreviations, normalizeSlug, readStdin,
 } from "./tools.js";
-import { runLocal, runRemote, buildInputBody, runInteractive } from "./run.js";
+import { runLocal, runRemote, buildInputBody, runInteractive, runInteractiveFor, isExitPromptError, reportError } from "./run.js";
 import listAction from "./list.js";
+import { pipeAction, listTransforms, doctorAction } from "./commands.js";
+import { buildWizard } from "./wizard.js";
+import { listPipelines, loadPipeline, deletePipeline } from "./pipelines.js";
 import abbrAction from "./abbr.js";
-import { TOOLS_CACHE_DIR, TOOLS_LIST_CACHE_PATH } from "./paths.js";
+import { isInteractive } from "./ui.js";
+import {
+  CACHE_DIR,
+  CONFIG_PATH,
+  LEGACY_CACHE_DIR,
+  TOOLS_CACHE_DIR,
+  TOOLS_LIST_CACHE_PATH,
+} from "./paths.js";
+
+/**
+ * Was `--json` requested?
+ *
+ * A subcommand's immediate parent is not always the program: for
+ * `nxb pipeline list` it is the `pipeline` command, which has no `json` option
+ * of its own. Walking to the root is what makes the global flag mean the same
+ * thing at every depth.
+ */
+function jsonFlag(cmd) {
+  let c = cmd;
+  while (c) {
+    if (typeof c.opts === "function") {
+      const v = c.opts().json;
+      if (v !== undefined) return v;
+    }
+    c = c.parent;
+  }
+  return false;
+}
+
+/** Guard: slugs become cache filenames and query strings, so reject oddities. */
+function requireSlug(slug, jsonMode) {
+  const safe = normalizeSlug(slug);
+  if (safe) return safe;
+  const msg = `Invalid tool slug: "${slug}". Use letters, digits, dots, dashes and underscores.`;
+  // Same envelope as every other failure, so a script keying off `success`
+  // does not see `undefined` here and nowhere else.
+  if (jsonMode) console.log(JSON.stringify({ success: false, error: msg }));
+  else console.error(chalk.red(msg));
+  process.exitCode = 1;
+  return null;
+}
 
 // ─── Program ─────────────────────────────────────────────────────────────────
 program
@@ -58,12 +101,16 @@ program
   .description("List available tools (interactive pagination)")
   .option("-s, --search <query>", "Search tools by name, slug, category, or tags")
   .option("--no-interactive", "Disable interactive navigation")
+  .option("-r, --refresh", "Bypass the local cache and re-fetch the catalogue")
+  .option("--offline", "Use only the local cache (no network)")
   .action(async (opts, cmd) => {
-    const jsonMode = cmd.parent.opts().json;
+    const jsonMode = jsonFlag(cmd);
     await listAction({
       search: opts.search,
       json: jsonMode,
       interactive: opts.interactive !== false,
+      force: Boolean(opts.refresh),
+      offline: Boolean(opts.offline),
     });
   });
 
@@ -72,35 +119,14 @@ program
   .command("search")
   .description("Search for tools")
   .argument("<query>", "Search query")
+  .option("--no-interactive", "Disable interactive navigation")
   .action(async (query, opts, cmd) => {
     const jsonMode = cmd?.parent?.opts().json || false;
-    const tools = await fetchTools();
-    if (!tools || tools.length === 0) {
-      if (jsonMode) return console.log(JSON.stringify({ tools: [], query }));
-      console.log(chalk.yellow(`No tools found matching "${query}".`));
-      return;
-    }
-    const q = query.toLowerCase();
-    const filtered = tools.filter(
-      (t) =>
-        (t.slug || "").includes(q) ||
-        (t.name || "").toLowerCase().includes(q) ||
-        (t.short_description || t.description || "").toLowerCase().includes(q) ||
-        (t.category || "").includes(q) ||
-        (t.tags || []).some((tg) => tg.toLowerCase().includes(q))
-    );
-    if (filtered.length === 0) {
-      if (jsonMode) return console.log(JSON.stringify({ tools: [], query }));
-      console.log(chalk.yellow(`No tools matching "${query}".`));
-      return;
-    }
-    if (jsonMode) return console.log(JSON.stringify({ tools: filtered, query }, null, 2));
-
-    console.log(chalk.bold(`\n  ${filtered.length} result${filtered.length > 1 ? "s" : ""} for "${query}"\n`));
-    filtered.forEach((t) => {
-      console.log(`  ${chalk.cyan((t.slug || "").padEnd(30))} ${chalk.dim((t.short_description || t.description || "").slice(0, 60))}`);
+    await listAction({
+      search: query,
+      json: jsonMode,
+      interactive: opts.interactive !== false,
     });
-    console.log();
   });
 
 // ─── `nxb run [slug] [args...]` ──────────────────────────────────────────────
@@ -109,32 +135,53 @@ program
   .description("Execute a tool (interactive if no slug is given)")
   .argument("[slug]", "Tool slug or abbreviation")
   .argument("[args...]", "Key=value arguments (e.g. domain=example.com)")
+  .option("-s, --search <query>", "Filter tools by name, slug, category, or tags")
   .option("-k, --key <key>", "API key (or set NEXUSBLOOM_API_KEY env var)")
   .option("-i, --input <json>", "Inline JSON input or @- for stdin (e.g. '{\"domain\":\"example.com\"}' or @-)")
   .option("-f, --file <path>", "Read input from a JSON file")
   .option("--local", "Execute coreLogic locally (fetches tool source, caches it)")
   .action(async (slug, args, opts, cmd) => {
-    const jsonMode = cmd.parent.opts().json;
+    const jsonMode = jsonFlag(cmd);
 
-    // ── Interactive mode: no slug provided ──
+    // ── Interactive / list mode: no slug provided ──
     if (!slug) {
-      return await runInteractive({ json: jsonMode });
+      return await runInteractive({ json: jsonMode, search: opts.search });
     }
 
+    const safeSlug = requireSlug(slug, jsonMode);
+    if (!safeSlug) return;
+
     // ── Resolve abbreviation ──
     const allTools = await fetchTools();
     const slugs = (allTools || []).map((t) => t.slug);
     const abbrMap = generateAbbreviations(slugs);
-    let resolved = slug;
-    if (abbrMap[slug] && slugs.includes(abbrMap[slug])) {
-      resolved = abbrMap[slug];
-      if (!jsonMode) console.log(chalk.dim(`  Resolved: ${slug} → ${resolved}`));
+    let resolved = safeSlug;
+    if (abbrMap[safeSlug] && slugs.includes(abbrMap[safeSlug])) {
+      resolved = abbrMap[safeSlug];
+      // The result itself goes to stderr, so the notice does too — otherwise
+      // `nxb run <abbr> ... > out.json` writes prose into the JSON.
+      if (!jsonMode) console.error(chalk.dim(`  Resolved: ${safeSlug} → ${resolved}`));
     }
 
     // ── Build input body ──
     const body = await buildInputBody(opts, args);
     if (body === null) return;
 
+    // ── No input at all: configure the tool interactively ──
+    // `nxb run text-statistics` with nothing to send used to fail schema
+    // validation ("Missing required fields: text"), which is a dead end for a
+    // human at a terminal. Ask for the fields instead. Only when the body is
+    // genuinely empty: any explicit input (--input/--file, key=value, piped
+    // stdin) means the caller is scripting, and a prompt there would hang CI.
+    if (Object.keys(body).length === 0 && isInteractive()) {
+      return await runInteractiveFor(resolved, {
+        json: jsonMode,
+        tools: allTools,
+        local: Boolean(opts.local),
+        key: opts.key,
+      });
+    }
+
     // ── Local vs remote ──
     if (opts.local || (!opts.key && !process.env.NEXUSBLOOM_API_KEY && !configGet("apiKey") && !configGet("key"))) {
       return await runLocal(resolved, body, { jsonMode, slugResolved: true });
@@ -154,15 +201,15 @@ program
   .argument("<slug>", "Tool slug or abbreviation")
   .action(async (slug, opts, cmd) => {
     const jsonMode = cmd?.parent?.opts().json || false;
-    const resolved = await resolveToolSlug(slug);
+    const safe = requireSlug(slug, jsonMode);
+    if (!safe) return;
 
+    const resolved = await resolveToolSlug(safe);
     const toolInfo = await fetchToolSource(resolved);
     const manifest = toolInfo?.manifest;
 
     if (!manifest) {
-      if (jsonMode) return console.log(JSON.stringify({ error: `Tool "${resolved}" not found.` }));
-      console.error(chalk.red(`Tool "${resolved}" not found.`));
-      return;
+      return reportError(jsonMode, `Tool "${resolved}" not found. Try \`nxb search ${safe}\`.`);
     }
 
     if (jsonMode) return console.log(JSON.stringify(manifest, null, 2));
@@ -173,20 +220,20 @@ program
 // ─── `nxb transform <slug>` ──────────────────────────────────────────────────
 program
   .command("transform")
-  .description("Pipe stdin through a tool and write result to stdout")
+  .description("Pipe stdin through a tool and write the result to stdout")
   .argument("<slug>", "Tool slug or abbreviation")
   .option("-k, --key <key>", "API key (or set NEXUSBLOOM_API_KEY env var)")
   .option("--local", "Execute locally (faster for repeated use)")
   .action(async (slug, opts, cmd) => {
-    const resolved = await resolveToolSlug(slug);
-    const jsonMode = cmd.parent.opts().json;
+    const jsonMode = jsonFlag(cmd);
+    const safe = requireSlug(slug, jsonMode);
+    if (!safe) return;
+
+    const resolved = await resolveToolSlug(safe);
 
     const input = await readStdin();
-    if (!input) {
-      if (jsonMode) return console.log(JSON.stringify({ error: "No input received from stdin" }));
-      console.error(chalk.red("No input received from stdin. Pipe data into this command."));
-      process.exitCode = 1;
-      return;
+    if (!input || !input.trim()) {
+      return reportError(jsonMode, "No input received from stdin. Pipe data into this command.");
     }
 
     let body;
@@ -196,19 +243,123 @@ program
       body = { input };
     }
 
-    if (opts.local || (!opts.key && !process.env.NEXUSBLOOM_API_KEY && !configGet("apiKey") && !configGet("key"))) {
-      return await runLocal(resolved, body, { jsonMode, slugResolved: true });
+    // `transform` exists to be piped, so stdout carries the payload and every
+    // decoration goes to stderr.
+    const useLocal =
+      opts.local || (!opts.key && !process.env.NEXUSBLOOM_API_KEY && !configGet("apiKey") && !configGet("key"));
+
+    const res = useLocal
+      ? await runLocal(resolved, body, { jsonMode: false, slugResolved: true, quiet: true })
+      : await runRemote(resolved, body, {
+          apiKey: opts.key || process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key"),
+          jsonMode: false,
+          slugResolved: true,
+          quiet: true,
+        });
+
+    if (!res?.ok) {
+      return reportError(jsonMode, res?.error || "Transform failed.");
     }
 
-    const apiKey = opts.key || process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
-    if (!apiKey) {
-      if (jsonMode) return console.log(JSON.stringify({ error: "API key required" }));
-      console.error(chalk.red("API key required. Set NEXUSBLOOM_API_KEY, pass --key, or use --local mode."));
+    // A string result is emitted verbatim so it can feed another process;
+    // anything else is JSON so it can feed another `nxb transform`.
+    console.log(typeof res.result === "string" ? res.result : JSON.stringify(res.result, null, 2));
+  });
+
+// ─── `nxb pipe` ──────────────────────────────────────────────────────────────
+program
+  .command("pipe")
+  .description("Run a pipeline: connect one tool's output into another's input")
+  .argument("[spec]", 'Pipeline string, e.g. "tool-a x=@in | tool-b count=$n|len"')
+  .option("--dry-run", "Check the wiring and type compatibility without running")
+  .option("--remote", "Run every step against the API instead of locally")
+  .option("--transforms", "List the available connection transforms")
+  .option("--build", "Build a pipeline interactively")
+  .action(async (spec, opts, cmd) => {
+    const jsonMode = jsonFlag(cmd);
+    if (opts.transforms) return listTransforms(jsonMode);
+    if (opts.build || (!spec && isInteractive())) {
+      // Building nothing is a failure, not a quiet success — scripts need to
+      // be able to detect that no pipeline came out.
+      const built = await buildWizard();
+      if (!built?.ok) process.exitCode = 1;
+      return;
+    }
+    if (!spec) {
+      console.error(chalk.red("  Give a pipeline, or run `nxb pipe --build`."));
       process.exitCode = 1;
       return;
     }
+    await pipeAction(spec, { json: jsonMode, dryRun: opts.dryRun, remote: opts.remote });
+  });
+
+// ─── `nxb pipeline <list|run|delete>` ────────────────────────────────────────
+const savedCmd = program
+  .command("pipeline")
+  .description("Manage saved pipelines");
+
+savedCmd
+  .command("list")
+  .description("List saved pipelines")
+  .action((opts, cmd) => {
+    const jsonMode = jsonFlag(cmd);
+    const items = listPipelines();
+    if (jsonMode) return console.log(JSON.stringify({ pipelines: items }, null, 2));
+    if (!items.length) {
+      console.log(chalk.yellow("  No saved pipelines. Create one with `nxb pipe --build`."));
+      return;
+    }
+    console.log(chalk.bold(`\n  ${items.length} saved pipeline${items.length === 1 ? "" : "s"}\n`));
+    for (const it of items) {
+      console.log(`  ${chalk.cyan(it.name.padEnd(20))} ${chalk.dim(`${it.steps} step${it.steps === 1 ? "" : "s"}`)}`);
+      if (it.pipeline) console.log(`      ${chalk.gray(it.pipeline.slice(0, 92))}`);
+    }
+    console.log();
+  });
+
+savedCmd
+  .command("run")
+  .description("Run a saved pipeline")
+  .argument("<name>", "Pipeline name")
+  .option("--dry-run", "Check the wiring without running")
+  .option("--remote", "Run every step against the API")
+  .action(async (name, opts, cmd) => {
+    const jsonMode = jsonFlag(cmd);
+    const def = loadPipeline(name);
+    if (!def?.pipeline) {
+      return reportError(jsonMode, `No saved pipeline named "${name}". Try \`nxb pipeline list\`.`);
+    }
+    await pipeAction(def.pipeline, { json: jsonMode, dryRun: opts.dryRun, remote: opts.remote });
+  });
+
+savedCmd
+  .command("delete")
+  .description("Delete a saved pipeline")
+  .argument("<name>", "Pipeline name")
+  .action((name, _opts, cmd) => {
+    const jsonMode = jsonFlag(cmd);
+    try {
+      if (!deletePipeline(name)) return reportError(jsonMode, `No saved pipeline named "${name}".`);
+      console.log(chalk.green(`  Deleted "${name}".`));
+    } catch (err) {
+      return reportError(jsonMode, err.message);
+    }
+  });
 
-    await runRemote(resolved, body, { apiKey, jsonMode, slugResolved: true });
+// ─── `nxb doctor <slug>` ─────────────────────────────────────────────────────
+program
+  .command("doctor")
+  .description("Compare a tool's real output against its declared output_schema")
+  .argument("<slug>", "Tool slug or abbreviation")
+  .action(async (slug, opts, cmd) => {
+    const jsonMode = jsonFlag(cmd);
+    const safe = requireSlug(slug, jsonMode);
+    if (!safe) return;
+    const resolved = await resolveToolSlug(safe);
+    // `nxb doctor x || exit 1` is the whole point of a drift detector; a
+    // finding that exits 0 makes the gate silently useless.
+    const verdict = await doctorAction(resolved, { json: jsonMode });
+    if (verdict && verdict.ok === false) process.exitCode = 1;
   });
 
 // ─── `nxb abbr [query]` ──────────────────────────────────────────────────────
@@ -216,11 +367,13 @@ program
   .command("abbr")
   .description("Show tool abbreviations (paginated)")
   .argument("[query]", "Search/filter abbreviations")
+  .option("-s, --search <query>", "Search/filter abbreviations")
   .option("--no-interactive", "Disable interactive navigation")
   .action(async (query, opts, cmd) => {
-    const jsonMode = cmd.parent.opts().json;
+    const jsonMode = jsonFlag(cmd);
     await abbrAction({
       query,
+      search: opts.search,
       json: jsonMode,
       interactive: opts.interactive !== false,
     });
@@ -234,7 +387,7 @@ const configCmd = program
 configCmd
   .command("set")
   .description("Set a config value (prompts for value if omitted)")
-  .argument("<key>", "Config key (key, default-tool)")
+  .argument("<key>", "Config key (key, supabaseKey, telemetry, toolsDir)")
   .argument("[value]", "Config value (prompted if not provided)")
   .action(async (key, value) => {
     if (!value) {
@@ -245,12 +398,18 @@ configCmd
       return;
     }
     configSet(key, value);
-    console.log(chalk.green(`  Set ${key} to "${value}"`));
+    // Never echo a secret back to the terminal / shell history.
+    if (isSecretKey(key)) {
+      console.log(chalk.green(`  Set ${key} (stored, value hidden)`));
+      console.log(chalk.dim(`  ${CONFIG_PATH}`));
+    } else {
+      console.log(chalk.green(`  Set ${key} to "${value}"`));
+    }
   });
 
 configCmd
   .command("get")
-  .description("Get a config value")
+  .description("Get a config value (secrets redacted)")
   .argument("[key]", "Config key (omit to show all)")
   .action((key) => {
     const store = loadConfig();
@@ -259,256 +418,147 @@ configCmd
       if (value === undefined) {
         console.log(chalk.yellow(`  ${key} is not set`));
       } else {
-        console.log(`  ${key}: ${value}`);
+        const shown = isSecretKey(key) ? maskSecret(value) : value;
+        console.log(`  ${key}: ${shown}`);
       }
     } else {
-      if (Object.keys(store).length === 0) {
-        console.log(chalk.yellow("  No config values set."));
-      } else {
-        Object.entries(store).forEach(([k, v]) => {
-          console.log(`  ${k}: ${v}`);
-        });
-      }
+      printConfig(store);
     }
   });
 
 configCmd
-  .command("list")
-  .description("List all config values (alias for config get)")
-  .action(() => {
-    const store = loadConfig();
-    if (Object.keys(store).length === 0) {
-      console.log(chalk.yellow("  No config values set."));
+  .command("unset")
+  .description("Remove a config value (e.g. a stored API key)")
+  .argument("<key>", "Config key to remove")
+  .action((key, opts, cmd) => {
+    const jsonMode = jsonFlag(cmd);
+    if (!configUnset(key)) {
+      return reportError(jsonMode, `"${key}" is not set.`);
+    }
+    if (jsonMode) {
+      console.log(JSON.stringify({ success: true, data: { unset: key } }, null, 2));
     } else {
-      Object.entries(store).forEach(([k, v]) => {
-        console.log(`  ${k}: ${v}`);
-      });
+      console.log(chalk.green(`  Removed ${key}`));
     }
   });
 
+configCmd
+  .command("list")
+  .description("List all config values (secrets redacted)")
+  .action(() => printConfig(loadConfig()));
+
+function maskSecret(value) {
+  const s = value == null ? "" : String(value);
+  return s.length <= 8 ? "********" : `${s.slice(0, 4)}…${s.slice(-4)}`;
+}
+
+function printConfig(store) {
+  if (!store || Object.keys(store).length === 0) {
+    console.log(chalk.yellow("  No config values set."));
+    return;
+  }
+  const safe = redactedConfig(store);
+  for (const [k, v] of Object.entries(safe)) {
+    console.log(`  ${k}: ${v}`);
+  }
+  console.log(chalk.dim(`\n  Stored at ${CONFIG_PATH}`));
+}
+
 // ─── `nxb cache` ─────────────────────────────────────────────────────────────
 const cacheCmd = program
   .command("cache")
   .description("Manage local tool cache");
 
+/** Delete everything inside a cache dir (recursively). Returns entries removed. */
+function clearCacheDir(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const target = path.join(dir, entry.name);
+    try {
+      if (entry.isDirectory()) fs.rmSync(target, { recursive: true, force: true });
+      else fs.unlinkSync(target);
+      count++;
+    } catch {
+      /* skip anything we cannot remove */
+    }
+  }
+  return count;
+}
+
 cacheCmd
   .command("clear")
   .description("Clear the local tool cache")
   .action(() => {
-    if (!fs.existsSync(TOOLS_CACHE_DIR)) {
-      console.log(chalk.yellow("  No cache directory found."));
-      return;
+    const count = clearCacheDir(TOOLS_CACHE_DIR);
+    let removedList = 0;
+    if (fs.existsSync(TOOLS_LIST_CACHE_PATH)) {
+      try {
+        fs.unlinkSync(TOOLS_LIST_CACHE_PATH);
+        removedList = 1;
+      } catch {
+        /* best effort */
+      }
     }
-    const files = fs.readdirSync(TOOLS_CACHE_DIR);
-    let count = 0;
-    for (const file of files) {
-      fs.unlinkSync(path.join(TOOLS_CACHE_DIR, file));
-      count++;
+    // Older versions cached inside the installed package directory.
+    const legacy = clearCacheDir(LEGACY_CACHE_DIR);
+    if (legacy) {
+      try {
+        fs.rmdirSync(LEGACY_CACHE_DIR);
+      } catch {
+        /* not empty / not ours — leave it */
+      }
     }
-    // Also remove tools-list.json
-    if (fs.existsSync(TOOLS_LIST_CACHE_PATH)) {
-      fs.unlinkSync(TOOLS_LIST_CACHE_PATH);
+    const total = count + removedList;
+    if (total === 0 && legacy === 0) {
+      console.log(chalk.yellow("  Nothing cached."));
+      return;
+    }
+    console.log(chalk.green(`  Cleared ${total} cached item${total !== 1 ? "s" : ""}.`));
+    if (legacy) {
+      console.log(chalk.dim(`  Removed ${legacy} legacy cache entr${legacy === 1 ? "y" : "ies"} from the old package directory.`));
     }
-    console.log(chalk.green(`  Cleared ${count} cached tool${count !== 1 ? "s" : ""}.`));
   });
 
 cacheCmd
   .command("list")
   .description("List cached tools")
-  .action(() => {
+  .option("-s, --search <query>", "Filter cached tools by slug")
+  .action((opts) => {
     if (!fs.existsSync(TOOLS_CACHE_DIR)) {
       console.log(chalk.yellow("  No cached tools."));
       return;
     }
-    const files = fs.readdirSync(TOOLS_CACHE_DIR);
+    const query = (opts.search || "").toLowerCase();
+    const files = fs
+      .readdirSync(TOOLS_CACHE_DIR)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => f.replace(/\.json$/, ""))
+      .filter((slug) => !query || slug.toLowerCase().includes(query));
+
     if (files.length === 0) {
-      console.log(chalk.yellow("  No cached tools."));
+      console.log(chalk.yellow(query ? `  No cached tools matching "${opts.search}".` : "  No cached tools."));
       return;
     }
-    console.log(chalk.bold(`\n  ${files.length} cached tool${files.length > 1 ? "s" : ""}:\n`));
-    files.forEach((f) => {
-      const slug = f.replace(/\.json$/, "");
-      const stats = fs.statSync(path.join(TOOLS_CACHE_DIR, f));
-      const age = Math.round((Date.now() - stats.mtimeMs) / 1000 / 60);
-      console.log(`  ${chalk.cyan(slug.padEnd(30))} ${chalk.dim(`${age}m ago`)}`);
+    console.log(chalk.bold(`\n  ${files.length} cached tool${files.length !== 1 ? "s" : ""}:\n`));
+    files.sort().forEach((slug) => {
+      const stats = fs.statSync(path.join(TOOLS_CACHE_DIR, `${slug}.json`));
+      const age = Math.round((Date.now() - stats.mtimeMs) / 60000);
+      const size = (stats.size / 1024).toFixed(1);
+      console.log(`  ${chalk.cyan(slug.padEnd(30))} ${chalk.dim(`${age}m ago · ${size}kb`)}`);
     });
     console.log();
   });
 
-// ─── `nxb create` ────────────────────────────────────────────────────────────
-const VALID_RUNTIMES = ["browser", "node", "both"];
-const VALID_CATEGORIES = [
-  "text", "image", "data", "network", "security", "development",
-  "education", "business", "utility", "math", "game", "Other",
-];
-
-program
-  .command("create")
-  .description("Scaffold a new tool locally")
-  .option("--slug <slug>", "Tool slug (lowercase, hyphenated)")
-  .option("--name <name>", "Display name")
-  .option("--desc <desc>", "Short description")
-  .option("--category <category>", `Category (${VALID_CATEGORIES.join(", ")})`)
-  .option("--runtime <runtime>", `Runtime (${VALID_RUNTIMES.join(", ")})`)
-  .option("--dir <dir>", "Target directory (default: ./src/tools/<slug>)")
-  .action(async (options) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const ask = (q) => new Promise((r) => rl.question(q, r));
-
-    let slug = options.slug;
-    while (!slug || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
-      slug = (await ask(chalk.cyan("Tool slug (e.g. my-tool): "))).trim().toLowerCase();
-      if (!slug) { console.log(chalk.red("Slug is required.")); continue; }
-      if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
-        console.log(chalk.red("Slug must be lowercase, hyphenated (e.g. my-tool)."));
-        slug = null;
-      }
-    }
-
-    let name = options.name;
-    while (!name || name.length < 2) {
-      name = (await ask(chalk.cyan("Display name: "))).trim();
-      if (!name) console.log(chalk.red("Name is required."));
-    }
-
-    let desc = options.desc;
-    while (!desc) {
-      desc = (await ask(chalk.cyan("Short description: "))).trim();
-      if (!desc) console.log(chalk.red("Description is required."));
-    }
-
-    let category = options.category;
-    while (!category || !VALID_CATEGORIES.includes(category)) {
-      const catList = VALID_CATEGORIES.join(", ");
-      category = (await ask(chalk.cyan("Category (" + catList + "): "))).trim().toLowerCase();
-      if (category === "other") category = "Other";
-      if (!VALID_CATEGORIES.includes(category)) {
-        console.log(chalk.red("Invalid category. Choose from: " + catList));
-        category = null;
-      }
-    }
-
-    let runtime = options.runtime;
-    while (!runtime || !VALID_RUNTIMES.includes(runtime)) {
-      const rtList = VALID_RUNTIMES.join(", ");
-      runtime = (await ask(chalk.cyan("Runtime (" + rtList + "): "))).trim().toLowerCase();
-      if (!VALID_RUNTIMES.includes(runtime)) {
-        console.log(chalk.red("Invalid runtime. Choose from: " + rtList));
-        runtime = null;
-      }
-    }
-
-    rl.close();
-
-    const pascalName = slug
-      .split("-")
-      .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
-      .join("");
-
-    const v2Source = `/**
- * ${name} — ${desc}
- * Auto-generated by nxb create
- */
-
-export const MANIFEST = {
-  slug: "${slug}",
-  name: "${name}",
-  short_description: "${desc}",
-  icon: "🛠️",
-  category: "${category}",
-  tags: [],
-  runtime: "${runtime}",
-  pricing: "free",
-  version: "1.0.0",
-  timeout_ms: 5000,
-  input_schema: {
-    type: "object",
-    properties: {
-      input: {
-        type: "string",
-        description: "Input text to process",
-      },
-    },
-    required: ["input"],
-  },
-  output_schema: {
-    type: "object",
-    properties: {
-      result: {
-        type: "string",
-        description: "Processed output",
-      },
-    },
-  },
-};
-
-export async function coreLogic(input) {
-  // Replace with your tool's logic
-  return { result: \`Processed: \${input.input}\` };
-}
-`;
-
-    const indexSource = `import React from "react";
-import { MANIFEST } from "./v2";
-
-export default function ${pascalName}Tool({ onResult }) {
-  const [input, setInput] = React.useState("");
-  const [result, setResult] = React.useState(null);
-
-  const handleRun = async () => {
-    try {
-      const { coreLogic } = await import("./v2");
-      const output = await coreLogic({ input });
-      setResult(output);
-      if (onResult) onResult(output);
-    } catch (err) {
-      setResult({ error: err.message });
-    }
-  };
-
-  return (
-    <div className="nexusbloom-tool">
-      <h2 className="text-xl font-bold mb-4">{MANIFEST.name}</h2>
-      <p className="text-gray-600 dark:text-gray-400 mb-4">{MANIFEST.short_description}</p>
-      <textarea className="w-full p-2 border rounded" rows={4} value={input}
-        onChange={(e) => setInput(e.target.value)} placeholder="Enter input..." />
-      <button className="mt-2 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
-        onClick={handleRun}>Run</button>
-      {result && <pre className="mt-4 p-3 bg-gray-100 rounded overflow-auto">{JSON.stringify(result, null, 2)}</pre>}
-    </div>
-  );
-}
-`;
-
-    const targetDir = options.dir || path.join(process.cwd(), "src/tools", slug);
-    const v2Path = path.join(targetDir, "v2.js");
-    const indexPath = path.join(targetDir, "index.js");
-
-    if (fs.existsSync(v2Path) || fs.existsSync(indexPath)) {
-      const overwrite = await new Promise((r) => {
-        const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
-        rl2.question(chalk.yellow(`Tool "${slug}" already exists. Overwrite? (y/N): `), (a) => {
-          rl2.close();
-          r(a.trim().toLowerCase() === "y");
-        });
-      });
-      if (!overwrite) {
-        console.log(chalk.dim("Aborted."));
-        return;
-      }
-    }
-
-    fs.mkdirSync(targetDir, { recursive: true });
-    fs.writeFileSync(v2Path, v2Source, "utf-8");
-    fs.writeFileSync(indexPath, indexSource, "utf-8");
-
-    console.log(chalk.green(`\n  ✓ Tool "${name}" created successfully!\n`));
-    console.log(chalk.dim(`    ${v2Path}`));
-    console.log(chalk.dim(`    ${indexPath}\n`));
-    console.log(chalk.dim("  Next steps:"));
-    console.log(chalk.dim("    1. Edit v2.js to implement your tool logic"));
-    console.log(chalk.dim("    2. Run nxb run --local <slug> to test locally"));
-    console.log(chalk.dim("    3. Publish from the VS Code extension or API\n"));
+cacheCmd
+  .command("path")
+  .description("Show where config and cache are stored")
+  .action(() => {
+    console.log(chalk.bold("\n  Paths\n"));
+    console.log(`  ${chalk.gray("config :")} ${CONFIG_PATH}`);
+    console.log(`  ${chalk.gray("cache  :")} ${CACHE_DIR}`);
+    console.log(`  ${chalk.gray("tools  :")} ${TOOLS_CACHE_DIR}`);
+    console.log();
   });
 
 // ─── `nxb json` ─────────────────────────────────────────────────────────────
@@ -520,15 +570,18 @@ program
   .option("-s, --set <key=value...>", "Set specific field values (e.g. -s count=10 format=csv)")
   .option("-a, --add <json>", "Merge additional JSON into the output (e.g. -a '{\"count\":20}')")
   .action(async (opts, cmd) => {
-    const jsonMode = cmd.parent.opts().json;
+    const jsonMode = jsonFlag(cmd);
 
     if (opts.template) {
-      const resolved = await resolveToolSlug(opts.template);
+      const safe = requireSlug(opts.template, jsonMode);
+      if (!safe) return;
+
+      const resolved = await resolveToolSlug(safe);
       const toolInfo = await fetchToolSource(resolved);
       const manifest = toolInfo?.manifest;
 
       if (!manifest) {
-        console.error(chalk.red(`Tool "${resolved}" not found. Set NEXUSBLOOM_SUPABASE_ANON_KEY or deploy the API.`));
+        console.error(chalk.red(`Tool "${resolved}" not found.`));
         process.exitCode = 1;
         return;
       }
@@ -537,6 +590,12 @@ program
       let result = {};
 
       if (opts.interactive) {
+        if (!isInteractive()) {
+          console.error(chalk.red("Not an interactive terminal — cannot prompt for fields."));
+          console.error(chalk.dim("  Drop -i, or use `nxb run` bare to pick fields interactively."));
+          process.exitCode = 1;
+          return;
+        }
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         const ask = (q) => new Promise((r) => rl.question(q, r));
 
@@ -621,6 +680,12 @@ program
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function promptValue(key) {
+  if (!isInteractive()) {
+    console.error(chalk.red("Not an interactive terminal — pass the value as an argument."));
+    console.error(chalk.dim(`  nxb config set ${key} <value>`));
+    process.exitCode = 1;
+    return Promise.resolve("");
+  }
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
     rl.question(chalk.cyan(`  Enter value for "${key}": `), (answer) => {
@@ -660,4 +725,11 @@ function renderToolInfo(manifest, resolved) {
   console.log();
 }
 
-program.parse(process.argv);
+// `parse` does not await the async action handlers, so a Ctrl+C inside an
+// inquirer prompt surfaces here as a rejected promise rather than a thrown
+// error. Catching it turns a stack trace into a clean, conventional exit.
+program.parseAsync(process.argv).catch((err) => {
+  if (!isExitPromptError(err)) throw err;
+  process.stderr.write("\n  Cancelled.\n");
+  process.exit(130);
+});