@gitpagedocs/cli 0.0.1

package/presentation/options/parser.ts

@@ -0,0 +1,120 @@
+import type { CliMode, CliOptions } from "../../domain/models/cli-options";
+import { DEFAULTS } from "./schema";
+import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
+
+const KNOWN_FLAGS = new Set([
+  "--build",
+  "--serve",
+  "--layoutconfig",
+  "--full",
+  "--push",
+  "--home",
+  "--search",
+  "--path",
+  "--output",
+  "--layouts-dir",
+  "--interactive",
+  "-i",
+  "--no-interactive",
+  "--yes",
+  "-y",
+  "--ai",
+  "--pages-actions",
+]);
+
+/** Options that carry a value; `--name=value` spellings must never be read as an owner/repo. */
+const VALUE_OPTION_PREFIXES = ["--owner", "--repo", "--path", "--home", "--output", "--layouts-dir", "--search"];
+
+function readOptionValue(args: string[], optionName: string): string {
+  const equalsArg = args.find((a) => a.startsWith(`${optionName}=`));
+  if (equalsArg) return equalsArg.slice(optionName.length + 1).trim();
+  const index = args.indexOf(optionName);
+  if (index >= 0) {
+    const next = args[index + 1];
+    if (next && !next.startsWith("--")) return next.trim();
+  }
+  return "";
+}
+
+/** Legacy `--<owner> --<repo>` spelling: every dashed arg that is not a known flag or option. */
+function readFallbackOwnerRepo(args: string[]): string[] {
+  return args
+    .filter((a) => a.startsWith("--") && !KNOWN_FLAGS.has(a))
+    .filter((a) => !VALUE_OPTION_PREFIXES.some((prefix) => a.startsWith(prefix)))
+    .map((a) => a.slice(2).trim())
+    .filter(Boolean);
+}
+
+/** New verb aliases (Phase 6) that map onto existing modes without new modes. */
+function readCommandAliases(args: string[]): { isDocument: boolean; isDeploy: boolean; aiCommand?: string } {
+  const command = args[0];
+  if (command === "ai") return { isDocument: false, isDeploy: false, aiCommand: args[1] };
+  if (command === "document") return { isDocument: true, isDeploy: false, aiCommand: args[1] ?? "repo" };
+  if (command?.startsWith("document:")) return { isDocument: true, isDeploy: false, aiCommand: command.split(":")[1] };
+  return { isDocument: false, isDeploy: command === "deploy" || command === "pages", aiCommand: undefined };
+}
+
+function resolveMode(flags: { isAi: boolean; isHome: boolean; isFull: boolean }): CliMode {
+  if (flags.isAi) return "ai";
+  if (flags.isHome) return "home";
+  if (flags.isFull) return "full";
+  return "config-only";
+}
+
+function resolveRepositorySearch(searchRaw: string, isHome: boolean): boolean | undefined {
+  if (searchRaw === "true") return true;
+  if (searchRaw === "false") return false;
+  return isHome ? DEFAULTS.home.repositorySearch : undefined;
+}
+
+export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOptions {
+  const args = argv.slice(2);
+
+  const docsPath = readOptionValue(args, "--path");
+  const outputDir = readOptionValue(args, "--output");
+  const layoutsDir = readOptionValue(args, "--layouts-dir");
+  const searchRaw = readOptionValue(args, "--search");
+
+  const fallbackDashedArgs = readFallbackOwnerRepo(args);
+  const githubOwner = readOptionValue(args, "--owner") || fallbackDashedArgs[0] || "";
+  const githubRepo = readOptionValue(args, "--repo") || fallbackDashedArgs[1] || "";
+
+  const { isDocument, isDeploy, aiCommand } = readCommandAliases(args);
+
+  const isBuild = args.includes("--build") || env.GITPAGEDOCS_BUILD === "1";
+  const isServe = args.includes("--serve");
+  const useLocalLayoutConfig = args.includes("--layoutconfig");
+  const shouldPush = args.includes("--push") || isDeploy;
+  const isHome = args.includes("--home");
+  const isInteractive = args.includes("--interactive") || args.includes("-i");
+  const isAi = args[0] === "ai" || args.includes("--ai") || isDocument;
+
+  const mode = resolveMode({ isAi, isHome, isFull: args.includes("--full") });
+  const repositorySearch = resolveRepositorySearch(searchRaw, isHome);
+  const defaultOutputDir = isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir;
+
+  return {
+    isBuild,
+    isServe,
+    mode,
+    aiCommand,
+    outputDir: outputDir || defaultOutputDir,
+    layoutsDir: normalizeLayoutsDir(layoutsDir || DEFAULTS.layoutsDir),
+    useLocalLayoutConfig,
+    shouldPush,
+    githubOwner,
+    githubRepo,
+    docsPath,
+    basePath: docsPath,
+    repositorySearch,
+    isInteractive,
+    hasArgs: args.length > 0,
+    explicit: {
+      useLocalLayoutConfig,
+      layoutsDir: Boolean(layoutsDir),
+      githubOwner: Boolean(githubOwner),
+      githubRepo: Boolean(githubRepo),
+      outputDir: Boolean(outputDir),
+    },
+  };
+}

