@nexusbloom/cli 0.3.4 → 0.8.0

package/src/commands.js

@@ -0,0 +1,253 @@
+/**
+ * commands.js — `nxb pipe`, `nxb doctor` and the shared execution glue.
+ *
+ * Kept out of index.js so the command definitions stay readable and so the
+ * wizard can reuse the same run path the CLI uses.
+ */
+
+import fs from "fs";
+import path from "path";
+
+import chalk from "chalk";
+
+import { fetchToolSource, fetchTools, filterTools, rankTools } from "./tools.js";
+import { execInSandbox } from "./sandbox.js";
+import { runRemote, reportError } from "./run.js";
+import { configGet } from "./tools.js";
+import {
+  PipeError,
+  buildPlan,
+  describeOutput,
+  parsePipeline,
+  renderPlan,
+  runPipeline,
+} from "./pipe.js";
+import { inferType, schemaTypes, typeLabel } from "./types.js";
+import { MISSING, getPath, preview, transformNames, parsePath, formatPath } from "./values.js";
+import { buildWizard } from "./wizard.js";
+
+/** Shared manifest/tool lookup used by the plan, the runner and the wizard. */
+const getManifest = (slug) => fetchToolSource(slug).then((t) => t ?? null);
+const getTool = (slug) => fetchToolSource(slug);
+
+/** Prefer local execution; fall back to the API when a key is configured. */
+function makeExecutor({ jsonMode, forceRemote }) {
+  return async ({ slug, source, input }) => {
+    const apiKey = process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
+    if (forceRemote && apiKey) {
+      const res = await runRemote(slug, input, { apiKey, jsonMode: false, quiet: true });
+      if (res?.ok) return { ok: true, result: res.result };
+      return { ok: false, error: res?.error || "remote execution failed" };
+    }
+    if (source) {
+      const manifest = (await getManifest(slug))?.manifest;
+      return execInSandbox({ source, input, timeoutMs: manifest?.timeout_ms || 5000 });
+    }
+    if (apiKey) {
+      const res = await runRemote(slug, input, { apiKey, jsonMode: false, quiet: true });
+      if (res?.ok) return { ok: true, result: res.result };
+      return { ok: false, error: res?.error || "remote execution failed" };
+    }
+    return { ok: false, error: `No runnable source available for "${slug}".` };
+  };
+}
+
+/**
+ * `nxb pipe` — run a pipeline from a command string.
+ *
+ * @param {string} spec  e.g. "tool-a x=@in | tool-b count=$n|len"
+ */
+export async function pipeAction(spec, opts = {}) {
+  const { json: jsonMode, dryRun = false, remote = false } = opts;
+
+  let steps;
+  try {
+    steps = parsePipeline(spec);
+  } catch (err) {
+    return reportError(jsonMode, err.message);
+  }
+
+  let plan;
+  try {
+    plan = await buildPlan(steps, getManifest);
+  } catch (err) {
+    return reportError(jsonMode, `Could not resolve tools: ${err.message}`);
+  }
+
+  if (!jsonMode) console.error(renderPlan(plan));
+
+  if (!plan.ok) {
+    return reportError(jsonMode, "Pipeline wiring has errors (see above). Fix them and re-run.");
+  }
+  if (dryRun) {
+    if (jsonMode) console.log(JSON.stringify({ ok: true, dryRun: true, steps: plan.steps.map((s) => s.slug) }, null, 2));
+    return { ok: true, dryRun: true };
+  }
+
+  // Standard input is consumed lazily: a pipeline with no @in must not block.
+  let stdinValue = null;
+  const usesStdin = steps.some((s) => s.inputs.some((i) => i.expr.kind === "stdin"));
+  if (usesStdin) {
+    const { readStdin } = await import("./tools.js");
+    const raw = await readStdin();
+    if (raw && raw.trim()) {
+      try {
+        stdinValue = JSON.parse(raw);
+      } catch {
+        stdinValue = raw;
+      }
+    }
+  }
+
+  const execute = makeExecutor({ jsonMode, forceRemote: remote });
+  const quiet = jsonMode || opts.quiet === true;
+
+  try {
+    const result = await runPipeline({
+      steps: plan.steps,
+      getTool,
+      execute,
+      stdin: stdinValue,
+      onStep: quiet
+        ? undefined
+        : ({ phase, index, step, output, durationMs, resolvedInputs }) => {
+            if (phase === "start") {
+              const wires = Object.entries(resolvedInputs || {})
+                .filter(([, v]) => v.from !== "literal")
+                .map(([k, v]) => `${k}=${preview(v.value, 18)}`)
+                .join(" ");
+              console.error(
+                chalk.gray(`  ▶ ${index + 1}/${plan.steps.length}  ${step.slug.padEnd(26)}`) +
+                  (wires ? chalk.dim(` ${wires}`) : "")
+              );
+            } else {
+              console.error(
+                chalk.green(`    ✓ ${String(durationMs ?? 0).padStart(5)}ms  `) + describeOutput(output)
+              );
+            }
+          },
+    });
+
+    const final = result.outputs[result.outputs.length - 1];
+    if (jsonMode) {
+      console.log(JSON.stringify({ success: true, output: final, steps: result.outputs }, null, 2));
+    } else {
+      console.error(chalk.dim("\n  Result:"));
+      console.log(typeof final === "string" ? final : JSON.stringify(final, null, 2));
+    }
+    return { ok: true, output: final };
+  } catch (err) {
+    if (err instanceof PipeError) return reportError(jsonMode, err.message);
+    return reportError(jsonMode, err.message || String(err));
+  }
+}
+
+/** `nxb pipe --transforms` — list the value transforms available in connections. */
+export function listTransforms(jsonMode) {
+  const names = transformNames();
+  if (jsonMode) {
+    console.log(JSON.stringify({ transforms: names }, null, 2));
+    return;
+  }
+  console.log(chalk.bold("\n  Connection transforms\n"));
+  const rows = [
+    ["len / count / words / lines / chars", "size of a string, array or object"],
+    ["first / last / get(i) / slice(a,b)", "reduce an array to a single value"],
+    ["join(sep) / split(sep) / reverse / sort(key)", "reshape collections"],
+    ["keys / values / pick(field)", "reach into an object"],
+    ["upper / lower / trim / replace(a,b) / pad(n)", "edit text"],
+    ["int() / float() / num / str / bool()", "change type — required for casts"],
+    ["json / unjson", "serialise / parse"],
+    ["default(v)", "supply a value when the path is missing"],
+  ];
+  for (const [a, b] of rows) console.log(`  ${chalk.cyan(a.padEnd(42))} ${chalk.dim(b)}`);
+  console.log(chalk.dim("\n  Use:  key=$path|transform        (no spaces around |)\n"));
+  return { ok: true };
+}
+
+/**
+ * `nxb doctor <slug>` — run a tool once and compare what it returned against
+ * its declared output_schema.
+ *
+ * Declared schemas are the only static typing the pipeline planner has, so
+ * drift here is what makes a pipeline fail for no visible reason.
+ */
+export async function doctorAction(slug, opts = {}) {
+  const { json: jsonMode } = opts;
+  const info = await getManifest(slug);
+  if (!info?.manifest) return reportError(jsonMode, `Tool "${slug}" not found.`);
+
+  const { manifest, coreLogicSource } = info;
+  const declared = manifest.output_schema?.properties || {};
+  const declaredKeys = Object.keys(declared);
+
+  if (!coreLogicSource) {
+    return reportError(jsonMode, `"${slug}" publishes no runnable source — cannot compare output.`);
+  }
+
+  // Build the smallest valid input the schema allows.
+  const input = buildSampleInput(manifest.input_schema);
+  const res = await execInSandbox({ source: coreLogicSource, input, timeoutMs: manifest.timeout_ms || 5000 });
+  if (!res.ok) return reportError(jsonMode, `Could not run "${slug}": ${res.error}`);
+
+  const actual = res.result && typeof res.result === "object" ? res.result : { value: res.result };
+  const actualKeys = Object.keys(actual);
+
+  const undeclared = actualKeys.filter((k) => !declaredKeys.includes(k));
+  const missing = declaredKeys.filter((k) => !actualKeys.includes(k));
+  const mistyped = actualKeys
+    .filter((k) => declared[k])
+    .map((k) => ({ key: k, declared: typeLabel(schemaTypes(declared[k])), actual: inferType(actual[k]) }))
+    .filter((r) => {
+      const d = r.declared.split("|");
+      return !d.includes(r.actual) && !(r.actual === "integer" && d.includes("number"));
+    });
+
+  const healthy = !undeclared.length && !missing.length && !mistyped.length;
+
+  if (jsonMode) {
+    console.log(
+      JSON.stringify(
+        { slug, healthy, input, declaredKeys, actualKeys, undeclared, missing, mistyped, sample: actual },
+        null,
+        2
+      )
+    );
+    return { ok: healthy };
+  }
+
+  console.log(chalk.bold(`\n  ${slug}\n`));
+  console.log(`  ${chalk.gray("input   :")} ${chalk.dim(JSON.stringify(input))}`);
+  if (healthy) {
+    console.log(chalk.green(`  ✓ output_schema matches the tool's real output (${actualKeys.length} fields)`));
+  } else {
+    if (undeclared.length) {
+      console.log(chalk.yellow(`  ! undeclared output fields: ${undeclared.join(", ")}`));
+      console.log(chalk.dim("    These are invisible to the pipeline planner — only the runtime check sees them."));
+    }
+    if (missing.length) console.log(chalk.yellow(`  ! declared but never returned: ${missing.join(", ")}`));
+    for (const m of mistyped) {
+      console.log(chalk.red(`  ✗ ${m.key}: declared ${m.declared}, actually returns ${m.actual}`));
+    }
+  }
+  console.log();
+  return { ok: healthy };
+}
+
+/** Minimal valid input for a schema — enough to make a tool run once. */
+function buildSampleInput(schema) {
+  const props = schema?.properties || {};
+  const input = {};
+  for (const [key, prop] of Object.entries(props)) {
+    if (prop.default !== undefined) input[key] = prop.default;
+    else if (Array.isArray(prop.enum) && prop.enum.length) input[key] = prop.enum[0];
+    else if (prop.type === "string") input[key] = "sample";
+    else if (prop.type === "integer" || prop.type === "number") input[key] = 1;
+    else if (prop.type === "boolean") input[key] = true;
+    else if (prop.type === "array") input[key] = [];
+    else if (prop.type === "object") input[key] = {};
+  }
+  return input;
+}
+
+export { buildWizard, filterTools, rankTools, fetchTools, getPath, MISSING, parsePath, formatPath, transformNames };

