create-pathfinder 1.5.1 → 1.7.0

package/src/install.mjs

@@ -65,15 +65,28 @@ export function planInstall(kitRoot, targetRoot, { force = false } = {}) {
  * itself alongside everything that did succeed instead of aborting the run
  * halfway with no summary. Entries marked `skip` are never opened.
  *
+ * `onProgress` is called once per plan item, after that item has resolved, with
+ * the item and whether it succeeded. It exists so a caller can report real
+ * progress without this function knowing what a progress bar is — there is no
+ * timer here, no rate, and no percentage, because a completion event is the
+ * only thing this layer actually knows. Omit it and nothing changes: the
+ * callback is the only difference between this and the version that had no
+ * parameter at all.
+ *
+ * A failed write reports `ok: false` rather than being skipped silently. A
+ * caller that counted only calls, and not outcomes, could otherwise render a
+ * complete bar over a partly failed install.
+ *
  * @returns {{written: number, skipped: number, overwritten: number,
  *            errors: {relativePath: string, message: string}[]}}
  */
-export function applyPlan(plan, { dryRun = false } = {}) {
+export function applyPlan(plan, { dryRun = false, onProgress } = {}) {
   const result = { written: 0, skipped: 0, overwritten: 0, errors: [] };
 
   for (const item of plan) {
     if (item.status === "skip") {
       result.skipped += 1;
+      onProgress?.({ item, ok: true });
       continue;
     }
 
@@ -86,12 +99,14 @@ export function applyPlan(plan, { dryRun = false } = {}) {
           relativePath: item.relativePath,
           message: error.message,
         });
+        onProgress?.({ item, ok: false });
         continue;
       }
     }
 
     if (item.status === "overwrite") result.overwritten += 1;
     else result.written += 1;
+    onProgress?.({ item, ok: true });
   }
 
   return result;