package/presentation/options/resolver.ts

@@ -0,0 +1,46 @@
+import type { CliOptions } from "../../domain/models/cli-options";
+import { parseCliOptions } from "./parser";
+import {
+  shouldRunInteractive,
+  promptConfigOnlyOptions,
+  promptHomeOptions,
+  promptDeployOptions,
+  ensureGitRepoInteractive,
+  interactivePromptsAvailable,
+} from "../ui/prompts";
+import { DEFAULTS } from "./schema";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { detectRepoFromGit } from "../../runtime/git-ops.mjs";
+
+export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Promise<CliOptions> {
+  const parsed = parseCliOptions(argv, env);
+
+  if (parsed.mode === "home") {
+    parsed.repositorySearch = parsed.repositorySearch ?? DEFAULTS.home.repositorySearch;
+    parsed.basePath = parsed.basePath ?? parsed.docsPath ?? DEFAULTS.home.basePath;
+  }
+
+  // `deploy` / `--push` need owner + repo AND a git repo. If anything is
+  // missing, prompt interactively (owner/repo pre-filled from the git origin
+  // remote; offer to `git init`) instead of throwing. In CI/non-TTY we fall
+  // through so the explicit guards in the push flow still fire clearly.
+  if (parsed.shouldPush && interactivePromptsAvailable()) {
+    let resolved = parsed;
+    if (!parsed.githubOwner || !parsed.githubRepo) {
+      const detected = detectRepoFromGit(process.cwd()) as { owner: string; repo: string } | null;
+      resolved = await promptDeployOptions(parsed, detected);
+    }
+    await ensureGitRepoInteractive(process.cwd());
+    return resolved;
+  }
+
+  // Every command prompts in a real terminal; shouldRunInteractive owns the
+  // CI / piped-stdin / --no-interactive opt-outs, and each prompt asks only for
+  // what the command line left unanswered.
+  if (!shouldRunInteractive(argv)) return parsed;
+
+  if (parsed.mode === "home") return promptHomeOptions(parsed);
+  if (parsed.mode === "config-only") return promptConfigOnlyOptions(parsed);
+
+  return parsed;
+}

package/presentation/options/schema.ts

@@ -0,0 +1,14 @@
+import { DEFAULT_LAYOUTS_DIR } from "../../contracts/layouts-paths.mjs";
+
+export const DEFAULTS = {
+  outputDir: "gitpagedocs",
+  /** Standalone layouts home; local layouts are generated here, never in outputDir. */
+  layoutsDir: DEFAULT_LAYOUTS_DIR as string,
+  repositorySearch: false,
+  basePath: "",
+  home: {
+    outputDir: "gitpagedocshome",
+    repositorySearch: false,
+    basePath: "",
+  },
+} as const;

package/presentation/ui/banner.ts

@@ -0,0 +1,13 @@
+export function printBanner(): void {
+  console.log("");
+  console.log("  Git Page Docs");
+  console.log("  by Vidigal-code");
+  console.log("  https://github.com/Vidigal-code/git-page-docs");
+  console.log("");
+}
+
+export function printCredits(): void {
+  console.log("");
+  console.log("  Powered by Vidigal-code - git-page-docs");
+  console.log("");
+}

package/presentation/ui/clack.ts

