@nexusbloom/cli 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @nexusbloom/cli
+
+CLI tool for NexusBloom — run tools and workflows from your terminal.
+
+## Install
+
+```bash
+npm install -g @nexusbloom/cli
+```
+
+## Usage
+
+```bash
+# List available tools
+nxb list
+
+# Search tools
+nxb search "ssl"
+
+# Run a tool (remote API, requires API key)
+nxb run ssl-certificate-checker domain=example.com --key YOUR_API_KEY
+
+# Run with inline JSON input
+nxb run css-gradient-generator --input '{"colors":["#ff6b6b","#4ecdc4"],"angle":135}'
+
+# Run with file input
+nxb run css-gradient-generator --file ./gradient-input.json
+
+# Run a tool locally (fetches + caches tool source, executes coreLogic on your machine)
+nxb run ssl-certificate-checker domain=example.com --local
+
+# Pipe stdin through a tool
+echo '{"domain":"example.com"}' | nxb transform ssl-certificate-checker
+
+# Describe what you want
+nxb chat "check if my website example.com is secure"
+
+# Show tool schema
+nxb info ssl-certificate-checker
+
+# Manage local tool cache
+nxb cache list
+nxb cache clear
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output results in JSON format |
+| `--key <key>` | API key (can also set via `NEXUSBLOOM_API_KEY` env var) |
+| `--input <json>` | Inline JSON input (e.g. `'{"domain":"example.com"}'`) |
+| `--file <path>` | Read input from a JSON file |
+| `--local` | Execute coreLogic locally (fetches + caches tool source) |
+
+## Environment Variables
+
+- `NEXUSBLOOM_API_KEY` — Your API key (can also be passed with `--key`)
+- `NEXUSBLOOM_API_URL` — API base URL (default: https://nexusbloom.dev)
+
+## Local Execution
+
+The `--local` flag fetches the tool's v2 source code from the NexusBloom API,
+caches it locally, and executes the `coreLogic()` function directly on your
+machine. This is useful for:
+
+- Offline use (after initial fetch)
+- Faster repeated execution (cached)
+- Privacy-sensitive inputs (data stays on your machine)
+
+Use `nxb cache clear` to clear the local cache.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@nexusbloom/cli",
+  "version": "0.1.0",
+  "description": "NexusBloom CLI — run tools and workflows from your terminal",
+  "type": "module",
+  "bin": {
+    "nxb": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "conf": "^12.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,559 @@
+#!/usr/bin/env node
+
+/**
+ * NexusBloom CLI (nxb)
+ *
+ * Usage:
+ *   nxb list                          — List available tools
+ *   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 chat <message>                — Natural language routing
+ *   nxb info <slug>                    — Show tool schema
+ *   nxb transform <slug>              — Pipe stdin through a tool
+ *   nxb config set <key> <value>      — Set config
+ *   nxb config get [key]              — Get config
+ *   nxb cache clear                   — Clear local tool cache
+ */
+
+import { program } from "commander";
+import chalk from "chalk";
+import { createRequire } from "module";
+import Conf from "conf";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+const API_BASE = process.env.NEXUSBLOOM_API_URL || "https://nexusbloom.dev";
+const config = new Conf({ projectName: "nexusbloom" });
+
+// ─── Cache directory for local tool execution ────────────────────────────────
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CACHE_DIR = path.resolve(__dirname, "../.cache/tools");
+
+function ensureCacheDir() {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+  }
+}
+
+// ─── Program ─────────────────────────────────────────────────────────────────
+program
+  .name("nxb")
+  .description("NexusBloom CLI — run tools and workflows from your terminal")
+  .version(version)
+  .option("--json", "Output in JSON format");
+
+// ─── `nxb list` — list available tools ───────────────────────────────────────
+program
+  .command("list")
+  .description("List available tools")
+  .option("-s, --search <query>", "Search tools by name or description")
+  .action(async (opts, cmd) => {
+    const jsonMode = cmd.parent.opts().json || opts.json;
+    try {
+      const url = new URL("/api/v1/tools", API_BASE);
+      if (opts.search) url.searchParams.set("search", opts.search);
+      const res = await fetch(url);
+      const { tools } = await res.json();
+      if (!tools || tools.length === 0) {
+        if (jsonMode) return console.log(JSON.stringify({ tools: [] }));
+        console.log(chalk.yellow("No tools found."));
+        return;
+      }
+      if (jsonMode) return console.log(JSON.stringify({ tools }, null, 2));
+      console.log(chalk.bold(`\n  ${tools.length} tool${tools.length > 1 ? "s" : ""} available\n`));
+      tools.forEach((t) => {
+        console.log(`  ${chalk.cyan(t.slug.padEnd(30))} ${chalk.dim((t.description || "").slice(0, 60))}`);
+      });
+      console.log();
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+      console.error(chalk.red("Failed to fetch tools:"), err.message);
+    }
+  });
+
+// ─── `nxb search <query>` — search tools ─────────────────────────────────────
+program
+  .command("search")
+  .description("Search for tools")
+  .argument("<query>", "Search query")
+  .action(async (query, cmd) => {
+    const jsonMode = cmd.parent.opts().json;
+    try {
+      const url = new URL("/api/v1/tools", API_BASE);
+      url.searchParams.set("search", query);
+      const res = await fetch(url);
+      const { tools } = await res.json();
+      if (!tools || tools.length === 0) {
+        if (jsonMode) return console.log(JSON.stringify({ tools: [] }));
+        console.log(chalk.yellow(`No tools matching "${query}".`));
+        return;
+      }
+      if (jsonMode) return console.log(JSON.stringify({ tools, query }, null, 2));
+      console.log(chalk.bold(`\n  ${tools.length} result${tools.length > 1 ? "s" : ""} for "${query}"\n`));
+      tools.forEach((t) => {
+        console.log(`  ${chalk.cyan(t.slug.padEnd(30))} ${chalk.dim((t.description || "").slice(0, 60))}`);
+      });
+      console.log();
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+      console.error(chalk.red("Search failed:"), err.message);
+    }
+  });
+
+// ─── `nxb run <slug>` — execute a tool ───────────────────────────────────────
+program
+  .command("run")
+  .description("Execute a tool")
+  .argument("<slug>", "Tool slug")
+  .argument("[args...]", "Key=value arguments (e.g. domain=example.com)")
+  .option("-k, --key <key>", "API key (or set NEXUSBLOOM_API_KEY env var)")
+  .option("-i, --input <json>", "Inline JSON input (e.g. '{\"domain\":\"example.com\"}')")
+  .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;
+
+    // ── Build input body ────────────────────────────────────────────────
+    let body = {};
+
+    // 1. --input flag takes highest priority
+    if (opts.input) {
+      try {
+        body = JSON.parse(opts.input);
+      } catch {
+        if (jsonMode) return console.log(JSON.stringify({ error: "Invalid JSON in --input flag" }));
+        console.error(chalk.red("Error: --input must be valid JSON"));
+        process.exit(1);
+      }
+    }
+
+    // 2. --file flag reads from a file
+    if (opts.file) {
+      try {
+        const fileContent = fs.readFileSync(path.resolve(opts.file), "utf-8");
+        const fileData = JSON.parse(fileContent);
+        // Merge file data, with --input taking precedence
+        body = { ...fileData, ...body };
+      } catch (err) {
+        if (jsonMode) return console.log(JSON.stringify({ error: `Failed to read --file: ${err.message}` }));
+        console.error(chalk.red(`Error reading file: ${err.message}`));
+        process.exit(1);
+      }
+    }
+
+    // 3. Key=value args (lowest priority, merged in)
+    if (!opts.input && !opts.file) {
+      (args || []).forEach((arg) => {
+        const [k, ...v] = arg.split("=");
+        body[k] = v.join("=");
+      });
+    }
+
+    // ── Local execution mode ────────────────────────────────────────────
+    if (opts.local) {
+      return await executeLocal(slug, body, jsonMode);
+    }
+
+    // ── Remote API execution ────────────────────────────────────────────
+    const apiKey = opts.key || process.env.NEXUSBLOOM_API_KEY || config.get("apiKey");
+    if (!apiKey) {
+      if (jsonMode) return console.log(JSON.stringify({ error: "API key required. Set NEXUSBLOOM_API_KEY, pass --key, or run `nxb config set key <your-key>`." }));
+      console.error(chalk.red("API key required. Set NEXUSBLOOM_API_KEY, pass --key, or run `nxb config set key <your-key>`."));
+      process.exit(1);
+    }
+
+    try {
+      const res = await fetch(`${API_BASE}/api/run/${slug}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+      });
+      const data = await res.json();
+      if (data.success) {
+        if (jsonMode) return console.log(JSON.stringify({ success: true, data: data.data }, null, 2));
+        console.log(chalk.green("\n  Result:"));
+        console.log(`  ${JSON.stringify(data.data, null, 2)}`);
+      } else {
+        if (jsonMode) return console.log(JSON.stringify({ success: false, error: data.error || "Unknown error" }, null, 2));
+        console.error(chalk.red(`\n  Error: ${data.error || "Unknown error"}`));
+        process.exit(1);
+      }
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+      console.error(chalk.red("Execution failed:"), err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── Local execution helper ──────────────────────────────────────────────────
+async function executeLocal(slug, input, jsonMode) {
+  ensureCacheDir();
+  const cacheFile = path.join(CACHE_DIR, `${slug}.json`);
+
+  // Try loading from cache first
+  let manifest, coreLogicSource;
+  if (fs.existsSync(cacheFile)) {
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, "utf-8"));
+      manifest = cached.manifest;
+      coreLogicSource = cached.coreLogicSource;
+      if (!jsonMode) console.log(chalk.dim(`  Using cached tool: ${slug}`));
+    } catch {
+      // Cache corrupted, refetch
+    }
+  }
+
+  // Fetch from API if not cached
+  if (!manifest || !coreLogicSource) {
+    if (!jsonMode) console.log(chalk.dim(`  Fetching tool: ${slug}...`));
+    try {
+      const res = await fetch(`${API_BASE}/api/run/${slug}`);
+      if (!res.ok) {
+        if (jsonMode) return console.log(JSON.stringify({ error: `Tool "${slug}" not found` }));
+        console.error(chalk.red(`Tool "${slug}" not found.`));
+        process.exit(1);
+      }
+      const data = await res.json();
+      manifest = data.manifest || data;
+
+      // Fetch the v2 source separately
+      const sourceRes = await fetch(`${API_BASE}/api/run/${slug}?source=true`);
+      if (sourceRes.ok) {
+        const sourceData = await sourceRes.json();
+        coreLogicSource = sourceData.data?.v2_source;
+      } else {
+        coreLogicSource = null;
+      }
+
+      // Cache it
+      if (manifest) {
+        fs.writeFileSync(cacheFile, JSON.stringify({ manifest, coreLogicSource, cachedAt: new Date().toISOString() }), "utf-8");
+      }
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: `Failed to fetch tool: ${err.message}` }));
+      console.error(chalk.red(`Failed to fetch tool: ${err.message}`));
+      process.exit(1);
+    }
+  }
+
+  if (!coreLogicSource) {
+    // Fallback: try to extract coreLogic from the manifest itself
+    if (jsonMode) return console.log(JSON.stringify({ error: "No v2 source available for local execution. Try without --local to use remote API." }));
+    console.error(chalk.yellow("No v2 source available for local execution. Try without --local to use remote API."));
+    process.exit(1);
+  }
+
+  // Execute coreLogic locally
+  try {
+    // Extract the coreLogic function from the source
+    const fnMatch = coreLogicSource.match(/export\s+(async\s+)?function\s+coreLogic[\s\S]*/);
+    if (!fnMatch) {
+      if (jsonMode) return console.log(JSON.stringify({ error: "Could not extract coreLogic from source" }));
+      console.error(chalk.red("Could not extract coreLogic from source"));
+      process.exit(1);
+    }
+    const fnSource = fnMatch[0].replace(/export\s+/, "");
+    const isAsync = fnMatch[0].startsWith("export async");
+
+    // Validate input against manifest
+    const schema = manifest.input_schema || {};
+    const required = schema.required || [];
+    const missing = required.filter((k) => input[k] === undefined || input[k] === null);
+    if (missing.length > 0) {
+      if (jsonMode) return console.log(JSON.stringify({ error: `Missing required fields: ${missing.join(", ")}` }));
+      console.error(chalk.red(`Missing required fields: ${missing.join(", ")}`));
+      process.exit(1);
+    }
+
+    // Apply defaults
+    if (schema.properties) {
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        if (input[key] === undefined && prop.default !== undefined) {
+          input[key] = prop.default;
+        }
+      }
+    }
+
+    // Create and execute the function
+    const coreLogic = new Function("return " + fnSource)();
+    const timeoutMs = manifest.timeout_ms || 5000;
+    let result;
+
+    if (isAsync) {
+      result = await Promise.race([
+        coreLogic(input),
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs)),
+      ]);
+    } else {
+      result = coreLogic(input);
+    }
+
+    if (jsonMode) return console.log(JSON.stringify({ success: true, data: result }, null, 2));
+    console.log(chalk.green("\n  Result (local):"));
+    console.log(`  ${JSON.stringify(result, null, 2)}`);
+  } catch (err) {
+    if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+    console.error(chalk.red(`\n  Local execution error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// ─── `nxb chat <message>` — describe what you want ───────────────────────────
+program
+  .command("chat")
+  .description("Describe what you want and let NexusBloom route to the right tools")
+  .argument("<message>", "What you want to do")
+  .action(async (message, cmd) => {
+    const jsonMode = cmd.parent.opts().json;
+    try {
+      if (!jsonMode) console.log(chalk.dim("  Routing your request..."));
+      const res = await fetch(`${API_BASE}/api/v1/route`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ task: message }),
+      });
+      const data = await res.json();
+      if (jsonMode) return console.log(JSON.stringify(data, null, 2));
+      if (data.matched_tools?.length > 0) {
+        console.log(chalk.bold(`\n  Matched ${data.matched_tools.length} tool${data.matched_tools.length > 1 ? "s" : ""}:\n`));
+        data.matched_tools.forEach((t) => {
+          console.log(`  ${chalk.cyan(t.slug.padEnd(30))} ${chalk.dim(`${Math.round(t.confidence * 100)}% match`)}`);
+        });
+        console.log();
+        if (data.results) {
+          console.log(chalk.bold("  Results:\n"));
+          data.results.forEach((r) => {
+            console.log(`  ${chalk.cyan(r.tool)}:`);
+            console.log(`  ${JSON.stringify(r.data, null, 4)}`);
+          });
+        }
+      } else {
+        console.log(chalk.yellow("  No matching tools found."));
+      }
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+      console.error(chalk.red("Chat failed:"), err.message);
+    }
+  });
+
+// ─── `nxb info <slug>` — show tool schema ────────────────────────────────────
+program
+  .command("info")
+  .description("Show tool schema and details")
+  .argument("<slug>", "Tool slug")
+  .action(async (slug, cmd) => {
+    const jsonMode = cmd.parent.opts().json;
+    try {
+      const res = await fetch(`${API_BASE}/api/run/${slug}`);
+      if (!res.ok) {
+        if (jsonMode) return console.log(JSON.stringify({ error: `Tool "${slug}" not found` }));
+        console.error(chalk.red(`Tool "${slug}" not found.`));
+        return;
+      }
+      const data = await res.json();
+      const manifest = data.manifest || data;
+      if (jsonMode) return console.log(JSON.stringify(manifest, null, 2));
+      console.log(chalk.bold(`\n  ${manifest.name}`));
+      console.log(`  ${chalk.dim(manifest.short_description || "")}`);
+      console.log(`  Version: ${chalk.cyan(manifest.version || "1.0.0")}`);
+      console.log(`  Runtime: ${chalk.cyan(manifest.runtime || "browser")}`);
+      console.log(`  Pricing: ${chalk.cyan(manifest.pricing || "free")}`);
+      if (manifest.input_schema?.properties) {
+        console.log(chalk.bold(`\n  Input Parameters:`));
+        const props = manifest.input_schema.properties;
+        const required = manifest.input_schema.required || [];
+        for (const [name, prop] of Object.entries(props)) {
+          const req = required.includes(name) ? chalk.red(" *required") : "";
+          console.log(`    ${chalk.cyan(name)} (${prop.type})${req}`);
+          if (prop.description) console.log(`      ${chalk.dim(prop.description)}`);
+        }
+      }
+      if (manifest.output_schema?.properties) {
+        console.log(chalk.bold(`\n  Output:`));
+        for (const [name, prop] of Object.entries(manifest.output_schema.properties)) {
+          console.log(`    ${chalk.cyan(name)} (${prop.type})`);
+        }
+      }
+      console.log();
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+      console.error(chalk.red("Failed to fetch tool info:"), err.message);
+    }
+  });
+
+// ─── `nxb transform <slug>` — pipe stdin through a tool ──────────────────────
+program
+  .command("transform")
+  .description("Pipe stdin through a tool and write result to stdout")
+  .argument("<slug>", "Tool slug")
+  .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 jsonMode = cmd.parent.opts().json;
+    const apiKey = opts.key || process.env.NEXUSBLOOM_API_KEY || config.get("apiKey");
+
+    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.exit(1);
+    }
+
+    let body;
+    try {
+      body = JSON.parse(input);
+    } catch {
+      body = { input };
+    }
+
+    if (opts.local) {
+      return await executeLocal(slug, body, jsonMode);
+    }
+
+    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."));
+      process.exit(1);
+    }
+
+    try {
+      const res = await fetch(`${API_BASE}/api/run/${slug}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+      });
+      const data = await res.json();
+      if (data.success) {
+        const output = typeof data.data === "string" ? data.data : JSON.stringify(data.data, null, 2);
+        if (jsonMode) return console.log(JSON.stringify({ success: true, data: data.data }, null, 2));
+        process.stdout.write(output + "\n");
+      } else {
+        if (jsonMode) return console.log(JSON.stringify({ success: false, error: data.error || "Unknown error" }, null, 2));
+        console.error(chalk.red(`\n  Error: ${data.error || "Unknown error"}`));
+        process.exit(1);
+      }
+    } catch (err) {
+      if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
+      console.error(chalk.red("Transform failed:"), err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── `nxb config` — manage configuration ─────────────────────────────────────
+const configCmd = program
+  .command("config")
+  .description("Manage CLI configuration");
+
+configCmd
+  .command("set")
+  .description("Set a config value")
+  .argument("<key>", "Config key (key, default-tool)")
+  .argument("<value>", "Config value")
+  .action((key, value) => {
+    config.set(key, value);
+    console.log(chalk.green(`  Set ${key} to "${value}"`));
+  });
+
+configCmd
+  .command("get")
+  .description("Get a config value")
+  .argument("[key]", "Config key (omit to show all)")
+  .action((key) => {
+    if (key) {
+      const value = config.get(key);
+      if (value === undefined) {
+        console.log(chalk.yellow(`  ${key} is not set`));
+      } else {
+        console.log(`  ${key}: ${value}`);
+      }
+    } else {
+      const store = config.store;
+      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}`);
+        });
+      }
+    }
+  });
+
+configCmd
+  .command("list")
+  .description("List all config values (alias for config get)")
+  .action(() => {
+    const store = config.store;
+    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}`);
+      });
+    }
+  });
+
+// ─── `nxb cache` — manage local tool cache ─────────────────────────────────
+const cacheCmd = program
+  .command("cache")
+  .description("Manage local tool cache");
+
+cacheCmd
+  .command("clear")
+  .description("Clear the local tool cache")
+  .action(() => {
+    ensureCacheDir();
+    const files = fs.readdirSync(CACHE_DIR);
+    let count = 0;
+    for (const file of files) {
+      fs.unlinkSync(path.join(CACHE_DIR, file));
+      count++;
+    }
+    console.log(chalk.green(`  Cleared ${count} cached tool${count !== 1 ? "s" : ""}.`));
+  });
+
+cacheCmd
+  .command("list")
+  .description("List cached tools")
+  .action(() => {
+    ensureCacheDir();
+    const files = fs.readdirSync(CACHE_DIR);
+    if (files.length === 0) {
+      console.log(chalk.yellow("  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(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();
+  });
+
+program.parse(process.argv);
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function readStdin() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(chunks.join("")));
+    if (process.stdin.isTTY) resolve("");
+  });
+}