@@ -205,26 +220,37 @@ function actionFor(state, force) {
  * Conflicts and orphans are outcomes, not errors: nothing went wrong, and the
  * files they name are the ones this tool successfully left alone.
  *
+ * `onProgress` behaves exactly as it does in `applyPlan`, and for the same
+ * reason: one call per plan item, after it resolves, carrying the item and
+ * whether it succeeded. Conflicts, orphans, and up-to-date adapters all report
+ * `ok: true` — nothing went wrong in any of those cases, and each one is an
+ * enumerated unit of a plan the user is watching being carried out. Only an
+ * unreadable file and a failed write report `ok: false`.
+ *
  * @returns {{generated: number, replaced: number, unchanged: number,
  *            conflicts: string[], orphans: string[],
  *            errors: {relativePath: string, message: string}[]}}
  */
-export function applyAdapterPlan(plan, { dryRun = false } = {}) {
+export function applyAdapterPlan(plan, { dryRun = false, onProgress } = {}) {
   const result = { generated: 0, replaced: 0, unchanged: 0, conflicts: [], orphans: [], errors: [] };
 
   for (const item of plan) {
     switch (item.action) {
       case "up-to-date":
         result.unchanged += 1;
+        onProgress?.({ item, ok: true });
         continue;
       case "conflict":
         result.conflicts.push(item.relativePath);
+        onProgress?.({ item, ok: true });
         continue;
       case "orphan":
         result.orphans.push(item.relativePath);
+        onProgress?.({ item, ok: true });
         continue;
       case "unreadable":
         result.errors.push({ relativePath: item.relativePath, message: item.message });
+        onProgress?.({ item, ok: false });
         continue;
       default:
         break;
@@ -236,12 +262,14 @@ export function applyAdapterPlan(plan, { dryRun = false } = {}) {
         writeFileSync(item.destination, item.contents, "utf8");
       } catch (error) {
         result.errors.push({ relativePath: item.relativePath, message: error.message });
+        onProgress?.({ item, ok: false });
         continue;
       }
     }
 
     if (item.action === "replace") result.replaced += 1;
     else result.generated += 1;
+    onProgress?.({ item, ok: true });
   }
 
   return result;

package/src/kit.mjs

@@ -51,6 +51,22 @@ export function isExcluded(basename) {
 
 const PACKAGE_ROOT = resolve(HERE, "..");
 
+/**
+ * This installer's own version, for the identity block to state.
+ *
+ * Read from the package manifest for the same reason the copy list is: the
+ * number has one home, and a constant declared here would be a second one that
+ * `npm version` does not know to update. Read once at module load, because a
+ * file that is part of the running package cannot change underneath a single
+ * run, and because a failure to read it should surface at import rather than
+ * halfway through a report.
+ *
+ * Not exported through `findKitRoot`'s resolution: the manifest sits beside
+ * this source in both layouts, published and checkout alike, so there is
+ * nothing to search for.
+ */
+export const VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+
 /**
  * Locate the kit directories this tool should copy from.
  *

package/src/progress.mjs

@@ -0,0 +1,144 @@
+/**
+ * The install phase's progress bar: one counter, one format function, one write.
+ *
+ * Not a renderer framework, and deliberately not extensible. It holds three
+ * numbers and knows how to draw one line from them.
+ *
+ * **What makes this bar honest**, since a progress bar is the easiest thing in
+ * a CLI to fake and the prototype rejected an earlier version of it as theatre:
+ *
+ * - **The denominator is a plan, not an estimate.** `planInstall` and
+ *   `planAdapters` both return complete lists before a single byte is written,
+ *   so the total is a count of enumerated work rather than a guess that gets
+ *   corrected as it goes.
+ * - **The numerator is completions.** It moves when `applyPlan` or
+ *   `applyAdapterPlan` finishes a unit and tells us so. There is no timer in
+ *   this file, no interval, no rate, and nothing that advances because time
+ *   passed. That is also why no throttle is needed: the bar repaints at most
+ *   once per completed unit, and the unit count is bounded by the plan.
+ * - **A run that finishes instantly is a correct run.** If the work takes 30ms
+ *   the bar reaches 100% in 30ms and the phase ends. Nothing sleeps or paces
+ *   itself so the effect can be admired.
+ * - **Nothing is displayed that has not been earned.** Both the fill and the
+ *   percentage floor rather than round, so neither can show a complete bar
+ *   while a unit is still outstanding.
+ * - **A failure cannot produce a clean 100%.** A failed unit advances nothing;
+ *   it increments a separate counter that the bar renders explicitly. An
+ *   install that lost two files ends visibly short with those two named, which
+ *   is the one thing the summary underneath must never be contradicted about.
+ *
+ * **What it deliberately cannot do.** There is no hide-cursor sequence here and
+ * no way to write one: `theme.line` exposes exactly two escapes, return to
+ * column zero and clear the line, and neither of them is stateful. A renderer
+ * with nothing to restore cannot leave a terminal broken, so this file has no
+ * signal handler, no exit hook, and no try/finally — an interrupted run leaves
+ * a visible cursor on a partly drawn bar, which is the accepted cost and the
+ * reason the guarantee holds without any machinery defending it.
+ */
+
+/**
+ * How many cells the bar occupies.
+ *
+ * A constant, not a function of the terminal width. Deriving it from the
+ * terminal would mean measuring, would make the bar jump on a resize, and would
+ * make its rendering depend on a value this process has no reliable way to
+ * track. A fixed bar is stable in scrollback and identical in every transcript.
+ */
+const BAR_CELLS = 24;
+
+/**
+ * Build the progress treatment for one run.
+ *
+ * Three behaviours, chosen from the theme and never from a call site:
+ *
+ * - `contract` — nothing at all. No bar, no milestone, no byte. This tier is a
+ *   promise made to scripts, and a repaint written into a pipe would produce a
+ *   log file containing a transcript of an animation.
+ * - `plain` — milestones, no bar. The phase still says what it finished; it
+ *   simply does not repaint a line, because `dynamic` is false.
+ * - `expressive` — milestones and the bar.
+ *
+ * @param {object} options
+ * @param {object} options.theme - the run's theme, from `createTheme`.
+ * @param {number} options.total - units the plans enumerated. Zero disables the
+ *   bar, which is what a dry run and an empty plan both want.
+ * @param {(text: string) => void} options.out - where to write.
+ */
+export function createProgress({ theme, total = 0, out = () => {} } = {}) {
+  const speaks = theme.tier !== "contract";
+  const repaints = speaks && theme.dynamic && total > 0;
+
+  let done = 0;
+  let failed = 0;
+
+  /**
+   * The bar, as one line, from the three numbers above.
+   *
+   * Floor rather than round on both the fill and the percentage. Rounding would
+   * let 35 of 36 units display a full bar at 100%, which is a claim about work
+   * that has not happened — the exact defect this whole design exists to avoid,
+   * and one that would only ever be visible on the last unit of a slow run.
+   */
+  const bar = () => {
+    const filled = Math.floor((done / total) * BAR_CELLS);
+    const track =
+      theme.glyph.barFull.repeat(filled) + theme.glyph.barEmpty.repeat(BAR_CELLS - filled);
+    const percent = String(Math.floor((done / total) * 100)).padStart(3);
+
+    // Painted `warn` the moment anything has failed, so the bar's own colour
+    // stops agreeing with a summary that is about to report an error. Colour is
+    // not the only carrier: the count and its glyph are spelled out beside it.
+    const tail = failed > 0 ? `  ${theme.warn(`${theme.glyph.warn} ${failed} failed`)}` : "";
+    return `  ${failed > 0 ? theme.warn(track) : theme.ok(track)} ${percent}%${tail}`;
+  };
+
+  const repaint = () => {
+    if (repaints) out(theme.line.start() + theme.line.clear() + bar());
+  };
+
+  return {
+    /** One unit resolved. The only thing that may move this bar. */
+    advance({ ok = true } = {}) {
+      if (ok) done += 1;
+      else failed += 1;
+      repaint();
+    },
+
+    /**
+     * A phase finished. Printed above the bar, which is then redrawn.
+     *
+     * The clear-then-print-then-repaint order is what lets a milestone scroll
+     * into the transcript while the bar stays on the last line, using only the
+     * two escapes the theme exposes. Moving the cursor up to keep the bar in
+     * place would need sequences that do not exist here on purpose.
+     */
+    milestone(text) {
+      if (!speaks) return;
+      if (repaints) out(theme.line.start() + theme.line.clear());
+      out(`${text}\n`);
+      repaint();
+    },
+
+    /**
+     * End the phase, leaving the completed bar on screen.
+     *
+     * One newline, so the bar becomes part of the transcript rather than
+     * something the summary overwrites. Someone pasting the run into an issue
+     * keeps the evidence that the phase ran.
+     */
+    finish() {
+      if (repaints) out("\n");
+    },
+
+    /** Exposed for tests and for a caller that wants to assert its own totals. */
+    get completed() {
+      return done;
+    },
+    get failures() {
+      return failed;
+    },
+    get total() {
+      return total;
+    },
+  };
+}

package/src/prompt.mjs

@@ -10,10 +10,31 @@
  * nothing must also print nothing, and a guard bug that degrades silently would
  * show up as a script that hangs on someone's CI runner months later.
  *
- * The second is the decided interaction model: `node:readline` and printed
- * lines. No setRawMode, no keypress handler, no cursor control, no redraw. That
- * is what makes this work in a dumb terminal, over ssh, and inside an editor's
- * integrated console, and it is a decision rather than a default.
+ * The second is the decided interaction model. ~~`node:readline` and printed
+ * lines. No setRawMode, no keypress handler, no cursor control, no redraw.~~
+ * **Superseded in Feature 23**, in two different ways, and the sentence was
+ * partly wrong when it was written:
+ *
+ * - **"No setRawMode" was never true of the process**, only of this file.
+ *   `node:readline` turns raw mode on itself the moment its input is a TTY, and
+ *   turns it off again on `close()` — verified across five Node majors during
+ *   the spike. What is true, and is now the load-bearing statement, is that
+ *   **readline owns raw mode and Pathfinder never touches it.** The distinction
+ *   matters: the first is a claim about terminal state that a reader could check
+ *   and find false, and the second is the reason no interrupt can leave a
+ *   terminal broken.
+ * - **There is now a keypress handler and a redraw**, in `select.mjs`, borrowed
+ *   from readline and given back. Which is a change of interaction, not of
+ *   ownership.
+ *
+ * What has *not* changed is the reason the original sentence existed. The
+ * line-based path still works in a dumb terminal, over a pipe, and on a CI
+ * runner, and it is still here — every function below keeps its numbered/`y n`
+ * implementation intact and reaches for it whenever `theme.selection` is false.
+ * That is a supported way to use this tool, reachable deliberately with
+ * `PATHFINDER_PROMPT=classic`, and not a fallback anyone should feel they have
+ * been demoted to. `text()` never had anything to gain from a keypress loop and
+ * is untouched.
  *
  * Answers are bounded. Unparseable input is re-prompted a fixed number of times
  * and then gives up, so an input stream that will never produce a `y` cannot
@@ -24,14 +45,25 @@
 
 import { createInterface } from "node:readline";
 
+import { alignmentWidth, optionRow, select } from "./select.mjs";
+import { createTheme } from "./theme.mjs";
+
 const YES = new Set(["y", "yes"]);
 const NO = new Set(["n", "no"]);
 
 /**
  * A question-asker bound to one pair of streams.
  *
+ * `theme` decides *how* a question is asked and nothing else. Every function
+ * below returns the same values through either path, which is what lets the
+ * choice be made here instead of at four call sites — and what lets the whole
+ * existing test suite drive the classic path unchanged by simply not supplying
+ * one. The default theme knows about no terminal at all, so it answers no to
+ * `selection`, which is the conservative answer and the right one for a
+ * prompter built from streams nobody has described.
+ *
  * @param {{input: NodeJS.ReadableStream, output: NodeJS.WritableStream,
- *          interactive?: boolean, retries?: number}} options
+ *          interactive?: boolean, retries?: number, theme?: object}} options
  * @returns {{interactive: boolean,
  *            confirm: (question: string, options?: {defaultAnswer?: boolean}) => Promise<boolean|null>,
  *            chooseMany: (question: string, config?: object) => Promise<unknown[]|null>,
@@ -39,7 +71,13 @@ const NO = new Set(["n", "no"]);
  *            text: (question: string) => Promise<string|null>,
  *            close: () => void}}
  */
-export function createPrompter({ input, output, interactive = false, retries = 3 }) {
+export function createPrompter({
+  input,
+  output,
+  interactive = false,
+  retries = 3,
+  theme = createTheme(),
+}) {
   let reader = null;
 
   // Created on first use, not here. A run that never reaches a question — a
@@ -47,10 +85,23 @@ export function createPrompter({ input, output, interactive = false, retries = 3
   // reader to stdin, because attaching one resumes the stream and a process
   // holding an open stdin does not exit on its own.
   function ensureReader() {
-    if (reader === null) reader = createReader({ input, output });
+    if (reader === null) reader = createReader({ input, output, theme });
     return reader;
   }
 
+  /**
+   * Ask one question with the arrow keys.
+   *
+   * The Interface is handed over rather than a pair of streams, because the
+   * selector's whole contract is that it borrows from an open readline and
+   * gives it back. Nothing here consults `input.isTTY`: the decision was made
+   * once, in the theme, and a module that re-derived it could disagree with the
+   * one place that is allowed to have an opinion — and could not be tested over
+   * a pipe at all.
+   */
+  const ask = (question, config) =>
+    select({ readline: ensureReader().readline, theme, question, ...config });
+
   return {
     interactive,
 
@@ -59,6 +110,20 @@ export function createPrompter({ input, output, interactive = false, retries = 3
         throw new Error(`refusing to ask "${question}": this prompter is not interactive`);
       }
 
+      // Two rows rather than a typed letter. `y` and `n` still work and are
+      // deliberately not printed: the presented interaction is the one the hint
+      // line describes, and an accelerator that has to be advertised is a second
+      // thing to learn rather than a shortcut for people who already know it.
+      if (theme.selection) {
+        return ask(question, {
+          options: [
+            { label: "Yes", value: true, key: "y" },
+            { label: "No", value: false, key: "n" },
+          ],
+          initial: [defaultAnswer],
+        });
+      }
+
       const suffix = defaultAnswer ? "[Y/n]" : "[y/N]";
 
       for (let attempt = 0; attempt < retries; attempt += 1) {
@@ -103,12 +168,28 @@ export function createPrompter({ input, output, interactive = false, retries = 3
       }
       if (choices.length === 0) return [];
 
+      // A checkbox list, which is what this question always was. Note what does
+      // *not* move: the caller still supplies `{label, value}` and still reads
+      // back the chosen values in list order, so no decision about what the
+      // options mean has crossed into this file.
+      if (theme.selection) {
+        return ask(question, { options: choices, multi: true, initial: defaultSelection });
+      }
+
       const defaults = choices.filter((choice) => defaultSelection.includes(choice.value));
       const defaultNumbers = defaults.map((choice) => choices.indexOf(choice) + 1);
 
+      // The same option grammar the selector uses, inside a numbered list
+      // instead of a repainted block. An option that names the path it writes
+      // to is not a decoration the keyboard path earned — it is the answer to
+      // "what does checking this box do", and both paths owe it.
+      const labelWidth = alignmentWidth(choices, theme);
+
       const header = [
         `? ${question}`,
-        ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+        ...choices.map(
+          (choice, index) => `    ${index + 1}. ${optionRow({ theme, option: choice, labelWidth })}`,
+        ),
         defaultNumbers.length > 0
           ? `  Numbers, comma-separated. Enter for the detected default [${defaultNumbers.join(",")}], or 0 for none.`
           : "  Numbers, comma-separated. Enter or 0 for none.",
@@ -158,12 +239,22 @@ export function createPrompter({ input, output, interactive = false, retries = 3
       if (choices.length === 0) return null;
 
       const fallback = choices.find((choice) => choice.value === defaultValue) ?? choices[0];
+
+      // The default becomes the highlighted row rather than a number in a
+      // sentence, so taking it still costs one keystroke.
+      if (theme.selection) {
+        return ask(question, { options: choices, initial: [fallback.value] });
+      }
+
       const defaultNumber = choices.indexOf(fallback) + 1;
+      const labelWidth = alignmentWidth(choices, theme);
 
       output.write(
         [
           `? ${question}`,
-          ...choices.map((choice, index) => `    ${index + 1}. ${choice.label}`),
+          ...choices.map(
+            (choice, index) => `    ${index + 1}. ${optionRow({ theme, option: choice, labelWidth })}`,
+          ),
           `  A number, or Enter for [${defaultNumber}].`,
           "",
         ].join("\n"),
@@ -266,8 +357,16 @@ export function nonInteractivePrompter() {
  * with a closed stdin must fall through to the caller's decision about an
  * unanswered question, not hang.
  */
-function createReader({ input, output }) {
-  const readline = createInterface({ input, output });
+function createReader({ input, output, theme }) {
+  // `terminal` is forced only where the selector will run, and only ever from
+  // false to true. On a real terminal readline works this out for itself and
+  // the flag changes nothing; over a pipe it is what makes the keypress decoder
+  // exist at all, which is the difference between a selector that can be tested
+  // and one that can only be tried. It is never forced *off*, so no classic run
+  // has its line editing altered by this.
+  const readline = createInterface(
+    theme?.selection ? { input, output, terminal: true } : { input, output },
+  );
   const delivered = [];
   const waiting = [];
   let closed = false;
@@ -284,6 +383,12 @@ function createReader({ input, output }) {
   });
 
   return {
+    // The Interface itself, for the one caller that needs the *owner* rather
+    // than a line: the selector borrows this object's listeners and hands them
+    // back. Exposed rather than re-created, because a second Interface over the
+    // same stdin would be a second thing turning raw mode on and off.
+    readline,
+
     /**
      * Print `text` and resolve with the next line, or null at end of input.
      *