@@ -0,0 +1,91 @@
+/**
+ * Thin, cancellation-aware wrappers over @clack/prompts. Centralizes the
+ * isCancel handling so prompt modules stay declarative and a Ctrl-C exits
+ * cleanly (mirroring the previous inquirer behaviour).
+ */
+import {
+  text,
+  password,
+  confirm,
+  select,
+  multiselect,
+  isCancel,
+  cancel,
+} from "@clack/prompts";
+
+function exitIfCancelled<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel("Operation cancelled.");
+    process.exit(0);
+  }
+  return value as T;
+}
+
+export interface AskTextOptions {
+  message: string;
+  defaultValue?: string;
+  placeholder?: string;
+  validate?: (value: string) => string | undefined;
+}
+
+export async function askText(options: AskTextOptions): Promise<string> {
+  const result = await text({
+    message: options.message,
+    placeholder: options.placeholder,
+    defaultValue: options.defaultValue,
+    initialValue: undefined,
+    validate: options.validate
+      ? (value) => options.validate?.(value ?? "")
+      : undefined,
+  });
+  return exitIfCancelled(result);
+}
+
+export interface AskPasswordOptions {
+  message: string;
+  validate?: (value: string) => string | undefined;
+}
+
+/** Masked password prompt (input hidden as the user types). */
+export async function askPassword(options: AskPasswordOptions): Promise<string> {
+  const result = await password({
+    message: options.message,
+    validate: options.validate
+      ? (value) => options.validate?.(value ?? "")
+      : undefined,
+  });
+  return exitIfCancelled(result);
+}
+
+export async function askConfirm(message: string, initialValue = false): Promise<boolean> {
+  const result = await confirm({ message, initialValue });
+  return exitIfCancelled(result);
+}
+
+export interface Choice<T extends string> {
+  value: T;
+  label: string;
+  hint?: string;
+}
+
+export async function askSelect<T extends string>(
+  message: string,
+  options: Choice<T>[],
+  initialValue?: T,
+): Promise<T> {
+  // clack's Option<Value> is a conditional type TS can't match against a generic
+  // Choice<T> (identical shape); cast at the boundary, inference flows from initialValue.
+  const result = await select<T>({ message, options: options as never, initialValue });
+  return exitIfCancelled(result);
+}
+
+export async function askMultiSelect<T extends string>(
+  message: string,
+  options: Choice<T>[],
+  initialValues?: T[],
+): Promise<T[]> {
+  const result = await multiselect<T>({ message, options: options as never, initialValues, required: true });
+  return exitIfCancelled(result);
+}
+
+export { intro, outro, note, spinner } from "@clack/prompts";

package/presentation/ui/layouts-prompts.ts

