@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/domains/shared/createInteractivePromptSession.test.ts

@@ -1,439 +0,0 @@
-import type { Effect, PromptQuestion } from "@canonical/task";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-const { createInterfaceMock } = vi.hoisted(() => ({
-  createInterfaceMock: vi.fn(),
-}));
-
-vi.mock("node:readline", () => ({ createInterface: createInterfaceMock }));
-
-const { default: createInteractivePromptSession } = await import(
-  "./createInteractivePromptSession.js"
-);
-
-const prompt = (question: PromptQuestion): Effect & { _tag: "Prompt" } => ({
-  _tag: "Prompt",
-  question,
-});
-
-/**
- * A fake persistent readline interface honouring the real contract: one
- * interface answers many questions from a queue, `close()` emits 'close'
- * synchronously, and an exhausted queue simulates EOF by closing.
- */
-const stubReadline = (lines: string[]) => {
-  const closeListeners: Array<() => void> = [];
-  const sigintListeners: Array<() => void> = [];
-  const queries: string[] = [];
-  const iface = {
-    on: (event: string, handler: () => void) => {
-      if (event === "close") closeListeners.push(handler);
-      if (event === "SIGINT") sigintListeners.push(handler);
-    },
-    question: (query: string, cb: (answer: string) => void) => {
-      queries.push(query);
-      const next = lines.shift();
-      if (next === undefined) {
-        for (const handler of closeListeners) handler();
-        return;
-      }
-      cb(next);
-    },
-    close: () => {
-      for (const handler of closeListeners) handler();
-    },
-  };
-  createInterfaceMock.mockReturnValue(iface);
-  return {
-    queries,
-    sigint: () => {
-      for (const handler of sigintListeners) handler();
-    },
-  };
-};
-
-/** A stub whose question never answers — for interrupt-while-pending tests. */
-const stubHangingReadline = () => {
-  const closeListeners: Array<() => void> = [];
-  const sigintListeners: Array<() => void> = [];
-  createInterfaceMock.mockReturnValue({
-    on: (event: string, handler: () => void) => {
-      if (event === "close") closeListeners.push(handler);
-      if (event === "SIGINT") sigintListeners.push(handler);
-    },
-    question: () => {},
-    close: () => {
-      for (const handler of closeListeners) handler();
-    },
-  });
-  return {
-    sigint: () => {
-      for (const handler of sigintListeners) handler();
-    },
-  };
-};
-
-describe("createInteractivePromptSession", () => {
-  let stderrSpy: ReturnType<typeof vi.spyOn>;
-  let writes: string[];
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    writes = [];
-    stderrSpy = vi
-      .spyOn(process.stderr, "write")
-      .mockImplementation((chunk) => {
-        writes.push(String(chunk));
-        return true;
-      });
-  });
-
-  afterEach(() => {
-    stderrSpy.mockRestore();
-  });
-
-  // --- text --------------------------------------------------------------
-
-  it("reads a text answer and shows the default hint", async () => {
-    const { queries } = stubReadline(["Widget"]);
-    const session = createInteractivePromptSession();
-
-    const answer = await session.answerPrompt(
-      prompt({ type: "text", name: "n", message: "Name?", default: "Btn" }),
-    );
-
-    expect(answer).toBe("Widget");
-    expect(queries[0]).toBe("Name? (Btn): ");
-    session.dispose();
-  });
-
-  it("takes the text default on empty input", async () => {
-    stubReadline([""]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "text", name: "n", message: "Name?", default: "Btn" }),
-      ),
-    ).toBe("Btn");
-    session.dispose();
-  });
-
-  it("re-asks a text prompt while empty with no default", async () => {
-    const { queries } = stubReadline(["", "", "Widget"]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "text", name: "n", message: "Name?" }),
-      ),
-    ).toBe("Widget");
-    expect(queries).toHaveLength(3);
-    session.dispose();
-  });
-
-  it("re-asks on a validate failure, printing its message", async () => {
-    stubReadline(["bad", "good"]);
-    const session = createInteractivePromptSession();
-
-    const answer = await session.answerPrompt(
-      prompt({
-        type: "text",
-        name: "n",
-        message: "Name?",
-        validate: (value) => value === "good" || "must be good",
-      }),
-    );
-
-    expect(answer).toBe("good");
-    expect(writes).toContain("must be good\n");
-    session.dispose();
-  });
-
-  it("re-asks on a boolean-false validate verdict with a generic message", async () => {
-    stubReadline(["bad", "good"]);
-    const session = createInteractivePromptSession();
-
-    const answer = await session.answerPrompt(
-      prompt({
-        type: "text",
-        name: "n",
-        message: "Name?",
-        validate: (value) => value === "good",
-      }),
-    );
-
-    expect(answer).toBe("good");
-    expect(writes).toContain("Invalid value.\n");
-    session.dispose();
-  });
-
-  // --- confirm -------------------------------------------------------------
-
-  it("parses yes/no answers and hints from the default", async () => {
-    const { queries } = stubReadline(["yes", "N"]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "confirm", name: "a", message: "A?", default: true }),
-      ),
-    ).toBe(true);
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "confirm", name: "b", message: "B?", default: false }),
-      ),
-    ).toBe(false);
-    expect(queries).toEqual(["A? [Y/n] ", "B? [y/N] "]);
-    session.dispose();
-  });
-
-  it("takes the confirm default on empty input", async () => {
-    stubReadline([""]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "confirm", name: "a", message: "A?", default: false }),
-      ),
-    ).toBe(false);
-    session.dispose();
-  });
-
-  it("re-asks a confirm with no default until it gets y or n", async () => {
-    const { queries } = stubReadline(["", "maybe", "n"]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "confirm", name: "a", message: "A?" }),
-      ),
-    ).toBe(false);
-    expect(queries).toEqual(["A? [y/n] ", "A? [y/n] ", "A? [y/n] "]);
-    session.dispose();
-  });
-
-  // --- select ----------------------------------------------------------------
-
-  const shellSelect: PromptQuestion = {
-    type: "select",
-    name: "shell",
-    message: "Shell?",
-    choices: [
-      { label: "Bash", value: "bash" },
-      { label: "Zsh", value: "zsh" },
-    ],
-  };
-
-  it("renders the menu and accepts a number, a value, or a label", async () => {
-    stubReadline(["2", "bash", "Zsh"]);
-    const session = createInteractivePromptSession();
-
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("zsh");
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("bash");
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("zsh");
-    expect(writes).toContain("Shell?\n");
-    expect(writes).toContain("  1) Bash\n");
-    expect(writes).toContain("  2) Zsh\n");
-    session.dispose();
-  });
-
-  it("takes the select default on empty input, re-asks without one", async () => {
-    const { queries } = stubReadline(["", "", "1"]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(prompt({ ...shellSelect, default: "zsh" })),
-    ).toBe("zsh");
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("bash");
-    expect(queries).toHaveLength(3);
-    session.dispose();
-  });
-
-  it("re-asks on an unmatched select answer", async () => {
-    const { queries } = stubReadline(["9", "fish", "2"]);
-    const session = createInteractivePromptSession();
-
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("zsh");
-    expect(queries).toHaveLength(3);
-    session.dispose();
-  });
-
-  it("resolves a choiceless select to its default without prompting", async () => {
-    stubReadline([]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ ...shellSelect, choices: [], default: "zsh" }),
-      ),
-    ).toBe("zsh");
-    expect(createInterfaceMock).not.toHaveBeenCalled();
-    session.dispose();
-  });
-
-  // --- multiselect -------------------------------------------------------
-
-  const featureMulti: PromptQuestion = {
-    type: "multiselect",
-    name: "features",
-    message: "Features?",
-    choices: [
-      { label: "A", value: "a" },
-      { label: "B", value: "b" },
-      { label: "C", value: "c" },
-    ],
-  };
-
-  it("accepts comma-separated numbers, values, and labels", async () => {
-    stubReadline(["1, b ,C"]);
-    const session = createInteractivePromptSession();
-
-    expect(await session.answerPrompt(prompt(featureMulti))).toEqual([
-      "a",
-      "b",
-      "c",
-    ]);
-    session.dispose();
-  });
-
-  it("takes the multiselect default on empty input, re-asks on all-invalid", async () => {
-    const { queries } = stubReadline(["", "x,y", "2"]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(prompt({ ...featureMulti, default: ["c"] })),
-    ).toEqual(["c"]);
-    expect(await session.answerPrompt(prompt(featureMulti))).toEqual(["b"]);
-    expect(queries).toHaveLength(3);
-    session.dispose();
-  });
-
-  it("resolves a choiceless multiselect to its default or none", async () => {
-    stubReadline([]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(prompt({ ...featureMulti, choices: [] })),
-    ).toEqual([]);
-    session.dispose();
-  });
-
-  it("accepts a comma-separated single-select answer by its first valid token", async () => {
-    stubReadline(["nope,2,1"]);
-    const session = createInteractivePromptSession();
-
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("zsh");
-    session.dispose();
-  });
-
-  it("resolves a choiceless select with no default to an empty string", async () => {
-    stubReadline([]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(prompt({ ...shellSelect, choices: [] })),
-    ).toBe("");
-    expect(createInterfaceMock).not.toHaveBeenCalled();
-    session.dispose();
-  });
-
-  // --- interrupt -----------------------------------------------------------
-
-  it("Ctrl-C rejects the pending prompt and marks the session interrupted", async () => {
-    const { sigint } = stubHangingReadline();
-    const session = createInteractivePromptSession();
-
-    const pending = session.answerPrompt(
-      prompt({ type: "confirm", name: "a", message: "A?", default: true }),
-    );
-    sigint();
-
-    await expect(pending).rejects.toThrow("Prompt interrupted");
-    expect(session.wasInterrupted()).toBe(true);
-    await expect(
-      session.answerPrompt(
-        prompt({ type: "text", name: "b", message: "B?", default: "d" }),
-      ),
-    ).rejects.toThrow("Prompt interrupted");
-    session.dispose();
-  });
-
-  // --- lifecycle -----------------------------------------------------------
-
-  it("spans one readline interface across many questions", async () => {
-    stubReadline(["n", "Widget"]);
-    const session = createInteractivePromptSession();
-
-    await session.answerPrompt(
-      prompt({ type: "confirm", name: "a", message: "A?", default: true }),
-    );
-    await session.answerPrompt(
-      prompt({ type: "text", name: "b", message: "B?" }),
-    );
-
-    expect(createInterfaceMock).toHaveBeenCalledTimes(1);
-    session.dispose();
-  });
-
-  it("falls back to defaults for every prompt after EOF", async () => {
-    // One answer, then the stream ends mid-question.
-    stubReadline(["n"]);
-    const session = createInteractivePromptSession();
-
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "confirm", name: "a", message: "A?", default: true }),
-      ),
-    ).toBe(false);
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "text", name: "b", message: "B?", default: "d" }),
-      ),
-    ).toBe("d");
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "confirm", name: "c", message: "C?" }),
-      ),
-    ).toBe(true);
-    expect(await session.answerPrompt(prompt(shellSelect))).toBe("bash");
-    expect(await session.answerPrompt(prompt(featureMulti))).toEqual([]);
-    session.dispose();
-  });
-
-  it("never opens readline when stdin already ended", async () => {
-    const endedSpy = vi
-      .spyOn(process.stdin, "readableEnded", "get")
-      .mockReturnValue(true);
-    try {
-      const session = createInteractivePromptSession();
-      expect(
-        await session.answerPrompt(
-          prompt({ type: "text", name: "n", message: "N?", default: "d" }),
-        ),
-      ).toBe("d");
-      expect(createInterfaceMock).not.toHaveBeenCalled();
-      session.dispose();
-    } finally {
-      endedSpy.mockRestore();
-    }
-  });
-
-  it("dispose closes the interface once and is safe to repeat", async () => {
-    stubReadline(["x"]);
-    const session = createInteractivePromptSession();
-    await session.answerPrompt(
-      prompt({ type: "text", name: "n", message: "N?" }),
-    );
-
-    session.dispose();
-    session.dispose();
-
-    // After dispose (which closed the interface), prompts resolve to defaults.
-    expect(
-      await session.answerPrompt(
-        prompt({ type: "text", name: "n", message: "N?", default: "d" }),
-      ),
-    ).toBe("d");
-  });
-});

