@sous-io/sous 0.1.0 → 0.2.0

package/src/utils/choice-prompt.ts

@@ -0,0 +1,143 @@
+/**
+ * The pick-one question sous asks for a recipe variable with a fixed set of
+ * allowed values.
+ *
+ * It behaves like the stock `select` prompt (arrow keys to move, Enter to
+ * choose, the default preselected) with the one addition every sous question
+ * shares: Tab resolves the question with `{ kind: "advanced" }` instead of
+ * moving the cursor, so the caller can show the advanced view and then ask the
+ * same question again. Built on the public `@inquirer/core` hooks only.
+ */
+
+import {
+  createPrompt,
+  isDownKey,
+  isEnterKey,
+  isTabKey,
+  isUpKey,
+  useKeypress,
+  usePrefix,
+  useState,
+  type Status,
+} from "@inquirer/core";
+import { promptBottom } from "./formatting.js";
+
+/** One value the question offers, and how it is written on screen. */
+export interface PromptChoice {
+  /** The line shown in the list. */
+  name: string;
+  /** The value handed back when the line is chosen. */
+  value: string;
+}
+
+/** What the pick-one question needs in order to ask itself. */
+export interface ChoicePromptConfig {
+  /** The one-line question. */
+  message: string;
+  /** The values on offer, in the order they are listed. */
+  choices: PromptChoice[];
+  /** The value that starts out highlighted, so Enter alone accepts it. */
+  default?: string;
+  /** A line under the list: the key legend, in the stock prompts' style. */
+  hint?: string;
+}
+
+/** How the question ended: with a choice, or with a request for the advanced view. */
+export type ChoicePromptResult = { kind: "value"; value: string } | { kind: "advanced" };
+
+/** Everything the renderer draws, so it can be tested without a terminal. */
+export interface ChoicePromptView {
+  /** The prompt prefix (the question mark, or the check mark once answered). */
+  prefix: string;
+  /** The one-line question. */
+  message: string;
+  /** The values on offer, in the order they are listed. */
+  choices: PromptChoice[];
+  /** Which choice is highlighted, counting from zero. */
+  active: number;
+  /** A line under the list: the key legend, in the stock prompts' style. */
+  hint?: string;
+  /** Whether the question has been answered, which replaces the list with the answer. */
+  answered?: boolean;
+}
+
+/** The pointer drawn beside the highlighted choice. */
+const POINTER = ">";
+
+/**
+ * Draws the question: prefix and message on the first line, then one line per
+ * choice with a pointer beside the highlighted one, and the hint underneath.
+ * Once the question is answered the list gives way to the chosen value, so the
+ * scrollback keeps one tidy line per question.
+ *
+ * @param view - The prompt's state.
+ * @returns The question line and the block under it.
+ */
+export function renderChoicePrompt(view: ChoicePromptView): [string, string] {
+  const chosen = view.choices[view.active];
+
+  if (view.answered === true) {
+    return [`${view.prefix} ${view.message}: ${chosen?.name ?? ""}`.trimEnd(), ""];
+  }
+
+  const lines = view.choices.map(
+    (choice, index) => `${index === view.active ? POINTER : " "} ${choice.name}`
+  );
+  if (view.hint !== undefined && view.hint !== "") lines.push(view.hint);
+
+  return [`${view.prefix} ${view.message}`.trimEnd(), promptBottom(lines.join("\n"))];
+}
+
+/** Asks one pick-one question, with Tab bound to the advanced view. */
+export const choicePrompt = createPrompt<ChoicePromptResult, ChoicePromptConfig>(
+  (config, done) => {
+    const [status, setStatus] = useState<Status>("idle");
+    const [answered, setAnswered] = useState(false);
+    const [active, setActive] = useState(
+      Math.max(
+        0,
+        config.choices.findIndex((choice) => choice.value === config.default)
+      )
+    );
+    const prefix = usePrefix({ status });
+
+    useKeypress((key, rl) => {
+      if (status !== "idle") return;
+      // Readline echoes whatever was pressed into its buffer; take it back out.
+      rl.clearLine(0);
+
+      if (isTabKey(key)) {
+        setStatus("done");
+        done({ kind: "advanced" });
+        return;
+      }
+
+      if (isEnterKey(key)) {
+        const chosen = config.choices[active];
+        if (chosen === undefined) return;
+        setAnswered(true);
+        setStatus("done");
+        done({ kind: "value", value: chosen.value });
+        return;
+      }
+
+      if (isUpKey(key)) {
+        setActive((active - 1 + config.choices.length) % config.choices.length);
+        return;
+      }
+
+      if (isDownKey(key)) {
+        setActive((active + 1) % config.choices.length);
+      }
+    });
+
+    return renderChoicePrompt({
+      prefix,
+      message: config.message,
+      choices: config.choices,
+      active,
+      ...(config.hint === undefined ? {} : { hint: config.hint }),
+      ...(answered ? { answered: true } : {}),
+    });
+  }
+);