@@ -0,0 +1,124 @@
+/**
+ * Layout-related prompts: where layouts come from, where they are written, and
+ * the opt-in migration away from the legacy `<outputDir>/layouts/` folder.
+ */
+import path from "node:path";
+import { askConfirm, askSelect, askText, note } from "./clack";
+import { interactivePromptsAvailable } from "./tty";
+import {
+  DEFAULT_LAYOUTS_DIR,
+  normalizeLayoutsDir,
+  legacyLayoutsDir,
+} from "../../contracts/layouts-paths.mjs";
+import { planLayoutsMigration } from "../../domain/services/layouts-migration.mjs";
+import { listFilesRecursively, executeLayoutsMigration } from "../../runtime/layouts-migrator.mjs";
+
+type LayoutsSource = "official" | "local";
+
+/** Outcome of a completed migration, for the caller to report. */
+export interface LayoutsMigrationOutcome {
+  from: string;
+  to: string;
+  movedCount: number;
+}
+
+/** Ask whether layouts come from the official remote source or a local folder. */
+export async function askLayoutsSource(useLocal: boolean): Promise<boolean> {
+  const choice = await askSelect<LayoutsSource>(
+    "Layout source",
+    [
+      {
+        value: "official",
+        label: "Official layouts (remote)",
+        hint: "nothing is written to your repository",
+      },
+      {
+        value: "local",
+        label: "Local layouts",
+        hint: `generated into ${DEFAULT_LAYOUTS_DIR}/`,
+      },
+    ],
+    useLocal ? "local" : "official",
+  );
+  return choice === "local";
+}
+
+/** Ask which folder should hold the generated layouts. */
+export async function askLayoutsDir(current: string): Promise<string> {
+  const answer = await askText({
+    message: "Layouts folder:",
+    defaultValue: normalizeLayoutsDir(current),
+    validate: (value) => (value.trim() ? undefined : "A folder name is required."),
+  });
+  return normalizeLayoutsDir(answer);
+}
+
+function toAbsolute(root: string, repoRelative: string): string {
+  return path.join(root, ...repoRelative.split("/"));
+}
+
+/**
+ * Offer to move layouts left behind in the legacy folder.
+ *
+ * Nothing is moved without an explicit confirmation. Outside a TTY the legacy
+ * folder is reported and left alone — the viewer still reads it, so declining
+ * (or automating) never breaks an existing site.
+ *
+ * @returns The outcome when files were moved, otherwise `null`.
+ */
+export async function migrateLegacyLayoutsInteractive(
+  root: string,
+  options: { outputDir: string; layoutsDir: string },
+): Promise<LayoutsMigrationOutcome | null> {
+  const from = legacyLayoutsDir(options.outputDir);
+  const to = normalizeLayoutsDir(options.layoutsDir);
+
+  const plan = planLayoutsMigration({
+    outputDir: options.outputDir,
+    layoutsDir: to,
+    legacyFiles: listFilesRecursively(toAbsolute(root, from)),
+    targetFiles: listFilesRecursively(toAbsolute(root, to)),
+  });
+
+  if (!plan.required) return null;
+
+  if (!interactivePromptsAvailable()) {
+    note(
+      `${plan.files.length} layout file(s) still live in ${plan.from}/.\n` +
+        `The viewer still reads them. Run this in a terminal to move them to ${plan.to}/.`,
+      "Legacy layouts",
+    );
+    return null;
+  }
+
+  const overwriteWarning =
+    plan.overwrites.length > 0
+      ? `\n${plan.overwrites.length} file(s) already in ${plan.to}/ would be replaced.`
+      : "";
+  note(
+    `Found ${plan.files.length} layout file(s) in ${plan.from}/.\n` +
+      `Layouts are now generated in ${plan.to}/.${overwriteWarning}`,
+    "Legacy layouts",
+  );
+
+  const confirmed = await askConfirm(
+    `Move them to ${plan.to}/ now?`,
+    plan.overwrites.length === 0,
+  );
+  if (!confirmed) {
+    note(`Left untouched — the viewer still reads ${plan.from}/.`, "Legacy layouts");
+    return null;
+  }
+
+  const result = executeLayoutsMigration(root, plan);
+
+  if (result.failed.length > 0) {
+    note(
+      `${result.failed.length} file(s) could not be moved:\n` +
+        result.failed.map((entry) => `- ${entry.file}: ${entry.reason}`).join("\n"),
+      "Migration incomplete",
+    );
+  }
+
+  return { from: plan.from, to: plan.to, movedCount: result.moved.length };
+}

package/presentation/ui/prompts.ts

