@sous-io/sous 0.2.36 → 1.0.1

package/src/base-command.ts

@@ -1,457 +0,0 @@
-import path from "node:path";
-import { Command, Flags } from "@oclif/core";
-import {
-  discoverConfig,
-  expandHome,
-  formatNotFoundMessage,
-  refreshDiscoveredConfig,
-  resolveConfigFlag,
-  type DiscoveredConfig,
-} from "./lib/config-discovery.js";
-import { loadEnvFiles } from "./lib/env-local.js";
-import { loadSettings, type ConfigContext, type Settings } from "./lib/settings.js";
-import { isInteractive } from "./lib/interactive.js";
-import { displayError, displayErrorBlock, header, log, warning } from "./utils/formatting.js";
-import { nonInteractiveFlag } from "./utils/flags.js";
-import { reportCommandError } from "./utils/command-errors.js";
-
-/**
- * Base class for all CLI commands.
- *
- * Startup sequence:
- *   1. Locate the config. Primary-config precedence, highest first:
- *      `--config`/`-c`/`--sous-config` flag > `SOUS_CONFIG` env >
- *      `--sous-dir` flag > `SOUS_DIR` env > walk up from cwd looking for a
- *      `.sous/` directory holding sous.config.{js,mjs,json,yaml}. The conf.d
- *      drop-in directory precedence is: `--sous-confd` flag > `SOUS_CONFD` env >
- *      `<sousDir>/conf.d`. Env vars are read from the REAL environment only
- *      (never `.env.local`), because they decide where `.env.local` lives.
- *   2. Load `<.sous>/.env.local`, then `<.sous>/.env`, into process.env (never
- *      overwriting real env vars). Precedence: shell > .env.local > .env.
- *   3. Load every config layer (primary + conf.d) through the config kernel and
- *      deep-merge them. Variable resolution happens later, per command.
- *
- * There is no user-level config: nothing is read from `~/.sous`.
- *
- * Every command also carries `--non-interactive`, which tells sous never to ask
- * a question: a run that would have prompted fails instead, naming the prompt
- * and the flag (or environment variables) that would have answered it, and this
- * class prints the command's own help underneath that error. The rule itself
- * lives in `lib/interactive.ts`, which also treats a truthy `CI` and a
- * non-terminal stdin or stdout the same way.
- */
-/**
- * What the config-locating flags and environment said on this run, resolved to
- * absolute paths but not yet turned into a config.
- */
-export type ConfigLocator = {
-  /** The working directory discovery started from. */
-  cwd: string;
-  /**
-   * The explicit config location, when one was given: the resolved path and
-   * the flag or environment variable that supplied it (`--config`,
-   * `--sous-config`, `SOUS_CONFIG`, `--sous-dir` or `SOUS_DIR`).
-   */
-  primary?: { value: string; source: string };
-  /** The conf.d directory override, when `--sous-confd` or `SOUS_CONFD` gave one. */
-  confDirOverride?: string;
-};
-
-export abstract class BaseCommand extends Command {
-  static baseFlags = {
-    config: Flags.string({
-      char: "c",
-      description:
-        "Path to a sous config file (or a directory containing one). Overrides .sous/ discovery",
-    }),
-    "sous-config": Flags.string({
-      description:
-        "Alias of --config: path to a sous config file (or a directory containing one)",
-    }),
-    "sous-dir": Flags.string({
-      description: "Path to the .sous directory to use (overrides walk-up discovery)",
-    }),
-    "sous-confd": Flags.string({
-      description: "Path to the conf.d drop-in layer directory (overrides <sousDir>/conf.d)",
-    }),
-    "non-interactive": nonInteractiveFlag(),
-  };
-
-  /**
-   * Whether a run of this command needs a project config to exist. Every
-   * command that works on a project leaves this true, and a run that finds no
-   * config fails before `run()` with the "No sous config found" block. The one
-   * command whose job is to CREATE the config sets it false: discovery still
-   * runs, so the config-locating flags still say where the project is, but
-   * finding nothing is the expected case rather than an error, and `settings`
-   * stays unset until `adoptConfig` is given the config that was written.
-   */
-  static requiresConfig = true;
-
-  /**
-   * Whether a config that cannot be located or loaded stops this command. It
-   * is false on every command but the one whose job may be to repair that
-   * config: `sous update` installs a sous that may understand a config this
-   * copy rejects (one written for a newer version, say). When true, a failure
-   * to locate or load the config becomes one warning, naming the config and
-   * quoting the error, and the run carries on with no config adopted:
-   * `hasConfig` is false, the env files are not applied, and `rejectedConfig`
-   * says where the config that failed to load was, when discovery found it.
-   * It only changes what a FAILURE does; finding no config at all is still
-   * decided by `requiresConfig`.
-   */
-  static toleratesConfigErrors = false;
-
-  protected settings!: Settings;
-
-  /** Where the active config was found. */
-  protected configContext!: ConfigContext;
-
-  /**
-   * What the config-locating flags and environment said, before discovery
-   * turned it into a config. A command that runs without a config reads the
-   * project's location from here.
-   */
-  protected configLocator!: ConfigLocator;
-
-  /** The full discovery result, including how the config was located. */
-  protected discovered!: DiscoveredConfig;
-
-  /**
-   * The config discovery found but could not load, on a command that
-   * `toleratesConfigErrors`. Undefined when the config loaded, when there was
-   * none, or when the failure came before any config file was identified.
-   */
-  protected rejectedConfig?: { configPath: string; sousDir: string };
-
-  /**
-   * The real shell environment, snapshotted BEFORE the `.sous/` env files are
-   * injected into `process.env`. The variables layer needs it to tell a value
-   * the shell supplied from one an env file supplied; after injection the two
-   * are indistinguishable.
-   */
-  protected shellEnv: NodeJS.ProcessEnv = {};
-
-  /**
-   * Emits the decorative CLI header during init(). The default writes it to
-   * stdout. Commands whose stdout must stay machine-readable (the `sous config *`
-   * JSON commands) override this to route the banner to stderr.
-   */
-  protected emitHeader(): void {
-    header();
-  }
-
-  /**
-   * Line sink for error rendering during init()/catch(). Defaults to stdout (via
-   * `log`). Commands whose stdout must stay machine-readable (the `sous config *`
-   * JSON commands) override this to route error text to stderr, so a broken
-   * config never corrupts a piped stdout stream (e.g. `sous config show | jq`).
-   */
-  protected errorSink: (line: string) => void = log;
-
-  /**
-   * Whether this run may ask the user a question. One rule, shared by every
-   * prompt in sous: see `lib/interactive.ts`.
-   */
-  protected get interactive(): boolean {
-    return isInteractive();
-  }
-
-  async init(): Promise<void> {
-    await super.init();
-    this.emitHeader();
-
-    // Read config-locating flags off argv directly. oclif's parse() runs inside
-    // each command's run(), which is too late: the config (and thus the env
-    // files) must be located before any variable resolution. `SOUS_*` env vars
-    // are read from the REAL environment here, BEFORE loadEnvFiles below, because
-    // they decide where `.env.local` itself lives.
-    const cwd = process.cwd();
-    const configFlag = blankToUndefined(readConfigFlagFromArgv(this.argv));
-    const sousConfigFlag = blankToUndefined(readLongFlagFromArgv(this.argv, "sous-config"));
-    const sousDirFlag = blankToUndefined(readLongFlagFromArgv(this.argv, "sous-dir"));
-    const sousConfdFlag = blankToUndefined(readLongFlagFromArgv(this.argv, "sous-confd"));
-
-    // Empty-string env vars are coerced to undefined and treated as unset. A
-    // bare `export SOUS_CONFD=` (or a variable that expands empty) must not turn
-    // cwd into the conf.d dir, and an empty SOUS_CONFIG/SOUS_DIR must not mask a
-    // lower-precedence source or disable walk-up discovery.
-    const sousConfdEnv = blankToUndefined(process.env.SOUS_CONFD);
-    const sousConfigEnv = blankToUndefined(process.env.SOUS_CONFIG);
-    const sousDirEnv = blankToUndefined(process.env.SOUS_DIR);
-
-    // conf.d directory: --sous-confd flag > SOUS_CONFD env > <sousDir>/conf.d.
-    const confdRaw = sousConfdFlag ?? sousConfdEnv;
-    const confDirOverride =
-      confdRaw !== undefined ? path.resolve(cwd, expandHome(confdRaw)) : undefined;
-
-    // Primary config, highest precedence first: --config/-c/--sous-config flag,
-    // SOUS_CONFIG env, --sous-dir flag, SOUS_DIR env. All resolve with the same
-    // rules as --config (a file, or a directory holding/containing a config).
-    // The paired source label is carried through to resolveConfigFlag so an
-    // error names the source the user actually set (not always `--config`).
-    const primaryCandidates: [string | undefined, string][] = [
-      [configFlag, "--config"],
-      [sousConfigFlag, "--sous-config"],
-      [sousConfigEnv, "SOUS_CONFIG"],
-      [sousDirFlag, "--sous-dir"],
-      [sousDirEnv, "SOUS_DIR"],
-    ];
-    const primary = primaryCandidates.find(([value]) => value !== undefined);
-    const { requiresConfig, toleratesConfigErrors } = this.constructor as typeof BaseCommand;
-
-    this.configLocator = {
-      cwd,
-      primary:
-        primary !== undefined
-          ? { value: path.resolve(cwd, expandHome(primary[0] as string)), source: primary[1] }
-          : undefined,
-      confDirOverride,
-    };
-
-    let discovered: DiscoveredConfig | null;
-
-    if (primary !== undefined) {
-      const [primarySource, sourceLabel] = primary as [string, string];
-      try {
-        discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
-      } catch (error) {
-        if (toleratesConfigErrors) {
-          return this.warnConfigNotLoaded(
-            error,
-            `the project config at ${this.configLocator.primary?.value} (named by ${sourceLabel})`
-          );
-        }
-        // A command that creates the config is pointed at a place with none in
-        // it by design; the flag still says where, so this is not a failure.
-        if (!requiresConfig) return;
-        displayError(error instanceof Error ? error.message : String(error), this.errorSink);
-        return this.exit(1);
-      }
-    } else {
-      try {
-        discovered = discoverConfig(cwd, confDirOverride);
-      } catch (error) {
-        if (!toleratesConfigErrors) throw error;
-        return this.warnConfigNotLoaded(error, `the project config it found searching up from ${cwd}`);
-      }
-    }
-
-    if (!discovered) {
-      if (!requiresConfig) return;
-      displayErrorBlock(formatNotFoundMessage(), this.errorSink);
-      return this.exit(1);
-    }
-
-    await this.adoptConfig(discovered);
-  }
-
-  /** True once a config has been discovered or adopted and its settings loaded. */
-  protected get hasConfig(): boolean {
-    return this.discovered !== undefined;
-  }
-
-  /**
-   * Makes a discovered config THE config for the rest of the run: loads its
-   * env files, enumerates its layers again now that `SOUS_HOME` may have
-   * changed, and loads the settings. `init()` calls it for the config discovery
-   * found; a command that creates a config calls it for the one it wrote, so
-   * both go through the same steps in the same order.
-   *
-   * @param discovered - The config to adopt.
-   */
-  protected async adoptConfig(discovered: DiscoveredConfig): Promise<void> {
-    // Inject .sous/.env.local and .sous/.env before anything resolves variables,
-    // keeping a copy of what the shell itself set so the variables layer can
-    // still tell the two apart.
-    this.shellEnv = { ...process.env };
-    loadEnvFiles(discovered.sousDir);
-
-    // Enumerated a second time now that the env files are loaded: `SOUS_HOME` is
-    // file-settable, and it decides where the store holding a subscribed
-    // recipe's config layers is. A first pass already ran during discovery, when
-    // only the real environment was known.
-    let refreshed: DiscoveredConfig;
-    try {
-      refreshed = refreshDiscoveredConfig(discovered);
-    } catch (error) {
-      if (this.toleratesConfigErrors) return this.rejectConfig(discovered, error);
-      displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
-      return this.exit(1);
-    }
-
-    this.discovered = refreshed;
-    this.configContext = {
-      sousDir: refreshed.sousDir,
-      configPath: refreshed.configPath,
-      confDir: refreshed.confDir,
-      layerPaths: refreshed.layerPaths,
-    };
-
-    // Routed through the command's error sink, not stdout: a recipe layer
-    // warning must not land in the middle of `sous config show | jq`.
-    for (const notice of refreshed.recipeLayerWarnings) warning(notice, this.errorSink);
-
-    try {
-      this.settings = await loadSettings(refreshed);
-    } catch (error) {
-      if (this.toleratesConfigErrors) return this.rejectConfig(refreshed, error);
-      displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
-      return this.exit(1);
-    }
-  }
-
-  /** The `toleratesConfigErrors` setting of the running command's class. */
-  private get toleratesConfigErrors(): boolean {
-    return (this.constructor as typeof BaseCommand).toleratesConfigErrors;
-  }
-
-  /**
-   * Undoes a config adoption that failed on a command that tolerates it: the
-   * env files it injected are taken back out of `process.env`, nothing is left
-   * adopted, and one warning says what happened.
-   */
-  private rejectConfig(discovered: DiscoveredConfig, error: unknown): void {
-    for (const name of Object.keys(process.env)) {
-      if (!(name in this.shellEnv)) delete process.env[name];
-    }
-    this.shellEnv = {};
-    this.discovered = undefined as unknown as DiscoveredConfig;
-    this.configContext = undefined as unknown as ConfigContext;
-    this.rejectedConfig = { configPath: discovered.configPath, sousDir: discovered.sousDir };
-    this.warnConfigNotLoaded(error, `the project config at ${discovered.configPath}`);
-  }
-
-  /**
-   * The one warning a command that tolerates config errors prints in place of
-   * failing.
-   *
-   * @param error - What locating or loading the config threw.
-   * @param config - Which config: its file, or where it was looked for.
-   */
-  private warnConfigNotLoaded(error: unknown, config: string): void {
-    const message = error instanceof Error ? error.message : String(error);
-    warning(
-      `Sous could not load ${config}, so this command carries on without it.\n` +
-        "\n" +
-        "The error was:\n" +
-        message,
-      this.errorSink
-    );
-  }
-
-  /**
-   * Renders any failure as a plain, readable message instead of an oclif stack
-   * trace: a config mistake, a mistyped command line, or a question sous could
-   * not ask. A stack pointing into oclif's parser or into sous's internals
-   * tells the user nothing about the mistake they need to fix, so it is printed
-   * only when `SOUS_DEBUG` asks for it. The rules live in
-   * `utils/command-errors.ts`, so every command in sous fails the same way.
-   *
-   * A clean `this.exit()` and a command rendering JSON still belong to oclif,
-   * and fall through to its handling untouched.
-   */
-  protected async catch(error: Error & { exitCode?: number }): Promise<unknown> {
-    const exitCode = await reportCommandError(this, error, { write: this.errorSink });
-    if (exitCode === undefined) return super.catch(error);
-    return this.exit(exitCode);
-  }
-
-  /**
-   * Re-runs discovery and reloads settings, committing the result onto this
-   * command only if everything loads cleanly (last-good semantics: a failed
-   * reload throws and leaves the previously loaded config untouched).
-   *
-   * Used by watch mode when a full-rebuild path (the config file, the conf.d
-   * directory, or the templating dir) changes: conf.d layer files can appear or
-   * disappear at runtime, so the ordered layer list must be rebuilt (and the
-   * duplicate-baseName check re-run) before settings reload.
-   */
-  protected async reloadDiscoveredConfig(): Promise<void> {
-    const refreshed = refreshDiscoveredConfig(this.discovered);
-    const reloaded = await loadSettings(refreshed);
-
-    // Commit only after a clean load, so a broken edit keeps the last-good config.
-    this.discovered = refreshed;
-    this.configContext = {
-      sousDir: refreshed.sousDir,
-      configPath: refreshed.configPath,
-      confDir: refreshed.confDir,
-      layerPaths: refreshed.layerPaths,
-    };
-    this.settings = reloaded;
-  }
-
-  /**
-   * Human-readable label for the configured project: the config's `name` when
-   * set, otherwise the basename of the directory holding `.sous/`.
-   */
-  protected get projectLabel(): string {
-    return this.settings.name ?? path.basename(path.dirname(this.configContext.sousDir));
-  }
-}
-
-/**
- * Pulls the value of `--config` / `-c` out of a raw argv array.
- * Supports `--config X`, `--config=X`, `-c X`, and `-cX`.
- *
- * Scanning stops at a bare `--`: anything after it belongs to a launched tool
- * (see `launch`'s pass-through args), never to sous.
- *
- * @param argv - Raw arguments (oclif's `this.argv`, i.e. argv minus the command).
- * @returns The flag value, or undefined when the flag is absent.
- */
-export function readConfigFlagFromArgv(argv: string[]): string | undefined {
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-
-    if (arg === "--") return undefined;
-    if (arg === "--config" || arg === "-c") return argv[i + 1];
-    if (arg.startsWith("--config=")) return arg.slice("--config=".length);
-    if (arg.startsWith("-c") && arg.length > 2 && !arg.startsWith("-c-")) return arg.slice(2);
-  }
-  return undefined;
-}
-
-/**
- * Coerces an empty or whitespace-only string to `undefined`, passing every other
- * value through unchanged.
- *
- * Config-locating inputs (`SOUS_CONFIG`, `SOUS_DIR`, `SOUS_CONFD`, and their flag
- * aliases) must treat an empty value as "unset", never as a real path. A bare
- * `export SOUS_CONFD=` (or a variable that expands empty) would otherwise resolve
- * to cwd and load every file in the working directory as a config layer; an empty
- * `SOUS_CONFIG` / `SOUS_DIR` would mask a lower-precedence source and disable
- * walk-up discovery. Normalising to `undefined` up front lets the plain `??`
- * precedence chain fall through correctly.
- */
-export function blankToUndefined(value: string | undefined): string | undefined {
-  if (value === undefined) return undefined;
-  return value.trim() === "" ? undefined : value;
-}
-
-/**
- * Pulls the value of a long-only flag (`--<flagName> VALUE` or
- * `--<flagName>=VALUE`) out of a raw argv array. Used for the `--sous-config`,
- * `--sous-dir` and `--sous-confd` aliases, which (like `--config`) must be
- * read before oclif's parse() so the config is located before env files load.
- *
- * Scanning stops at a bare `--` for the same reason as `readConfigFlagFromArgv`:
- * anything after it belongs to a launched tool, never to sous.
- *
- * @param argv - Raw arguments (oclif's `this.argv`).
- * @param flagName - The flag name without leading dashes (e.g. `sous-dir`).
- * @returns The flag value, or undefined when the flag is absent (or has no value).
- */
-export function readLongFlagFromArgv(argv: string[], flagName: string): string | undefined {
-  const long = `--${flagName}`;
-  const eq = `${long}=`;
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-
-    if (arg === "--") return undefined;
-    if (arg === long) return argv[i + 1];
-    if (arg.startsWith(eq)) return arg.slice(eq.length);
-  }
-  return undefined;
-}

