@paradigma-inc/flywheel 0.1.35 → 0.1.52

package/src/unified-cli.mjs

@@ -0,0 +1,161 @@
+import { runCli as runSetupCli } from "./cli.mjs";
+import { runRuntimeCli } from "./runtime/delegate.mjs";
+import { RUNTIME_ALIASES } from "./runtime/vendor/flywheel-cli-dist/commands/aliases.js";
+
+const ALIAS_RESERVED_COMMANDS = new Set([
+  "setup",
+  "uninstall",
+  "help",
+  "--help",
+  "-h",
+]);
+
+const HELP_EXTRAS = [
+  {
+    group: "setup-admin",
+    name: "setup",
+    summary: "Install Flywheel CLI + MCP + skills.",
+  },
+  {
+    group: "setup-admin",
+    name: "uninstall",
+    summary: "Uninstall Flywheel artifacts.",
+  },
+];
+
+function helpExtrasArg() {
+  return `--_help_extras=${JSON.stringify(HELP_EXTRAS)}`;
+}
+
+function renderAliasesHelp() {
+  const lines = Object.entries(RUNTIME_ALIASES).map(
+    ([aliasCommand, canonicalCommand]) =>
+      `  ${aliasCommand} → ${canonicalCommand}`,
+  );
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+function stripFormatTokens(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith("--format=")) continue;
+    if (token === "--format") {
+      i += 1;
+      continue;
+    }
+    out.push(token);
+  }
+  return out;
+}
+
+/**
+ * Detect a top-level help invocation.
+ *
+ * The first token must be `help`, `--help`, or `-h` (or argv must be empty).
+ * Format tokens may follow — `flywheel help --format=json` and
+ * `flywheel --help --format=json` are help invocations — but format tokens
+ * are never a help signal on their own. Misordered inputs like
+ * `flywheel --format=json help` fall through to the dispatcher, which
+ * surfaces `unknown command: --format=json` with a non-zero exit and keeps
+ * scripts that forget the command token noisy instead of silently mapping
+ * to help.
+ *
+ * `--help <anything>` still matches (matches pre-refactor behaviour); the
+ * runtime ignores the trailing positional and emits top-level help.
+ */
+function isCombinedHelpRequest(argv) {
+  if (argv.length === 0) return true;
+  if (argv[0] === "--help" || argv[0] === "-h") return true;
+  if (argv[0] !== "help") return false;
+  const remainder = stripFormatTokens(argv.slice(1));
+  return remainder.length === 0;
+}
+
+async function routeExplicitHelp(argv) {
+  const [, target] = argv;
+  if (target === "--aliases" || target === "-a") {
+    renderAliasesHelp();
+    return;
+  }
+  if (target === "setup" || target === "uninstall") {
+    await runSetupCli(["node", "flywheel", target, "--help"]);
+    return;
+  }
+  if (target === undefined) {
+    // Defensive: `isCombinedHelpRequest` normally catches this path first,
+    // but keep the fallback so any accidental routing still surfaces the
+    // grouped help + extras instead of a blank runtime call.
+    const exitCode = await runRuntimeCli(["help", helpExtrasArg()]);
+    process.exitCode = exitCode;
+    return;
+  }
+  const resolvedArgv =
+    typeof target === "string" &&
+    Object.prototype.hasOwnProperty.call(RUNTIME_ALIASES, target)
+      ? ["help", RUNTIME_ALIASES[target], ...argv.slice(2)]
+      : argv;
+  const exitCode = await runRuntimeCli(resolvedArgv);
+  process.exitCode = exitCode;
+}
+
+export async function runUnifiedCli(argv = process.argv.slice(2)) {
+  if (!Array.isArray(argv)) {
+    throw new Error("runUnifiedCli expects an argv array.");
+  }
+
+  if (isCombinedHelpRequest(argv)) {
+    // Preserve any --format token verbatim so the runtime's format validator
+    // runs and rejects unsupported values (e.g. `--format=badvalue`) with the
+    // stable usage error instead of silently falling back to text. Order
+    // matters: `--_help_extras=…` is inserted *before* the user's `--format`
+    // tokens so a dangling `--format` (no value) cannot swallow the internal
+    // extras payload as its value and leak it into the `invalid --format=…`
+    // diagnostic.
+    const formatArgs = [];
+    for (let i = 0; i < argv.length; i += 1) {
+      const token = argv[i];
+      if (token.startsWith("--format=")) {
+        formatArgs.push(token);
+      } else if (token === "--format") {
+        formatArgs.push(token);
+        if (i + 1 < argv.length) {
+          formatArgs.push(argv[i + 1]);
+          i += 1;
+        }
+      }
+    }
+    const passthrough = ["help", helpExtrasArg(), ...formatArgs];
+    const exitCode = await runRuntimeCli(passthrough);
+    process.exitCode = exitCode;
+    return;
+  }
+
+  if (
+    argv.length > 0 &&
+    !ALIAS_RESERVED_COMMANDS.has(argv[0]) &&
+    Object.prototype.hasOwnProperty.call(RUNTIME_ALIASES, argv[0])
+  ) {
+    argv = [RUNTIME_ALIASES[argv[0]], ...argv.slice(1)];
+  }
+
+  const [command] = argv;
+  if (command === "help") {
+    await routeExplicitHelp(argv);
+    return;
+  }
+
+  if (command === "setup" || command === "uninstall") {
+    await runSetupCli(["node", "flywheel", ...argv]);
+    return;
+  }
+
+  if (command.includes(":")) {
+    const exitCode = await runRuntimeCli(argv);
+    process.exitCode = exitCode;
+    return;
+  }
+
+  process.stderr.write(`unknown command: ${command}\n`);
+  process.exitCode = 1;
+}