@@ -0,0 +1,147 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { runExecutable } from "../../runtime/exec.mjs";
+import type { CliOptions } from "../../domain/models/cli-options";
+import { DEFAULTS } from "../options/schema";
+import { askText, askConfirm, note } from "./clack";
+import { interactivePromptsAvailable, promptingEnabled } from "./tty";
+import { askLayoutsSource, askLayoutsDir } from "./layouts-prompts";
+
+export { interactivePromptsAvailable };
+
+/**
+ * Every command prompts when it runs in a real terminal, so a bare invocation
+ * reflects what the user actually needs instead of silently taking defaults.
+ * CI, a piped stdin, and an explicit `--no-interactive` / `--yes` / `-y` opt out;
+ * `--interactive` / `-i` remains accepted and reads the same either way.
+ */
+export function shouldRunInteractive(argv: string[]): boolean {
+  return promptingEnabled(argv.slice(2));
+}
+
+export async function promptHomeOptions(parsed: CliOptions): Promise<CliOptions> {
+  const outputDir = await askText({
+    message: "Output directory:",
+    defaultValue: parsed.outputDir ?? DEFAULTS.home.outputDir,
+    validate: (v) => (v?.trim() ? undefined : "Required"),
+  });
+  const repositorySearch = await askConfirm(
+    "Enable repository search home?",
+    parsed.repositorySearch ?? DEFAULTS.repositorySearch,
+  );
+  const basePath = await askText({
+    message: "Base path (e.g. git-page-docs, empty for root):",
+    defaultValue: parsed.basePath ?? DEFAULTS.basePath,
+  });
+
+  return {
+    ...parsed,
+    outputDir: outputDir.trim(),
+    repositorySearch,
+    basePath: basePath?.trim() ?? "",
+  };
+}
+
+/**
+ * Deploy/--push needs a GitHub owner + repo. When they are missing, prompt for
+ * them (pre-filled from the git `origin` remote when available) instead of
+ * crashing with "`--push` requires owner and repo".
+ */
+export async function askOwnerRepo(
+  detected: { owner: string; repo: string } | null,
+  defaults?: { owner?: string; repo?: string },
+): Promise<{ owner: string; repo: string }> {
+  const owner = await askText({
+    message: "GitHub owner (user or organization):",
+    defaultValue: defaults?.owner || detected?.owner || "",
+    validate: (v) => (v?.trim() ? undefined : "Owner is required."),
+  });
+  const repo = await askText({
+    message: "GitHub repository name:",
+    defaultValue: defaults?.repo || detected?.repo || "",
+    validate: (v) => (v?.trim() ? undefined : "Repository is required."),
+  });
+  return { owner: owner.trim(), repo: repo.trim() };
+}
+
+export async function promptDeployOptions(
+  parsed: CliOptions,
+  detected: { owner: string; repo: string } | null,
+): Promise<CliOptions> {
+  note(
+    "Deploy publishes gitpagedocs to GitHub Pages and needs the target\nrepository (owner/repo). Press Enter to accept a detected value.",
+    "GitHub Pages deploy",
+  );
+  const { owner, repo } = await askOwnerRepo(detected, {
+    owner: parsed.githubOwner,
+    repo: parsed.githubRepo,
+  });
+
+  return {
+    ...parsed,
+    githubOwner: owner,
+    githubRepo: repo,
+  };
+}
+
+/**
+ * Deploy/--push needs a git repository in the current folder. When there isn't
+ * one, offer to run `git init` instead of crashing with "not a git repository".
+ * In CI/non-TTY this is a no-op so the downstream guard still reports clearly.
+ */
+export async function ensureGitRepoInteractive(root: string): Promise<void> {
+  if (existsSync(path.join(root, ".git"))) return;
+  if (!interactivePromptsAvailable()) return;
+  const init = await askConfirm(
+    "This folder is not a git repository yet. Initialize one here (git init)?",
+    true,
+  );
+  if (!init) {
+    note("Deploy needs a git repository. Run `git init`, then retry.", "Heads up");
+    return;
+  }
+  try {
+    runExecutable("git", ["init"], { cwd: root, stdio: "ignore" });
+    note("Initialized an empty git repository.", "git");
+  } catch {
+    note("Could not run `git init`. Initialize git manually, then retry.", "git");
+  }
+}
+
+/**
+ * Ask only for what the command line did not already answer, so an explicit
+ * flag is never second-guessed by a prompt.
+ */
+export async function promptConfigOnlyOptions(parsed: CliOptions): Promise<CliOptions> {
+  const useLocalLayoutConfig = parsed.explicit.useLocalLayoutConfig
+    ? parsed.useLocalLayoutConfig
+    : await askLayoutsSource(parsed.useLocalLayoutConfig ?? false);
+
+  const layoutsDir =
+    useLocalLayoutConfig && !parsed.explicit.layoutsDir
+      ? await askLayoutsDir(parsed.layoutsDir)
+      : parsed.layoutsDir;
+
+  const githubOwner = parsed.explicit.githubOwner
+    ? parsed.githubOwner
+    : await askText({
+        message: "GitHub owner (optional):",
+        defaultValue: parsed.githubOwner ?? "",
+      });
+
+  const githubRepo = parsed.explicit.githubRepo
+    ? parsed.githubRepo
+    : await askText({
+        message: "GitHub repo (optional):",
+        defaultValue: parsed.githubRepo ?? "",
+      });
+
+  return {
+    ...parsed,
+    useLocalLayoutConfig,
+    layoutsDir,
+    githubOwner: githubOwner?.trim() ?? "",
+    githubRepo: githubRepo?.trim() ?? "",
+  };
+}

package/presentation/ui/terminal-stream.ts