package/src/commands/build.ts

@@ -1,181 +0,0 @@
-import { Flags } from "@oclif/core";
-import { BaseCommand } from "../base-command.js";
-import { runProjectBuild } from "../lib/build-service.js";
-import { PidService } from "../lib/pid-service.js";
-import { resolveRootScope } from "../lib/settings.js";
-import { resolveStoreSettings } from "../lib/repos/store/settings.js";
-import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
-import { buildReloadWatchConfig, startConfigReloadWatch } from "../lib/watch-loop.js";
-import type { WatchHandle } from "../lib/watch-service.js";
-import { WatchService } from "../lib/watch-service.js";
-import { log, paragraph, showCommandVars } from "../utils/formatting.js";
-
-export default class Build extends BaseCommand {
-  static description =
-    "Compile this project's outputs and remove the ones its config no longer produces";
-
-  static examples = [
-    "<%= config.bin %> build",
-    "<%= config.bin %> build --no-prune",
-    "<%= config.bin %> build --rebuild",
-    "<%= config.bin %> build --dry-run",
-  ];
-
-  static flags = {
-    ...BaseCommand.baseFlags,
-    "no-prune": Flags.boolean({
-      description: "Skip the prune step",
-      default: false,
-    }),
-    "no-compile": Flags.boolean({
-      description: "Skip the compile step (prune only)",
-      default: false,
-    }),
-    rebuild: Flags.boolean({
-      description: "Ignore cached hashes and reprocess all outputs",
-      default: false,
-    }),
-    "dry-run": Flags.boolean({
-      description: "Print what would be written/pruned without making changes",
-      default: false,
-    }),
-    strict: Flags.boolean({
-      description: "Treat compile warnings as errors",
-      default: false,
-    }),
-    watch: Flags.boolean({
-      char: "w",
-      description: "Watch source files and rebuild on changes",
-      default: false,
-    }),
-  };
-
-  async run(): Promise<void> {
-    const { flags } = await this.parse(Build);
-
-    showCommandVars({
-      Project: this.projectLabel,
-      Config: this.configContext.configPath,
-      Rebuild: flags.rebuild,
-      "Dry Run": flags["dry-run"],
-      "No Compile": flags["no-compile"],
-      "No Prune": flags["no-prune"],
-    });
-
-    const buildOptions = {
-      strict: flags.strict,
-      rebuild: flags.rebuild,
-      dryRun: flags["dry-run"],
-      noCompile: flags["no-compile"],
-      noPrune: flags["no-prune"],
-    };
-
-    const success = await runProjectBuild({
-      settings: this.settings,
-      configContext: this.configContext,
-      shellEnv: this.shellEnv,
-      options: buildOptions,
-    });
-
-    if (!success && !flags.watch) {
-      this.exit(1);
-    }
-
-    if (flags.watch) {
-      const rootScope = resolveRootScope(this.settings, this.configContext);
-
-      // --- PID file enforcement ---
-      const pidService = new PidService();
-      const pidFilePath = pidService.getFilePath(rootScope);
-      await pidService.acquire(pidFilePath, this.projectLabel);
-
-      const cleanup = async (watchHandle?: WatchHandle) => {
-        if (process.stdin.isTTY) {
-          process.stdin.setRawMode(false);
-        }
-        process.stdin.pause();
-        if (watchHandle) await watchHandle.stop();
-        await pidService.release(pidFilePath);
-      };
-
-      process.on("SIGINT", () => { void cleanup().then(() => process.exit(0)); });
-      process.on("SIGTERM", () => { void cleanup().then(() => process.exit(0)); });
-
-      const watchService = new WatchService();
-
-      // Reruns the build with the command's current settings. Called for
-      // partial rebuilds (with the changed file) and, after a clean reload, for
-      // full rebuilds, which prepare the recipes again the way the first build did.
-      const rebuild = async (changedFile?: string) => {
-        // A failed rebuild has already listed its errors, and the watch keeps
-        // running so the next save can fix them.
-        await runProjectBuild({
-          settings: this.settings,
-          configContext: this.configContext,
-          shellEnv: this.shellEnv,
-          heading: "Rebuilding",
-          options: {
-            ...buildOptions,
-            // --rebuild means full clean build on every trigger; skip partial optimisation
-            changedFile: buildOptions.rebuild ? undefined : changedFile,
-          },
-        });
-      };
-
-      const { handle, triggerFullRebuild } = startConfigReloadWatch({
-        watchService,
-        buildWatchConfig: () => buildReloadWatchConfig(this.settings, this.configContext),
-        rebuild,
-        reloadConfig: () => this.reloadDiscoveredConfig(),
-      });
-
-      // Watch mode polls upstream for the repositories that prefer a newer
-      // in-range version. The poll is cheap (one index request per repository)
-      // and a failure never breaks the watch; the last good answer stands.
-      const pollSeconds = resolveStoreSettings(this.settings).watchPollSeconds;
-      if (pollSeconds > 0) {
-        const repositories = subscriptionServiceFor({
-          configContext: this.configContext,
-          settings: this.settings,
-          shellEnv: this.shellEnv,
-        });
-        const poll = setInterval(() => {
-          void repositories
-            .checkUpstream()
-            .then(async (report) => {
-              if (report.updated.length === 0) return;
-              for (const change of report.updated) {
-                paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
-              }
-              await triggerFullRebuild("A newer recipe version arrived upstream.");
-            })
-            .catch(() => {
-              // checkUpstream already reports its own failures as warnings.
-            });
-        }, pollSeconds * 1000);
-        poll.unref();
-      }
-
-      // Display the interactive prompt
-      log("[ Press Q to quit  |  any other key: rebuild ]");
-
-      if (process.stdin.isTTY) {
-        process.stdin.setRawMode(true);
-        process.stdin.resume();
-        process.stdin.setEncoding("utf8");
-
-        process.stdin.on("data", (key: string) => {
-          // q, Q, or Ctrl+C → clean exit
-          if (key === "q" || key === "Q" || key === "\u0003") {
-            void cleanup(handle.current ?? undefined).then(() => process.exit(0));
-            return;
-          }
-          // Any other key → trigger a full rebuild immediately (bypass debounce)
-          void triggerFullRebuild("Manual rebuild triggered.");
-        });
-      }
-
-      await new Promise(() => {}); // keep process alive
-    }
-  }
-}