package/src/domains/shared/createInteractivePromptSession.ts

@@ -1,236 +0,0 @@
-import { createInterface, type Interface } from "node:readline";
-import type { Effect, PromptQuestion } from "@canonical/task";
-
-/**
- * An interactive prompt session: the `promptHandler` seam implementation a
- * terminal front-end injects into the shared executor, plus its lifecycle.
- * Create one per command run and dispose it when the run ends.
- */
-export interface InteractivePromptSession {
-  /** Resolve a `Prompt` effect by asking the user over readline. */
-  readonly answerPrompt: (
-    effect: Effect & { _tag: "Prompt" },
-  ) => Promise<unknown>;
-  /** Whether the user interrupted a prompt (Ctrl-C). */
-  readonly wasInterrupted: () => boolean;
-  /** Release the underlying readline interface. Safe to call twice. */
-  readonly dispose: () => void;
-}
-
-/** Thrown when the user interrupts a prompt — the run must abort, not proceed. */
-export class PromptInterruptedError extends Error {
-  constructor() {
-    super("Prompt interrupted");
-    this.name = "PromptInterruptedError";
-  }
-}
-
-/** Render a choice list to stderr as a numbered menu. */
-function renderChoices(
-  choices: ReadonlyArray<{ label: string; value: string }>,
-): void {
-  for (const [index, choice] of choices.entries()) {
-    process.stderr.write(`  ${index + 1}) ${choice.label}\n`);
-  }
-}
-
-/**
- * Resolve one answer token against a choice list: a 1-based number, an exact
- * value, or an exact label.
- */
-function matchChoice(
-  choices: ReadonlyArray<{ label: string; value: string }>,
-  token: string,
-): string | undefined {
-  const index = Number(token);
-  if (Number.isInteger(index) && index >= 1 && index <= choices.length) {
-    return choices[index - 1]?.value;
-  }
-  const matched = choices.find(
-    (choice) => choice.value === token || choice.label === token,
-  );
-  return matched?.value;
-}
-
-/**
- * Create an interactive prompt session over stdin/stderr.
- *
- * One readline interface spans the whole session, so answers piped in a
- * single chunk (`printf "n\nWidget\n" | pragma …`) survive across questions —
- * closing a per-question interface would discard its buffered lines. Prompts
- * render on stderr, keeping stdout clean for piping. On EOF (a closed or
- * non-interactive stdin) every prompt resolves to its default instead of
- * hanging.
- *
- * The unified dialect, per prompt type:
- * - text: shows the default in parentheses; empty input takes the default or
- *   re-asks when there is none; a `validate` failure re-asks with its message.
- * - confirm: `[Y/n]`/`[y/N]`; empty input takes the default, re-asks when the
- *   default is undefined.
- * - select/multiselect: numbered menu; an answer token is a number, a value,
- *   or a label (multiselect: comma-separated); empty input takes the default
- *   or re-asks when there is none.
- *
- * @returns The session: the `promptHandler` seam function plus `dispose`.
- * @note Impure — reads from stdin and writes prompts to stderr.
- */
-export default function createInteractivePromptSession(): InteractivePromptSession {
-  let rl: Interface | undefined;
-  let ended = process.stdin.readableEnded === true;
-  let interrupted = false;
-  let pending: ((value: string) => void) | undefined;
-
-  const open = (): Interface => {
-    if (rl === undefined) {
-      rl = createInterface({ input: process.stdin, output: process.stderr });
-      // Ctrl-C is an abort, not an EOF: proceeding with defaults would run the
-      // very command the user is cancelling. Mark, then close.
-      rl.on("SIGINT", () => {
-        interrupted = true;
-        rl?.close();
-      });
-      // EOF with a question outstanding: resolve it to "" so the caller falls
-      // back to defaults; every later ask short-circuits on `ended`.
-      rl.on("close", () => {
-        ended = true;
-        pending?.("");
-        pending = undefined;
-      });
-    }
-    return rl;
-  };
-
-  const ask = async (query: string): Promise<string> => {
-    if (interrupted) {
-      throw new PromptInterruptedError();
-    }
-    if (ended) {
-      return "";
-    }
-    const answer = await new Promise<string>((resolve) => {
-      pending = resolve;
-      open().question(query, (value) => {
-        pending = undefined;
-        resolve(value.trim());
-      });
-    });
-    if (interrupted) {
-      throw new PromptInterruptedError();
-    }
-    return answer;
-  };
-
-  const askText = async (
-    question: PromptQuestion & { type: "text" },
-  ): Promise<string> => {
-    const hint = question.default === undefined ? "" : ` (${question.default})`;
-    for (;;) {
-      const answer = await ask(`${question.message}${hint}: `);
-      if (answer === "") {
-        if (question.default !== undefined) return question.default;
-        if (ended) return "";
-        continue;
-      }
-      const verdict = question.validate?.(answer) ?? true;
-      if (verdict === true) return answer;
-      process.stderr.write(
-        `${typeof verdict === "string" ? verdict : "Invalid value."}\n`,
-      );
-      if (ended) return question.default ?? "";
-    }
-  };
-
-  const askConfirm = async (
-    question: PromptQuestion & { type: "confirm" },
-  ): Promise<boolean> => {
-    const hint =
-      question.default === true
-        ? "Y/n"
-        : question.default === false
-          ? "y/N"
-          : "y/n";
-    for (;;) {
-      const answer = (
-        await ask(`${question.message} [${hint}] `)
-      ).toLowerCase();
-      if (answer === "" && (question.default !== undefined || ended)) {
-        return question.default ?? true;
-      }
-      if (answer === "y" || answer === "yes") return true;
-      if (answer === "n" || answer === "no") return false;
-    }
-  };
-
-  const askSelect = async (
-    question: PromptQuestion & { type: "select" },
-  ): Promise<string> => {
-    if (question.choices.length === 0) {
-      return question.default ?? "";
-    }
-    process.stderr.write(`${question.message}\n`);
-    renderChoices(question.choices);
-    const hint = question.default === undefined ? "" : ` (${question.default})`;
-    for (;;) {
-      const answer = await ask(`Choose a value${hint}: `);
-      if (answer === "") {
-        if (question.default !== undefined) return question.default;
-        if (ended) return question.choices[0]?.value ?? "";
-        continue;
-      }
-      // Tolerate a comma-separated answer at a single select: first valid token.
-      const value = answer
-        .split(",")
-        .map((token) => matchChoice(question.choices, token.trim()))
-        .find((match) => match !== undefined);
-      if (value !== undefined) return value;
-      if (ended) return question.default ?? question.choices[0]?.value ?? "";
-    }
-  };
-
-  const askMultiselect = async (
-    question: PromptQuestion & { type: "multiselect" },
-  ): Promise<string[]> => {
-    if (question.choices.length === 0) {
-      return question.default ?? [];
-    }
-    process.stderr.write(`${question.message}\n`);
-    renderChoices(question.choices);
-    const hint =
-      question.default === undefined ? "" : ` (${question.default.join(",")})`;
-    for (;;) {
-      const answer = await ask(`Choose one or more values${hint}: `);
-      if (answer === "") {
-        if (question.default !== undefined) return question.default;
-        if (ended) return [];
-        continue;
-      }
-      const picked = answer
-        .split(",")
-        .map((token) => matchChoice(question.choices, token.trim()))
-        .filter((value): value is string => value !== undefined);
-      if (picked.length > 0) return picked;
-      if (ended) return question.default ?? [];
-    }
-  };
-
-  return {
-    answerPrompt: (effect) => {
-      const question = effect.question;
-      switch (question.type) {
-        case "confirm":
-          return askConfirm(question);
-        case "select":
-          return askSelect(question);
-        case "multiselect":
-          return askMultiselect(question);
-        default:
-          return askText(question);
-      }
-    },
-    wasInterrupted: () => interrupted,
-    dispose: () => {
-      rl?.close();
-      rl = undefined;
-    },
-  };
-}