@triflare/fx 1.0.3 → 2.0.0

package/src/cli/run.js

@@ -0,0 +1,248 @@
+/**
+ * CLI entrypoint: commander setup, global options, and top-level error
+ * handling.
+ */
+
+import process from "node:process";
+import { Command, CommanderError } from "commander";
+import { brandText } from "../brand.js";
+import { loadProduct } from "../product.js";
+import { registerCommands } from "./commands/index.js";
+import {
+  CliError,
+  EXIT,
+  UsageError,
+  errorToJson,
+  formatError,
+} from "./errors.js";
+import { createReporter } from "./reporter.js";
+import { createTheme } from "./theme.js";
+
+const USAGE_CODES = new Set([
+  "commander.unknownCommand",
+  "commander.unknownOption",
+  "commander.missingArgument",
+  "commander.optionMissingArgument",
+  "commander.invalidArgument",
+  "commander.excessArguments",
+]);
+
+function resolveColor(options = {}) {
+  if (options.color === false || options.color === "never") return "never";
+  if (options.color === "always") return "always";
+  return "auto";
+}
+
+/** Read the global flags needed before commander has parsed successfully. */
+function scanGlobalFlags(argv) {
+  const result = {
+    json: false,
+    quiet: false,
+    verbose: false,
+    color: "auto",
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--json") result.json = true;
+    else if (token === "-q" || token === "--quiet") result.quiet = true;
+    else if (token === "-v" || token === "--verbose") result.verbose = true;
+    else if (token === "--no-color") result.color = "never";
+    else if (token === "--color") result.color = argv[++i] ?? "auto";
+    else if (token.startsWith("--color="))
+      result.color = token.slice("--color=".length);
+  }
+  return result;
+}
+
+function commandFromArgv(argv, program) {
+  const names = new Set();
+  for (const command of program.commands)
+    for (const name of [command.name(), ...command.aliases()]) names.add(name);
+  for (const token of argv) if (names.has(token)) return token;
+  return null;
+}
+
+function styleUsage(text, theme) {
+  return text
+    .split(" ")
+    .map((word) => {
+      if (word === "[options]") return theme.option(word);
+      if (word === "[command]") return theme.command(word);
+      if (word.startsWith("[") || word.startsWith("<"))
+        return theme.argument(word);
+      return theme.command(word);
+    })
+    .join(" ");
+}
+
+function styleOptionTerm(text, theme) {
+  return text
+    .split(" ")
+    .map((word) =>
+      word.startsWith("<") || word.startsWith("[")
+        ? theme.argument(word)
+        : theme.option(word),
+    )
+    .join(" ");
+}
+
+function styleSubcommandTerm(text, theme) {
+  return text
+    .split(" ")
+    .map((word) => {
+      if (word === "[options]") return theme.option(word);
+      if (word.startsWith("[") || word.startsWith("<"))
+        return theme.argument(word);
+      return theme.command(word);
+    })
+    .join(" ");
+}
+
+function createProgram(product, theme, color) {
+  const program = new Command();
+  program
+    .name(product.command)
+    .description(product.tagline)
+    .version(
+      `${product.name} ${product.version}`,
+      "-V, --version",
+      "Print the version",
+    )
+    .helpOption("-h, --help", "Show help")
+    .helpCommand("help [command]", "Show help for a command")
+    .showSuggestionAfterError(true)
+    .configureHelp({
+      sortCommands: false,
+      sortOptions: false,
+      showGlobalOptions: true,
+      styleTitle: (text) => theme.heading(text),
+      styleUsage: (text) => styleUsage(text, theme),
+      styleCommandText: (text) => theme.command(text),
+      styleSubcommandText: (text) => theme.command(text),
+      styleOptionText: (text) => theme.option(text),
+      styleArgumentText: (text) => theme.argument(text),
+      styleCommandDescription: (text) => theme.muted(text),
+      styleOptionDescription: (text) => theme.muted(text),
+      styleSubcommandDescription: (text) => theme.muted(text),
+      styleArgumentDescription: (text) => theme.muted(text),
+      styleOptionTerm: (text) => styleOptionTerm(text, theme),
+      styleSubcommandTerm: (text) => styleSubcommandTerm(text, theme),
+      styleArgumentTerm: (text) => theme.argument(text),
+    })
+    .optionsGroup("Global Options:")
+    .option("-v, --verbose", "Show timings, stack traces, and extra detail")
+    .option("--json", "Emit machine-readable JSON")
+    .option("-q, --quiet", "Suppress success and informational output")
+    .option("--color <mode>", "Color output: auto, always, or never", "auto")
+    .option("--no-color", "Disable color output")
+    .option("--cwd <dir>", "Run as if started in <dir>")
+    .option("--config <file>", "Use a specific config file")
+    .option("--no-config", "Ignore the project config file")
+    .option("--no-input", "Never prompt for input")
+    .option("-y, --yes", "Accept defaults and confirm destructive actions")
+    .option(
+      "--no-upgrade-prompt",
+      "Do not offer to migrate project.extensions",
+    );
+
+  program.addHelpText(
+    "before",
+    `\n  ${brandText(product.name, process.stdout, {
+      force: color === "always",
+    })} ${theme.muted(product.version)}\n  ${theme.muted(product.tagline)}\n`,
+  );
+  program.addHelpText(
+    "after",
+    `\n  ${theme.accent("↳")} Run ${theme.command(
+      `${product.command} <command> --help`,
+    )} for command details.\n`,
+  );
+
+  return program;
+}
+
+/**
+ * Run the CLI and return an exit code instead of terminating the process.
+ *
+ * @param {string[]} [argv]
+ * @returns {Promise<number>}
+ */
+export async function run(argv = process.argv.slice(2)) {
+  const product = loadProduct();
+  const raw = scanGlobalFlags(argv);
+  const color = resolveColor(raw);
+  const theme = createTheme({ product, color, stream: process.stdout });
+  const reporter = createReporter({
+    product,
+    json: raw.json,
+    quiet: raw.quiet,
+    verbose: raw.verbose,
+    color,
+  });
+  const state = { exitCode: EXIT.OK, command: null };
+  const program = createProgram(product, theme, color);
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: (text) => process.stdout.write(text),
+    writeErr: (text) => process.stderr.write(text),
+    getOutHasColors: () => theme.enabled,
+    getErrHasColors: () => theme.enabled,
+    // Keep commander's usage text out of the stream; run() renders one
+    // consistent diagnostic (or JSON document) below.
+    outputError: () => {},
+  });
+
+  registerCommands(program, { state, product });
+  // With no command, print help to stdout instead of commander's stderr usage.
+  program.action(() => program.outputHelp());
+
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return state.exitCode;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (
+        error.code === "commander.helpDisplayed" ||
+        error.code === "commander.help" ||
+        error.code === "commander.version"
+      )
+        return EXIT.OK;
+
+      const usage = new UsageError(error.message.replace(/^error:\s*/, ""), {
+        code: USAGE_CODES.has(error.code) ? "USAGE_ERROR" : "COMMANDER_ERROR",
+        hint: `run "${product.command} help" for usage`,
+      });
+      usage.command = state.command ?? commandFromArgv(argv, program);
+      usage.warnings = [];
+      return reportError(usage, reporter);
+    }
+
+    if (error && typeof error === "object") {
+      error.warnings ??= [];
+      error.command ??= state.command ?? commandFromArgv(argv, program);
+    }
+    return reportError(error, reporter);
+  }
+}
+
+function reportError(error, reporter) {
+  const exitCode = error instanceof CliError ? error.exitCode : EXIT.FAILURE;
+  const command = error?.command ?? null;
+
+  if (reporter.json) {
+    reporter.document({
+      schemaVersion: 1,
+      command,
+      ok: false,
+      warnings: error?.warnings ?? [],
+      error: errorToJson(error),
+    });
+    return exitCode;
+  }
+
+  if (error instanceof CliError && error.silent) return exitCode;
+
+  reporter.error(formatError(error, { verbose: reporter.verbose }));
+  if (error instanceof CliError && error.hint) reporter.hint(error.hint);
+  return exitCode;
+}