@@ -0,0 +1,97 @@
+/**
+ * @file terminal-stream.ts
+ * @description Terminal rendering for streamed AI output, non-TTY-first:
+ *   - model text goes to STDOUT (so `chat "q" > out.txt` captures clean content)
+ *   - all chrome (spinner, headers, hints) goes to STDERR
+ *   - colours/spinner are emitted only on a TTY; a pipe gets plain text
+ * Keeps the streaming/rendering side effects in one place, apart from the pure
+ * ChatSession state.
+ */
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+} as const;
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+const SPINNER_INTERVAL_MS = 80;
+
+function stdoutIsTty(): boolean {
+  return Boolean(process.stdout.isTTY);
+}
+
+function stderrIsTty(): boolean {
+  return Boolean(process.stderr.isTTY);
+}
+
+/** Writes model content to stdout (verbatim; the actual deliverable). */
+export function writeContent(text: string): void {
+  process.stdout.write(text);
+}
+
+/** Writes one chrome line to stderr, dimmed on a TTY. */
+export function writeChrome(line: string): void {
+  if (stderrIsTty()) {
+    process.stderr.write(`${ANSI.dim}${line}${ANSI.reset}\n`);
+  } else {
+    process.stderr.write(`${line}\n`);
+  }
+}
+
+/** Colour helpers that no-op when stderr is not a TTY. */
+export function accent(text: string): string {
+  return stderrIsTty() ? `${ANSI.cyan}${text}${ANSI.reset}` : text;
+}
+
+export function danger(text: string): string {
+  return stderrIsTty() ? `${ANSI.red}${text}${ANSI.reset}` : text;
+}
+
+/**
+ * A spinner with elapsed-time readout on stderr. On a non-TTY it prints a
+ * single static line instead of animating, so logs stay clean. `stop()` clears
+ * the line and is idempotent.
+ */
+export class ElapsedSpinner {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private frame = 0;
+  private readonly startedAt = Date.now();
+
+  constructor(private readonly label: string) {}
+
+  start(): void {
+    if (!stderrIsTty()) {
+      process.stderr.write(`${this.label}...\n`);
+      return;
+    }
+    this.render();
+    this.timer = setInterval(() => this.render(), SPINNER_INTERVAL_MS);
+  }
+
+  private render(): void {
+    const seconds = ((Date.now() - this.startedAt) / 1000).toFixed(1);
+    const glyph = SPINNER_FRAMES[this.frame % SPINNER_FRAMES.length];
+    this.frame += 1;
+    process.stderr.write(`\r${ANSI.cyan}${glyph}${ANSI.reset} ${ANSI.dim}${this.label} ${seconds}s${ANSI.reset}\x1b[K`);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (stderrIsTty()) {
+      process.stderr.write("\r\x1b[K");
+    }
+  }
+
+  /** Elapsed seconds since construction. */
+  elapsedSeconds(): number {
+    return (Date.now() - this.startedAt) / 1000;
+  }
+}
+
+export const supportsColor = stderrIsTty;
+export const isInteractiveOutput = stdoutIsTty;

package/presentation/ui/tty.ts

@@ -0,0 +1,37 @@
+/**
+ * Terminal capability detection.
+ *
+ * Kept in its own module so every prompt module can ask "may I prompt?" without
+ * importing the prompt modules themselves (which would be circular).
+ */
+
+/** Environment variables that mark a non-interactive automated run. */
+const CI_ENV_FLAGS = ["CI", "GITHUB_ACTIONS"] as const;
+
+/** Flags that explicitly opt out of prompting. */
+export const NON_INTERACTIVE_FLAGS = ["--no-interactive", "--yes", "-y"] as const;
+
+function isCiOrNonTty(): boolean {
+  for (const flag of CI_ENV_FLAGS) {
+    if (process.env[flag] === "true") return true;
+  }
+  return Boolean(process.stdin && !process.stdin.isTTY);
+}
+
+/** True when clack prompts can run (interactive TTY, not CI). */
+export function interactivePromptsAvailable(): boolean {
+  return !isCiOrNonTty();
+}
+
+/** True when the user explicitly asked for a non-interactive run. */
+export function promptingOptedOut(args: readonly string[]): boolean {
+  return NON_INTERACTIVE_FLAGS.some((flag) => args.includes(flag));
+}
+
+/**
+ * True when prompts should run for this invocation: a real terminal, and no
+ * explicit opt-out.
+ */
+export function promptingEnabled(args: readonly string[]): boolean {
+  return interactivePromptsAvailable() && !promptingOptedOut(args);
+}