package/src/compile.js

@@ -0,0 +1,69 @@
+/**
+ * compile.js — Turn a tool's v2 source text into a callable `coreLogic`.
+ *
+ * Tool source is an ES module, but the sandbox runner has no module loader, so
+ * module syntax is stripped before evaluation. Only ever call this from inside
+ * the child process (see runner.js / sandbox.js) — it evaluates code.
+ */
+
+/**
+ * Remove `import` / `export` syntax so the body can run as a bare script.
+ *
+ * Statements are matched on a boundary (start of text, line start, or just
+ * after `;`/`{`/`}`) rather than on `^\s*`, because real tool files put several
+ * exports on one line: `export const A = 1;export const B = 2;`.
+ */
+export function stripModuleSyntax(source) {
+  // $1 preserves the boundary character so the remaining code stays valid.
+  const B = "(^|[;{}])";
+
+  return String(source)
+    // import ... from "mod"  (named, default, namespace, multi-line)
+    .replace(new RegExp(`${B}\\s*import\\s+[^;]*?\\s+from\\s+["'][^"']+["']\\s*;?`, "gm"), "$1")
+    // import "mod"
+    .replace(new RegExp(`${B}\\s*import\\s+["'][^"']+["']\\s*;?`, "gm"), "$1")
+    // export { a, b } [from "mod"]
+    .replace(
+      new RegExp(`${B}\\s*export\\s*\\{[^}]*\\}\\s*(?:from\\s+["'][^"']+["'])?\\s*;?`, "gm"),
+      "$1"
+    )
+    // export default
+    .replace(new RegExp(`${B}\\s*export\\s+default\\s+`, "gm"), "$1 ")
+    // export const/let/var/function/async/class
+    .replace(
+      new RegExp(`${B}\\s*export\\s+(?=(?:const|let|var|function|async|class)\\b)`, "gm"),
+      "$1 "
+    );
+}
+
+/**
+ * Compile source text into a `coreLogic(input)` function.
+ *
+ * Supports `function coreLogic`, `async function coreLogic`, and
+ * `const coreLogic = (…) => …` (sync or async). Throws if no callable
+ * `coreLogic` is exported.
+ */
+export function compileCoreLogic(source) {
+  const clean = stripModuleSyntax(source);
+
+  const attempts = [
+    // Named `coreLogic` binding (declaration or const/arrow assignment).
+    `return (function() {\n${clean}\n;return typeof coreLogic !== "undefined" ? coreLogic : undefined;})();`,
+    // Default-export fallback: the module body evaluates to the function.
+    `return (function() {\n${clean}\n})();`,
+  ];
+
+  let lastError;
+  for (const body of attempts) {
+    try {
+      // eslint-disable-next-line no-new-func
+      const value = new Function(body)();
+      if (typeof value === "function") return value;
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw new Error(
+    `Tool source does not export a coreLogic() function${lastError ? `: ${lastError.message}` : ""}`
+  );
+}

package/src/diagnostics.js

@@ -0,0 +1,41 @@
+/**
+ * diagnostics.js — Explain an empty tool catalogue.
+ *
+ * "0 tools" is indistinguishable from a broken network, a typo'd base URL, or
+ * a cache that was never populated. Saying which one it is turns a dead end
+ * into an actionable message.
+ */
+
+import { API_BASE } from "./tools.js";
+import { reportError } from "./run.js";
+
+/**
+ * @param {{offline?: boolean, jsonMode?: boolean, source?: string}} opts
+ */
+export async function diagnoseEmptyCatalogue({ offline = false, jsonMode = false, source = "cache" } = {}) {
+  if (offline) {
+    return reportError(
+      jsonMode,
+      `No tools in the local ${source}. Run \`nxb list --refresh\` once while online to populate it.`
+    );
+  }
+
+  const base = API_BASE;
+  try {
+    const res = await fetch(`${base}/api/tools`, { signal: AbortSignal.timeout(8000) });
+    if (!res.ok) {
+      return reportError(jsonMode, `Tool catalogue unavailable: HTTP ${res.status} from ${base}/api/tools`);
+    }
+    const data = await res.json().catch(() => null);
+    if (Array.isArray(data?.tools)) {
+      return reportError(jsonMode, `The API returned no tools. Run \`nxb list --refresh\` after publishing one.`);
+    }
+  } catch {
+    return reportError(
+      jsonMode,
+      `Could not reach ${base}. Check your connection or set NEXUSBLOOM_API_URL, or use \`nxb list --offline\`.`
+    );
+  }
+
+  return reportError(jsonMode, "No tools available. Run `nxb list --refresh` to re-fetch the catalogue.");
+}