@nexusbloom/cli 0.9.4 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusbloom/cli",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "NexusBloom CLI — run tools and workflows from your terminal",
   "type": "module",
   "bin": {

package/src/abbr.js

@@ -1,13 +1,7 @@
 /**
  * abbr.js — `nxb abbr` command.
  *
- * Paginated abbreviation view.
- *
- *   nxb abbr                 — interactive pagination (20/page)
- *   nxb abbr ip              — filter by query (matches slug, abbr, or name)
- *   nxb abbr -s ip           — same, explicit flag
- *   nxb abbr --json          — raw JSON
- *   nxb abbr --no-interactive— single dump
+ * Paginated abbreviation view. Flags are declared in index.js.
  */
 
 import chalk from "chalk";

package/src/index.js

@@ -1,27 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * NexusBloom CLI (nxb)
+ * NexusBloom CLI (nxb) — command wiring.
  *
- * Usage:
- *   nxb list                           — List available tools (interactive pagination)
- *   nxb list -s <query>                — Filter + paginate
- *   nxb search <query>                 — Search tools
- *   nxb run <slug> [args...]           — Execute a tool (remote API)
- *   nxb run <slug> --input '{}'        — Execute with inline JSON input
- *   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 [-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 (secrets redacted)
- *   nxb cache clear                    — Clear local tool cache
- *   nxb cache list                     — List cached tools
- *   nxb cache path                     — Print where config/cache live
- *   nxb json --template <slug>         — Create JSON input for tools
+ * Commands are declared with commander below, and `--help` is generated from
+ * those declarations. A hand-maintained usage list in this header was always
+ * going to drift from the code, so there isn't one; README.md carries the
+ * task-oriented examples.
  */
 
 import { program } from "commander";

package/src/list.js

@@ -1,12 +1,9 @@
 /**
  * list.js — `nxb list` command.
  *
- * Paginated tool listing. Long lists are always paired with a search option.
- *
- *   nxb list                  — interactive pagination (20/page)
- *   nxb list -s ssl           — filter + paginate
- *   nxb list --json           — raw JSON
- *   nxb list --no-interactive — single dump
+ * Paginated tool listing. Long lists are always paired with a search option;
+ * `--json` and the other flags are declared in index.js, which is also where
+ * `--help` reads them from.
  */
 
 import chalk from "chalk";

package/src/run.js

@@ -2,11 +2,11 @@
  * run.js — `nxb run` command.
  *
  * Two modes:
- *   1. Direct:  nxb run <slug> [key=value ...] [--input json] [--file path] [--local]
- *   2. Interactive: nxb run (no slug) → select tool → pick inputs → auto-build & execute
+ *   1. Direct:       nxb run <slug> [key=value ...] [--input json] [--file path] [--local]
+ *   2. Interactive:  nxb run  → select tool → pick inputs → auto-build & execute
  *
- * Imports execution logic from the original monolithic index.js but adds
- * inquirer-driven field prompting for the interactive path.
+ * The interactive path is only entered when no slug and no input were supplied,
+ * otherwise a scripted call would block on a prompt it never sees.
  */
 
 import fs from "fs";

package/src/tools.js

@@ -1,29 +1,16 @@
 /**
- * tools.js — Centralised tool catalogue for the nxb CLI.
+ * tools.js — Tool catalogue resolution and config access.
  *
  * Resolution order for the *tool list*:
- *   1. Cached snapshot  (`.cache/tools-list.json`) — always written on a
- *      successful fetch so subsequent `list` / `abbr` calls are offline-fast.
- *   2. Live API          (`/api/tools`)
+ *   1. Cached snapshot (`$XDG_CACHE_HOME/nexusbloom/tools-list.json`) — written
+ *      on every successful fetch, so `list` / `abbr` stay fast and work offline
+ *   2. Live API (`/api/tools`)
  *   3. Supabase fallback (`/rest/v1/tools` + `/rest/v1/community_tools`)
- *   4. Local filesystem scan (`src/tools/<slug>/v2.js`)
+ *   4. Local filesystem scan — see `LOCAL_TOOL_DIRS` for the search roots
  *
- * Resolution order for a *single tool's source* (for `--local` execution):
- *   1. Local filesystem  → 2. cache (`tools/<slug>.json`) → 3. API/Supabase
- *
- * Exports:
- *   loadConfig / saveConfig / configGet / configSet / redactedConfig
- *   fetchTools()              — resolves list (cache-first on network failure)
- *   refreshTools()            — force a fresh fetch + persist to cache
- *   fetchToolSource(slug)     — { manifest, coreLogicSource }
- *   filterTools / rankTools   — shared search used by list / search / abbr / run
- *   isValidSlug / normalizeSlug
- *   scanLocalTools()
- *   findLocalTool(slug)
- *   generateAbbreviations(slugs)
- *   resolveToolSlug(slug, tools?)
- *   getSupabaseKey / getSupabaseUrl / supabaseHeaders
- *   API_BASE
+ * Resolution order for a *single tool's source* (for `--local` execution) is
+ * the mirror image: local filesystem, then cache, then API/Supabase. Local wins
+ * because a developer running `--local` is iterating on that file right now.
  */
 
 import fs from "fs";
@@ -446,7 +433,6 @@ export async function fetchToolSource(rawSlug) {
     const source = fs.readFileSync(localPath, "utf-8");
     const manifest = extractManifest(source, { trusted: true });
     if (manifest) {
-      // Refresh cache from local source
       fs.writeFileSync(cacheFile, JSON.stringify({ manifest, coreLogicSource: source, cachedAt: new Date().toISOString() }), "utf-8");
       return { manifest, coreLogicSource: source, source: "local" };
     }