package/src/utils/command-errors.ts

@@ -0,0 +1,186 @@
+/**
+ * One way for every sous command to report a failure.
+ *
+ * A person who forgets an argument, misspells a flag, or runs sous where there
+ * is no config has made an ordinary mistake, and what they need back is the
+ * sentence describing it (plus, when the mistake is a usage one, the command's
+ * own help). A stack trace pointing into oclif's parser tells them nothing, so
+ * no expected failure prints one. A trace is still one environment variable
+ * away: set `SOUS_DEBUG` and every reported error prints its stack to stderr.
+ *
+ * The same reporting is used by every command. `BaseCommand.catch` calls it for
+ * the commands that discover a config; the repository authoring commands
+ * (`repo init`, `repo release`, `repo submit`) extend oclif's `Command`
+ * directly and call it from their own `catch`, so all of sous fails the same
+ * way.
+ */
+
+import { Errors, type Command } from "@oclif/core";
+import { isConfigError } from "../lib/errors.js";
+import { wantsHelp } from "../lib/interactive.js";
+import { displayErrorBlock, log } from "./formatting.js";
+import { printCommandHelpToStderr } from "./command-help.js";
+
+/** The environment variable that turns stack traces back on. */
+export const DEBUG_ENV_VAR = "SOUS_DEBUG";
+
+/**
+ * Values of `SOUS_DEBUG` that mean "not set". Everything else counts as set,
+ * because people spell it `1`, `true` and `yes` in roughly equal measure. The
+ * same list gates the `CI` variable in `lib/interactive.ts`.
+ */
+const FALSY_DEBUG_VALUES = new Set(["", "0", "false", "no", "off"]);
+
+/** The line oclif appends to a parse error, replaced by the help screen itself. */
+const OCLIF_HELP_HINT = "See more help with --help";
+
+/** The sentence an unexpected failure ends with, since sous cannot explain it. */
+const UNEXPECTED_REMEDY = `Sous did not expect this error; set '${DEBUG_ENV_VAR}=1' and run the command again for the full stack trace.`;
+
+/** Where the report is written, and what it reads to decide about traces. */
+export type ErrorReportOptions = {
+  /**
+   * Line sink for the error text. Defaults to stdout via `log`; commands whose
+   * stdout must stay machine-readable pass a stderr writer.
+   */
+  write?: (line: string) => void;
+  /** The environment, read for `SOUS_DEBUG`. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+};
+
+/**
+ * True when this run was asked for stack traces, either by `SOUS_DEBUG` or by
+ * oclif's own debug setting (which `--debug`-style bootstrapping turns on).
+ *
+ * @param env - The environment to read. Defaults to the real one.
+ */
+export function stackTracesRequested(env: NodeJS.ProcessEnv = process.env): boolean {
+  const oclifDebug = (globalThis as { oclif?: { debug?: boolean } }).oclif?.debug;
+  if (oclifDebug === true) return true;
+
+  const raw = env[DEBUG_ENV_VAR];
+  if (raw === undefined) return false;
+  return !FALSY_DEBUG_VALUES.has(raw.trim().toLowerCase());
+}
+
+/**
+ * True when the "error" is only a request to end the process, which every
+ * `this.exit(code)` raises. It carries no message and must reach oclif
+ * untouched, or a clean exit would be reported as a failure.
+ *
+ * @param error - The thrown value.
+ */
+export function isExitSignal(error: unknown): boolean {
+  if (error instanceof Errors.ExitError) return true;
+  return typeof error === "object" && error !== null && (error as { code?: string }).code === "EEXIT";
+}
+
+/**
+ * True when the caller got the command line wrong (a missing argument, an
+ * unknown flag, a value outside a flag's options) or asked a question sous
+ * could not ask. Both are answered by showing the command's own help, so both
+ * are treated the same way.
+ *
+ * oclif's parse errors all carry a `parse` property; nothing else oclif throws
+ * does, which is what separates a usage mistake from a reported failure.
+ *
+ * @param error - The thrown value.
+ */
+export function isUsageError(error: unknown): boolean {
+  if (wantsHelp(error)) return true;
+  return error instanceof Errors.CLIError && "parse" in error;
+}
+
+/**
+ * Reports one command failure in sous's own voice: the message, the command's
+ * help underneath it when the message alone is not enough, and a stack trace
+ * only when one was asked for.
+ *
+ * @param command - The command that failed, whose help may be drawn.
+ * @param error - The error it failed with.
+ * @param options - Where to write, and the environment to read.
+ * @returns The exit code the run should end with, or undefined when this error
+ *   is not sous's to report and must fall through to oclif's own handling.
+ */
+export async function reportCommandError(
+  command: Command,
+  error: Error & { exitCode?: number; oclif?: { exit?: number | false } },
+  options: ErrorReportOptions = {}
+): Promise<number | undefined> {
+  // A clean exit, and a command rendering its own JSON error, both belong to
+  // oclif; neither is a failure for sous to describe.
+  if (isExitSignal(error)) return undefined;
+  if (jsonRequested(command)) return undefined;
+
+  const write = options.write ?? log;
+  const showHelp = isUsageError(error);
+  const expected = showHelp || isConfigError(error) || error instanceof Errors.CLIError;
+
+  const body = [messageOf(error, showHelp)];
+  if (!expected) body.push("", UNEXPECTED_REMEDY);
+
+  displayErrorBlock(body.join("\n"), write);
+
+  if (stackTracesRequested(options.env ?? process.env)) writeStackToStderr(error);
+  if (showHelp) await printCommandHelpToStderr(command);
+
+  return exitCodeOf(error);
+}
+
+/**
+ * The message to print, with oclif's "See more help with --help" line removed
+ * when the help itself is about to be printed underneath it.
+ *
+ * @param error - The error being reported.
+ * @param showHelp - Whether the command's help follows the message.
+ */
+function messageOf(error: Error, showHelp: boolean): string {
+  const message = error.message?.trim() === "" ? String(error) : error.message;
+  if (!showHelp) return message;
+  return message
+    .split("\n")
+    .filter((line) => line.trim() !== OCLIF_HELP_HINT)
+    .join("\n")
+    .trimEnd();
+}
+
+/**
+ * Writes an error's stack to stderr, verbatim and uncolored. It is diagnostic
+ * output for whoever set `SOUS_DEBUG`, never part of what the command prints.
+ *
+ * @param error - The error whose stack to write.
+ */
+function writeStackToStderr(error: Error): void {
+  const stack = error.stack ?? "";
+  if (stack.trim() === "") return;
+  process.stderr.write(`${stack}\n`);
+}
+
+/**
+ * The exit code a failure ends with: the one oclif assigned when it assigned
+ * one (a parse error exits 2), and 1 for everything else.
+ *
+ * @param error - The error being reported.
+ */
+function exitCodeOf(error: Error & { exitCode?: number; oclif?: { exit?: number | false } }): number {
+  const fromOclif = error.oclif?.exit;
+  if (typeof fromOclif === "number" && Number.isInteger(fromOclif)) return fromOclif;
+  if (typeof error.exitCode === "number" && Number.isInteger(error.exitCode)) return error.exitCode;
+  return 1;
+}
+
+/**
+ * True when the command is rendering machine-readable JSON, in which case oclif
+ * owns the error output and sous must not print a human error over it.
+ *
+ * @param command - The command that failed.
+ */
+function jsonRequested(command: Command): boolean {
+  const enabled = (command as { jsonEnabled?: () => boolean }).jsonEnabled;
+  if (typeof enabled !== "function") return false;
+  try {
+    return enabled.call(command) === true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/command-help.ts

@@ -0,0 +1,45 @@
+/**
+ * Printing a command's own help underneath an error.
+ *
+ * A run that failed because a question could not be asked should show the
+ * caller every flag that would have answered it, without sending them off to
+ * `sous help <command>`. The same goes for a run that failed because the
+ * command line itself was wrong. `utils/command-errors.ts` decides when a
+ * failure earns a help screen; this module draws it, so every command in sous
+ * draws exactly the same one.
+ */
+
+import { loadHelpClass, type Command } from "@oclif/core";
+
+/**
+ * Prints one command's help, always to stderr.
+ *
+ * An error is not output, and a command whose stdout is being piped must not
+ * have a help screen spliced into its stream. oclif's help writes to stdout, so
+ * stdout is pointed at stderr for the duration and put back afterwards. The help
+ * class is the one oclif itself uses for `--help`, `-h` and the `help` command,
+ * so all four routes draw the same screen.
+ *
+ * Drawing the help is a courtesy: a failure to draw it must never replace the
+ * error that is actually being reported, so everything here is swallowed.
+ *
+ * @param command - The command whose help to draw.
+ */
+export async function printCommandHelpToStderr(command: Command): Promise<void> {
+  const writeToStdout = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk: string | Uint8Array, ...rest: unknown[]) =>
+    (process.stderr.write as (...args: unknown[]) => boolean)(
+      chunk,
+      ...rest
+    )) as typeof process.stdout.write;
+
+  try {
+    const HelpClass = await loadHelpClass(command.config);
+    const help = new HelpClass(command.config);
+    await help.showHelp([command.id ?? ""]);
+  } catch {
+    // The help screen is a courtesy; never let it replace the real error.
+  } finally {
+    process.stdout.write = writeToStdout;
+  }
+}

package/src/utils/confirm-prompt.ts

@@ -0,0 +1,110 @@
+/**
+ * The yes-or-no question sous asks for a recipe variable that holds a boolean.
+ *
+ * It behaves like the stock `confirm` prompt (the y and n keys answer it, Enter
+ * alone accepts the default, which is the capitalised letter) with the one
+ * addition every sous question shares: Tab resolves the question with
+ * `{ kind: "advanced" }`, so the caller can show the advanced view and then ask
+ * the same question again. Built on the public `@inquirer/core` hooks only.
+ */
+
+import {
+  createPrompt,
+  isEnterKey,
+  isTabKey,
+  useKeypress,
+  usePrefix,
+  useState,
+  type Status,
+} from "@inquirer/core";
+import { promptBottom } from "./formatting.js";
+
+/** What the yes-or-no question needs in order to ask itself. */
+export interface ConfirmPromptConfig {
+  /** The one-line question. */
+  message: string;
+  /** The answer Enter alone accepts. Defaults to yes. */
+  default?: boolean;
+  /** A line under the question: the key legend, in the stock prompts' style. */
+  hint?: string;
+}
+
+/** How the question ended: with an answer, or with a request for the advanced view. */
+export type ConfirmPromptResult = { kind: "value"; value: boolean } | { kind: "advanced" };
+
+/** Everything the renderer draws, so it can be tested without a terminal. */
+export interface ConfirmPromptView {
+  /** The prompt prefix (the question mark, or the check mark once answered). */
+  prefix: string;
+  /** The one-line question. */
+  message: string;
+  /** The answer Enter alone accepts. Defaults to yes. */
+  default?: boolean;
+  /** The answer given, once there is one. */
+  answer?: boolean;
+  /** A line under the question: the key legend, in the stock prompts' style. */
+  hint?: string;
+}
+
+/**
+ * Draws the question: prefix, message and the two keys with the default
+ * capitalised, replaced by the answer itself once one is given, plus the hint
+ * on the line underneath. A yes or no is never a secret, so nothing here is
+ * ever masked.
+ *
+ * @param view - The prompt's state.
+ * @returns The question line and the line under it.
+ */
+export function renderConfirmPrompt(view: ConfirmPromptView): [string, string] {
+  const fallback = view.default ?? true;
+  const keys = fallback ? "(Y/n)" : "(y/N)";
+  const tail = view.answer === undefined ? keys : view.answer ? "yes" : "no";
+  const line = `${view.prefix} ${view.message} ${tail}`.trimEnd();
+
+  if (view.answer !== undefined) return [line, ""];
+  return [line, promptBottom(view.hint ?? "")];
+}
+
+/** Asks one yes-or-no question, with Tab bound to the advanced view. */
+export const confirmPrompt = createPrompt<ConfirmPromptResult, ConfirmPromptConfig>(
+  (config, done) => {
+    const [status, setStatus] = useState<Status>("idle");
+    const [answer, setAnswer] = useState<boolean | undefined>(undefined);
+    const prefix = usePrefix({ status });
+
+    /** Settles the question with one answer, and draws it in place of the keys. */
+    const settle = (value: boolean): void => {
+      setAnswer(value);
+      setStatus("done");
+      done({ kind: "value", value });
+    };
+
+    useKeypress((key, rl) => {
+      if (status !== "idle") return;
+      // Readline echoes whatever was pressed into its buffer; take it back out.
+      rl.clearLine(0);
+
+      if (isTabKey(key)) {
+        setStatus("done");
+        done({ kind: "advanced" });
+        return;
+      }
+
+      if (isEnterKey(key)) {
+        settle(config.default ?? true);
+        return;
+      }
+
+      if (key.name === "y") settle(true);
+      else if (key.name === "n") settle(false);
+    });
+
+    return renderConfirmPrompt({
+      prefix,
+      message: config.message,
+      ...(config.default === undefined ? {} : { default: config.default }),
+      ...(answer === undefined ? {} : { answer }),
+      ...(config.hint === undefined ? {} : { hint: config.hint }),
+    });
+  }
+);

package/src/utils/flags.ts

@@ -0,0 +1,153 @@
+/**
+ * Flags that more than one command shares, defined once.
+ *
+ * The confirmation flag is the reason this module exists. Several commands stop
+ * and ask before they change anything (subscribing, trusting a repository,
+ * deleting every file sous wrote), and a caller who wants to answer those
+ * questions ahead of time should not have to remember which command spells it
+ * `--yes`, which spells it `--force` and which spells it `--trust`. They are one
+ * flag with several spellings, built here so the spellings cannot drift apart.
+ *
+ * Alternate spellings are real oclif flag aliases, not separate flags, so the
+ * help screen lists the flag once. The alternates are named in a dim suffix on
+ * the description, generated from the alias list rather than typed by hand.
+ */
+
+import { Flags } from "@oclif/core";
+import { color } from "@oclif/color";
+import type { AlphabetLowercase, AlphabetUppercase } from "@oclif/core/interfaces";
+
+/** A short flag character, in the shape oclif wants it. */
+export type FlagChar = AlphabetLowercase | AlphabetUppercase;
+
+/** What the confirmation flag is called on a given command. */
+export type ConfirmationPrimary = "yes" | "force";
+
+/** How a command asks for the shared confirmation flag. */
+export type ConfirmationFlagOptions = {
+  /**
+   * Which spelling is the primary one, which must match the key the flag is
+   * filed under in the command's `flags` object. Defaults to `yes`; `clear` uses
+   * `force`, because that is the spelling it has always had.
+   */
+  primary?: ConfirmationPrimary;
+  /**
+   * Extra long spellings to accept, on top of `--yes` and `--force`. The trust
+   * ceremony reads naturally as `--trust`, so the commands that perform it pass
+   * it here.
+   */
+  extraAliases?: string[];
+  /** Replaces the default description, which the alias suffix is still added to. */
+  description?: string;
+};
+
+/** What every confirmation flag says it does, before the alias suffix. */
+export const CONFIRMATION_DESCRIPTION =
+  "Answer yes to every confirmation this command would ask";
+
+/** The long spelling that is not the primary one, keyed by the primary one. */
+const OTHER_SPELLING: Record<ConfirmationPrimary, string> = {
+  yes: "force",
+  force: "yes",
+};
+
+/** The short character for each long spelling. */
+const CHAR_FOR: Record<string, FlagChar> = { yes: "y", force: "f" };
+
+/**
+ * Renders the "(also -f, --force)" suffix that tells a reader every other way
+ * to spell a flag, without giving each spelling a help line of its own.
+ *
+ * Short characters come first, then long names, in the order they were given.
+ * The suffix is dim, so it sits behind the description rather than competing
+ * with it; on a stream with no colors it is plain text.
+ *
+ * @param aliases - Long alternate spellings, without leading dashes.
+ * @param charAliases - Short alternate characters, without leading dashes.
+ * @returns The suffix, including its leading space, or an empty string when
+ *   there is nothing to say.
+ */
+export function aliasSuffix(aliases: string[] = [], charAliases: FlagChar[] = []): string {
+  const spellings = [
+    ...charAliases.map((char) => `-${char}`),
+    ...aliases.map((alias) => `--${alias}`),
+  ];
+  if (spellings.length === 0) return "";
+  return ` ${color.dim(`(also ${spellings.join(", ")})`)}`;
+}
+
+/**
+ * The shared confirmation flag: one boolean that answers every yes-or-no
+ * question a command would otherwise stop and ask.
+ *
+ * File it under the key named by `primary`, so `--yes` is the flag's real name
+ * on most commands and `--force` is its real name on `clear`. Either way both
+ * long spellings, both short characters, and any extra alias are accepted and
+ * behave identically.
+ *
+ * @param options - Which spelling is primary, and any extra aliases.
+ */
+export function confirmationFlag(options: ConfirmationFlagOptions = {}) {
+  const primary = options.primary ?? "yes";
+  const other = OTHER_SPELLING[primary];
+  const aliases = [other, ...(options.extraAliases ?? [])];
+  const charAliases: FlagChar[] = [CHAR_FOR[other]!];
+  const description = options.description ?? CONFIRMATION_DESCRIPTION;
+
+  return Flags.boolean({
+    char: CHAR_FOR[primary]!,
+    aliases,
+    charAliases,
+    description: `${description}${aliasSuffix(aliases, charAliases)}`,
+    default: false,
+  });
+}
+
+/**
+ * The two flags that answer a recipe's questions ahead of time, on every
+ * command that can ask one.
+ *
+ * They exist for callers with no terminal: a script, a continuous integration
+ * job, or an agent that read the question plan out of a dry run and knows every
+ * answer already. Both spellings are defined here so the commands that take
+ * them cannot describe them differently. The semantics live in
+ * `lib/vars/preanswers.ts`.
+ */
+export function answerFlags() {
+  return {
+    answer: Flags.string({
+      description:
+        "Answer one of the questions ahead of time, written as '<name>=<value>'. Repeat it for each answer",
+      multiple: true,
+    }),
+    "answers-file": Flags.string({
+      description:
+        "Read answers from a YAML or JSON file of '<name>: <value>' pairs. An '--answer' wins over the file",
+    }),
+  };
+}
+
+/** What `--non-interactive` says it does, on every command that carries it. */
+export const NON_INTERACTIVE_DESCRIPTION =
+  "Never ask a question; fail instead, naming the flag that would have answered it";
+
+/**
+ * The global flag that turns every prompt into an error, defined once.
+ *
+ * `BaseCommand` puts it in `baseFlags`, so every command that discovers a
+ * config carries it without asking. The three repository authoring commands
+ * (`repo init`, `repo release`, `repo submit`) do not extend `BaseCommand`,
+ * because they run inside a recipe repository rather than a sous project; they
+ * add this flag themselves, so the rule reads the same everywhere.
+ *
+ * The flag's effect is not in its parsed value: `lib/interactive.ts` reads the
+ * raw command line, so a prompt is already blocked by the time a command looks
+ * at its flags. Declaring it here is what stops oclif rejecting it as unknown,
+ * and what puts it on the help screen.
+ */
+export function nonInteractiveFlag() {
+  return Flags.boolean({
+    description: NON_INTERACTIVE_DESCRIPTION,
+    default: false,
+  });
+}