@paradigma-inc/flywheel 0.1.143 → 0.1.147

package/src/unified-cli.mjs

@@ -1,9 +1,9 @@
 import { runCli as runSetupCli } from "./cli.mjs";
 import {
-  helpExtrasArg,
-  loadPackageVersion,
-  usageExtrasArg,
-  usageVersionArg,
+ helpExtrasArg,
+ loadPackageVersion,
+ usageExtrasArg,
+ usageVersionArg,
 } from "./public-command-metadata.mjs";
 import { runRuntimeCli } from "./runtime/delegate.mjs";
 import { RUNTIME_ALIASES } from "./runtime/vendor/flywheel-cli-dist/commands/aliases.js";
@@ -12,52 +12,52 @@ import { runUpdateCommand } from "./update/command.mjs";
 import { runCommandWithDeferredUpdateWarning } from "./update/warning.mjs";
 
 const ALIAS_RESERVED_COMMANDS = new Set([
-  "setup",
-  "update",
-  "uninstall",
-  "completion",
-  "help",
-  "--help",
-  "-h",
-  "--usage",
-  "--usage-spec",
+ "setup",
+ "update",
+ "uninstall",
+ "completion",
+ "help",
+ "--help",
+ "-h",
+ "--usage",
+ "--usage-spec",
 ]);
 const VERSION_REQUEST_TOKENS = new Set(["--version", "-v", "version"]);
 const USAGE_REQUEST_TOKENS = new Set(["--usage", "--usage-spec"]);
 const COMPLETION_HELP_SUBCOMMANDS = new Set(["install", "uninstall"]);
 
 function renderAliasesHelp() {
-  const lines = Object.entries(RUNTIME_ALIASES).map(
-    ([aliasCommand, canonicalCommand]) =>
-      `  ${aliasCommand} → ${canonicalCommand}`,
-  );
-  process.stdout.write(`${lines.join("\n")}\n`);
+ 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;
+function stripHelpOptionTokens(argv) {
+ const out = [];
+ for (let i = 0; i < argv.length; i += 1) {
+  const token = argv[i];
+  if (token.startsWith("--format=") || token.startsWith("--env=")) continue;
+  if (token === "--format" || token === "--env") {
+   i += 1;
+   continue;
+  }
+  out.push(token);
+ }
+ return out;
 }
 
 function isVersionRequest(argv) {
-  return argv.length === 1 && VERSION_REQUEST_TOKENS.has(argv[0]);
+ return argv.length === 1 && VERSION_REQUEST_TOKENS.has(argv[0]);
 }
 
 /**
  * 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
+ * Format and environment tokens may follow — `flywheel help --env=research`
+ * and `flywheel --help --format=json` are help invocations — but options
  * 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
@@ -68,189 +68,185 @@ function isVersionRequest(argv) {
  * 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;
+ if (argv.length === 0) return true;
+ if (argv[0] === "--help" || argv[0] === "-h") return true;
+ if (argv[0] !== "help") return false;
+ const remainder = stripHelpOptionTokens(argv.slice(1));
+ return remainder.length === 0;
 }
 
 function setupHelpArgvFor(target, subcommand) {
-  if (target === "setup" || target === "uninstall") {
-    return [target, "--help"];
-  }
+ if (target === "setup" || target === "uninstall") {
+  return [target, "--help"];
+ }
 
-  if (target === "completion") {
-    if (COMPLETION_HELP_SUBCOMMANDS.has(subcommand)) {
-      return ["completion", subcommand, "--help"];
-    }
-    return ["completion", "--help"];
+ if (target === "completion") {
+  if (COMPLETION_HELP_SUBCOMMANDS.has(subcommand)) {
+   return ["completion", subcommand, "--help"];
   }
+  return ["completion", "--help"];
+ }
 
-  for (const nestedSubcommand of COMPLETION_HELP_SUBCOMMANDS) {
-    if (target === `completion ${nestedSubcommand}`) {
-      return ["completion", nestedSubcommand, "--help"];
-    }
+ for (const nestedSubcommand of COMPLETION_HELP_SUBCOMMANDS) {
+  if (target === `completion ${nestedSubcommand}`) {
+   return ["completion", nestedSubcommand, "--help"];
   }
+ }
 
-  return null;
+ return null;
 }
 
 async function routeExplicitHelp(argv, { runSetup, runRuntime }) {
-  const [, target, subcommand] = argv;
-  if (target === "--aliases" || target === "-a") {
-    renderAliasesHelp();
-    return;
-  }
-  const setupHelpArgv = setupHelpArgvFor(target, subcommand);
-  if (setupHelpArgv) {
-    process.exitCode = await runSetup(["node", "flywheel", ...setupHelpArgv], {
-      exitOverride: true,
-    });
-    return;
-  }
-  if (target === "update") {
-    process.exitCode = await runUpdateCommand(["--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 runRuntime(["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 runRuntime(resolvedArgv);
+ const [, target, subcommand] = argv;
+ if (target === "--aliases" || target === "-a") {
+  renderAliasesHelp();
+  return;
+ }
+ const setupHelpArgv = setupHelpArgvFor(target, subcommand);
+ if (setupHelpArgv) {
+  process.exitCode = await runSetup(["node", "flywheel", ...setupHelpArgv], {
+   exitOverride: true,
+  });
+  return;
+ }
+ if (target === "update") {
+  process.exitCode = await runUpdateCommand(["--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 runRuntime(["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 runRuntime(resolvedArgv);
+ process.exitCode = exitCode;
 }
 
 async function runWithDeferredUpdateWarning(argv, runCommand) {
-  const exitCode = await runCommandWithDeferredUpdateWarning({
-    argv,
-    currentVersion: await loadPackageVersion(),
-    runCommand,
-  });
-  if (Number.isInteger(exitCode)) {
-    process.exitCode = exitCode;
-  }
+ const exitCode = await runCommandWithDeferredUpdateWarning({
+  argv,
+  currentVersion: await loadPackageVersion(),
+  runCommand,
+ });
+ if (Number.isInteger(exitCode)) {
+  process.exitCode = exitCode;
+ }
 }
 
 export async function runUnifiedCli(
-  argv = process.argv.slice(2),
-  dependencies = {},
+ argv = process.argv.slice(2),
+ dependencies = {},
 ) {
-  if (!Array.isArray(argv)) {
-    throw new Error("runUnifiedCli expects an argv array.");
-  }
-  const runSetup = dependencies.runSetupCli ?? runSetupCli;
-  const runtimeDependencies = dependencies.runtimeDependencies ?? {};
-  const runRuntime = (runtimeArgv) =>
-    (dependencies.runRuntimeCli ?? runRuntimeCli)(
-      runtimeArgv,
-      runtimeDependencies,
-    );
-
-  if (isVersionRequest(argv)) {
-    process.stdout.write(`${await loadPackageVersion()}\n`);
-    process.exitCode = 0;
-    return;
-  }
+ if (!Array.isArray(argv)) {
+  throw new Error("runUnifiedCli expects an argv array.");
+ }
+ const runSetup = dependencies.runSetupCli ?? runSetupCli;
+ const runtimeDependencies = dependencies.runtimeDependencies ?? {};
+ const runRuntime = (runtimeArgv) =>
+  (dependencies.runRuntimeCli ?? runRuntimeCli)(
+   runtimeArgv,
+   runtimeDependencies,
+  );
 
-  if (argv.length === 1 && USAGE_REQUEST_TOKENS.has(argv[0])) {
-    await runWithDeferredUpdateWarning(argv, async () => {
-      const publicPackageVersion = await loadPackageVersion();
-      return await runRuntime([
-        argv[0],
-        usageExtrasArg(),
-        usageVersionArg(publicPackageVersion),
-      ]);
-    });
-    return;
-  }
+ if (isVersionRequest(argv)) {
+  process.stdout.write(`${await loadPackageVersion()}\n`);
+  process.exitCode = 0;
+  return;
+ }
 
-  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;
-        }
-      }
+ if (argv.length === 1 && USAGE_REQUEST_TOKENS.has(argv[0])) {
+  await runWithDeferredUpdateWarning(argv, async () => {
+   const publicPackageVersion = await loadPackageVersion();
+   return await runRuntime([
+    argv[0],
+    usageExtrasArg(),
+    usageVersionArg(publicPackageVersion),
+   ]);
+  });
+  return;
+ }
+
+ if (isCombinedHelpRequest(argv)) {
+  // Preserve output validation and the selected credential/server profile.
+  // Put internal extras before user flags so a missing flag value cannot
+  // consume and expose the internal payload in an error.
+  const helpArgs = [];
+  for (let i = 0; i < argv.length; i += 1) {
+   const token = argv[i];
+   if (token.startsWith("--format=") || token.startsWith("--env=")) {
+    helpArgs.push(token);
+   } else if (token === "--format" || token === "--env") {
+    helpArgs.push(token);
+    if (i + 1 < argv.length) {
+     helpArgs.push(argv[i + 1]);
+     i += 1;
     }
-    const passthrough = ["help", helpExtrasArg(), ...formatArgs];
-    await runWithDeferredUpdateWarning(
-      argv,
-      async () => await runRuntime(passthrough),
-    );
-    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 === "update") {
-    process.exitCode = await runUpdateCommand(argv.slice(1));
-    return;
-  }
-
-  if (command === "help") {
-    await runWithDeferredUpdateWarning(argv, async () => {
-      await routeExplicitHelp(argv, { runSetup, runRuntime });
-      return process.exitCode ?? 0;
-    });
-    return;
-  }
-
-  if (
-    command === "setup" ||
-    command === "uninstall" ||
-    command === "completion"
-  ) {
-    await runWithDeferredUpdateWarning(argv, async () => {
-      return await runSetup(["node", "flywheel", ...argv], {
-        exitOverride: true,
-      });
-    });
-    return;
-  }
-
-  if (
-    command.includes(":") ||
-    Object.prototype.hasOwnProperty.call(RETIRED_COMMAND_NAMES, command)
-  ) {
-    await runWithDeferredUpdateWarning(
-      argv,
-      async () => await runRuntime(argv),
-    );
-    return;
-  }
-
+  const passthrough = ["help", helpExtrasArg(), ...helpArgs];
+  await runWithDeferredUpdateWarning(
+   argv,
+   async () => await runRuntime(passthrough),
+  );
+  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 === "update") {
+  process.exitCode = await runUpdateCommand(argv.slice(1));
+  return;
+ }
+
+ if (command === "help") {
   await runWithDeferredUpdateWarning(argv, async () => {
-    process.stderr.write(`unknown command: ${command}\n`);
-    return 1;
+   await routeExplicitHelp(argv, { runSetup, runRuntime });
+   return process.exitCode ?? 0;
   });
+  return;
+ }
+
+ if (
+  command === "setup" ||
+  command === "uninstall" ||
+  command === "completion"
+ ) {
+  await runWithDeferredUpdateWarning(argv, async () => {
+   return await runSetup(["node", "flywheel", ...argv], {
+    exitOverride: true,
+   });
+  });
+  return;
+ }
+
+ if (
+  command.includes(":") ||
+  Object.prototype.hasOwnProperty.call(RETIRED_COMMAND_NAMES, command)
+ ) {
+  await runWithDeferredUpdateWarning(
+   argv,
+   async () => await runRuntime(argv),
+  );
+  return;
+ }
+
+ await runWithDeferredUpdateWarning(argv, async () => {
+  process.stderr.write(`unknown command: ${command}\n`);
+  return 1;
+ });
 }