package/src/cli/templates/index.js

@@ -0,0 +1,112 @@
+/**
+ * Scaffolding templates used by `fx init`.
+ */
+
+import {
+  configFilename,
+  sourceDirectory,
+  sourceExtension,
+} from "../../brand.js";
+
+const CAT_ASSET = `<svg xmlns="http://www.w3.org/2000/svg" width="95" height="101" viewBox="0 0 95 101">
+  <ellipse cx="47" cy="60" rx="35" ry="35" fill="#ffab19" stroke="#cf8b17" stroke-width="4"/>
+  <circle cx="35" cy="50" r="6" fill="#000"/>
+  <circle cx="60" cy="50" r="6" fill="#000"/>
+</svg>
+`;
+
+function configText({ name, width, height, target }) {
+  const lines = [
+    "project:",
+    `  name: ${JSON.stringify(name)}`,
+    "  fps: 60",
+    `  width: ${width}`,
+    `  height: ${height}`,
+    "  turbo: false",
+    "  interpolation: true",
+    "fx:",
+    "  partialSprites: false",
+  ];
+  if (target !== "none") {
+    lines.push("package:", `  target: ${target}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+const CAT_SOURCE = `sprite "Cat" {
+    costumes: {
+        cat: "../assets/cat.svg"
+    };
+
+    let score = 0;
+
+    when greenFlag {
+        motion.goToXY(0, 0);
+        control.forever {
+            motion.turnRight(1);
+        }
+    }
+
+    when keyPressed("space") {
+        score += 1;
+        looks.sayForSecs(operators.join("Score: ", score), 1);
+    }
+}
+`;
+
+const EMPTY_SOURCE = `// Your project starts here.
+when greenFlag {
+    looks.say("Hello, world!");
+}
+`;
+
+const BLANK_SOURCE = `// Your project starts here.
+`;
+
+/**
+ * Build the file map for an init run.
+ *
+ * @param {{
+ *   product: object,
+ *   name: string,
+ *   template: "cat"|"empty"|"blank",
+ *   width: number,
+ *   height: number,
+ *   target: string,
+ * }} options
+ */
+export function initFiles({ product, name, template, width, height, target }) {
+  const files = {
+    [configFilename(product)]: configText({ name, width, height, target }),
+    [`${sourceDirectory(product)}/main${sourceExtension(product)}`]:
+      template === "cat"
+        ? CAT_SOURCE
+        : template === "empty"
+          ? EMPTY_SOURCE
+          : BLANK_SOURCE,
+  };
+  if (template === "cat") files["assets/cat.svg"] = CAT_ASSET;
+  return files;
+}
+
+export const TEMPLATES = [
+  {
+    value: "cat",
+    label: "Cat demo",
+    hint: "sprite, costumes, events, variables",
+  },
+  { value: "empty", label: "Empty project", hint: "one green-flag script" },
+  { value: "blank", label: "Blank", hint: "just the config and a source file" },
+];
+
+export const TARGETS = [
+  { value: "none", label: "None", hint: "source only" },
+  { value: "html", label: "HTML", hint: "single-file web build" },
+  { value: "zip", label: "ZIP", hint: "packaged archive" },
+];
+
+export const STAGE_SIZES = [
+  { value: "480x360", label: "480 × 360", hint: "Scratch default" },
+  { value: "640x360", label: "640 × 360", hint: "wide" },
+  { value: "1920x1080", label: "1920 × 1080", hint: "full HD" },
+];

package/src/cli/theme.js

@@ -0,0 +1,84 @@
+/**
+ * Terminal theme shared by help output and the reporter.
+ *
+ * Colors are derived from the product palette so a rebrand reaches the CLI
+ * too. Everything falls back to plain text when the stream cannot show color.
+ */
+
+import { styleText } from "node:util";
+import { brandingColors } from "../brand.js";
+
+const STATUS_COLORS = {
+  success: "#34D399",
+  warning: "#FBBF24",
+  danger: "#F87171",
+};
+
+function rgb(hex) {
+  const digits =
+    hex.length === 4 ? hex.slice(1).replace(/./g, "$&$&") : hex.slice(1);
+  return digits.match(/../g).map((part) => parseInt(part, 16));
+}
+
+function mix(from, to, amount) {
+  const [r1, g1, b1] = rgb(from);
+  const [r2, g2, b2] = rgb(to);
+  const channel = (a, b) => Math.round(a + (b - a) * amount);
+  return [channel(r1, r2), channel(g1, g2), channel(b1, b2)];
+}
+
+function supportsColor(stream) {
+  if (!stream?.isTTY) return false;
+  if (process.env.NO_COLOR) return false;
+  if (process.env.TERM === "dumb") return false;
+  return styleText("red", "x", { stream }).includes("\x1b");
+}
+
+/**
+ * @param {{ product?: object, color?: "auto"|"always"|"never", stream?: NodeJS.WriteStream }} [options]
+ */
+export function createTheme({
+  product,
+  color = "auto",
+  stream = process.stdout,
+} = {}) {
+  const palette = brandingColors(product);
+  const enabled =
+    color === "always" || (color !== "never" && supportsColor(stream));
+
+  const paint = (text, codes) => {
+    if (!enabled || codes.length === 0) return String(text);
+    return `\x1b[${codes.join(";")}m${text}\x1b[0m`;
+  };
+
+  const foreground = (colorValue) => {
+    const [r, g, b] = Array.isArray(colorValue) ? colorValue : rgb(colorValue);
+    return `38;2;${r};${g};${b}`;
+  };
+
+  const command = mix(palette.primary, "#FFFFFF", 0.35);
+  const heading = mix(palette.primary, "#FFFFFF", 0.2);
+  const option = mix(palette.primary, "#FFFFFF", 0.58);
+  const argument = mix(palette.primary, "#FFFFFF", 0.74);
+
+  return {
+    enabled,
+    stream,
+
+    accent: (text) => paint(text, [foreground(palette.primary)]),
+    command: (text) => paint(text, ["1", foreground(command)]),
+    heading: (text) => paint(text, ["1", foreground(heading)]),
+    option: (text) => paint(text, [foreground(option)]),
+    argument: (text) => paint(text, [foreground(argument)]),
+    muted: (text) => paint(text, ["2"]),
+    bold: (text) => paint(text, ["1"]),
+    success: (text) => paint(text, [foreground(STATUS_COLORS.success)]),
+    warning: (text) => paint(text, [foreground(STATUS_COLORS.warning)]),
+    danger: (text) => paint(text, [foreground(STATUS_COLORS.danger)]),
+
+    tone(name, text) {
+      const value = STATUS_COLORS[name] ?? palette.primary;
+      return paint(text, [foreground(value)]);
+    },
+  };
+}