create-procode 0.0.0-stage → 1.0.0

package/src/cli.mjs

@@ -0,0 +1,392 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { parseArgs, helpText } from "./args.mjs";
+import { ask, confirm, closePrompt, isInteractive } from "./prompt.mjs";
+import { c, log, step, ok, warn, info } from "./log.mjs";
+import { buildDependencies, buildDevDependencies, PINNED_SET, resolveDependencySet } from "./deps.mjs";
+import {
+  BASE_DIR,
+  copyTree,
+  inspectTarget,
+  toPackageName,
+  toBasePath,
+  writeJson,
+} from "./scaffold.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf8"));
+
+const DEFAULTS = {
+  name: "procode-app",
+  appCode: "MYAPP",
+  apiUrl: "https://qa.example.com/lowcodev2/api/{APP_CODE}/",
+  authUrl: "https://localhost:7016/token",
+  toolUrl: "https://lowcodeapi-399313.uc.r.appspot.com/",
+  env: "InDraft",
+};
+
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+  for (const pm of ["pnpm", "yarn", "bun"]) if (ua.startsWith(pm)) return pm;
+  return "npm";
+}
+
+function runCommand(cmd, args, cwd) {
+  const res = spawnSync(cmd, args, {
+    cwd,
+    stdio: "inherit",
+    // On Windows npm/pnpm/yarn/git are .cmd shims, which spawn cannot exec directly.
+    shell: process.platform === "win32",
+  });
+  if (res.error) throw res.error;
+  return res.status === 0;
+}
+
+const VALID_APP_CODE = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+async function collectOptions(opts, positionals) {
+  const nonInteractive = opts.yes || !isInteractive();
+  const given = (key) => Object.prototype.hasOwnProperty.call(opts, key);
+
+  // Every question below is skippable: press Enter to take the shown default,
+  // or pass the matching flag and it is never asked at all.
+
+  // ---- project name -------------------------------------------------------
+  let name = opts.name ?? positionals[0];
+  if (!name) {
+    if (nonInteractive) {
+      name = DEFAULTS.name;
+    } else {
+      name = await ask("Project name?", DEFAULTS.name, (v) =>
+        v.includes("/") || v.includes("\\") ? "Use a plain directory name, not a path." : null,
+      );
+    }
+  }
+  const packageName = toPackageName(name);
+
+  // ---- application code ---------------------------------------------------
+  // The core resolves the adapter global by NAME as "getAdapter" +
+  // VITE_APPLICATION_CODE. If the two diverge every adapter silently falls back
+  // to a dummy and no screen ever has data - so this is validated, not free text.
+  const codeFromName = packageName.replace(/[^a-zA-Z0-9]/g, "").toUpperCase() || DEFAULTS.appCode;
+  let appCode = opts["app-code"];
+  if (!appCode) {
+    appCode = nonInteractive
+      ? codeFromName
+      : await ask("Application code (VITE_APPLICATION_CODE)?", codeFromName, (v) =>
+          VALID_APP_CODE.test(v)
+            ? null
+            : "Must start with a letter and hold only letters, digits and underscores - it becomes part of a JS identifier.",
+        );
+  }
+  if (!VALID_APP_CODE.test(appCode)) {
+    throw new Error(
+      "--app-code \"" +
+        appCode +
+        "\" is not usable: it becomes the global name getAdapter" +
+        appCode +
+        ", so it must start with a letter and hold only letters, digits and underscores.",
+    );
+  }
+
+  // ---- base path ----------------------------------------------------------
+  let basePath = opts.base;
+  if (!basePath) {
+    basePath = nonInteractive
+      ? "/" + packageName
+      : await ask("Base path (Vite base + VITE_HOMEPAGE)?", "/" + packageName);
+  }
+  basePath = toBasePath(basePath);
+
+  // ---- service URLs -------------------------------------------------------
+  const apiUrl = (opts["api-url"] ?? DEFAULTS.apiUrl).replace(/\{APP_CODE\}/g, appCode);
+  const authUrl = opts["auth-url"] ?? DEFAULTS.authUrl;
+  const toolUrl = opts["tool-url"] ?? DEFAULTS.toolUrl;
+  const projectEnv = opts.env ?? DEFAULTS.env;
+
+  // ---- booleans -----------------------------------------------------------
+  const pm = opts.pm ?? detectPackageManager();
+  const withSample = given("sample") ? opts.sample : true;
+  const withLint = given("lint") ? opts.lint : true;
+  const latest = given("latest") ? opts.latest : true;
+
+  let install = given("install") ? opts.install : null;
+  if (install === null) {
+    install = nonInteractive ? true : await confirm("Run " + pm + " install now?", true);
+  }
+
+  let git = given("git") ? opts.git : null;
+  if (git === null) git = nonInteractive ? true : await confirm("Initialise a git repository?", true);
+
+  return {
+    name,
+    packageName,
+    appCode,
+    basePath,
+    apiUrl,
+    authUrl,
+    toolUrl,
+    projectEnv,
+    pm,
+    install,
+    git,
+    withSample,
+    withLint,
+    latest,
+    force: Boolean(opts.force),
+  };
+}
+
+function buildTokens(o, set) {
+  return {
+    APP_NAME: o.name,
+    PKG_NAME: o.packageName,
+    APP_CODE: o.appCode,
+    BASE_PATH: o.basePath, // "/myapp"
+    BASE_PATH_SLASH: o.basePath.endsWith("/") ? o.basePath : o.basePath + "/", // "/myapp/"
+    API_BASE_URL: o.apiUrl,
+    AUTH_URL: o.authUrl,
+    TOOL_BASE_URL: o.toolUrl,
+    PROJECT_ENV: o.projectEnv,
+    GENERATOR_VERSION: PKG.version,
+    // Rendered from the same set package.json is written from, so the
+    // generated README cannot drift from the versions it pins.
+    REACT_RANGE: set.peers.react ?? "",
+    PROCODE_VERSIONS: Object.entries(set.procode)
+      .map(([name, range]) => "| `" + name + "` | " + range + " |")
+      .join("\n"),
+  };
+}
+
+/** Remove the sample screen and unwire it, when --no-sample was passed. */
+function stripSample(root) {
+  fs.rmSync(path.join(root, "src", "Module", "Sample"), { recursive: true, force: true });
+  fs.rmSync(path.join(root, "src", "AdapterProvider", "SampleContacts.ts"), { force: true });
+  fs.rmSync(path.join(root, "src", "Factory", "Actions", "sampleContacts.ts"), { force: true });
+
+  // The registry keeps the two generic actions and the custom-widget pair;
+  // only the sample-screen stand-ins go.
+  fs.writeFileSync(
+    path.join(root, "src", "CustomAction.ts"),
+    [
+      'import { setField } from "./Factory/Actions/setField";',
+      'import { myAction, suggestReferenceCode } from "./Factory/Actions/myAction";',
+      "",
+      "/**",
+      " * Extension point 4 of 5: custom actions, resolved by a CUS_-prefixed key.",
+      " *",
+      " * Resolution is custom -> template -> standard. A key no tier knows is logged",
+      ' * and toasted as "This action is not available". A Map, not an object literal:',
+      ' * on a plain object, actionMap["constructor"] returns a function.',
+      " *",
+      " * Write a custom action only for logic none of the standard keys expresses,",
+      " * and NEVER to make an HTTP call.",
+      " */",
+      "class CustomActionFactory {",
+      "  private actionMap = new Map<string, (props: any, ...args: any[]) => any>([",
+      '    ["CUS_SET_FIELD", setField],',
+      '    ["CUS_MY_ACTION", myAction],',
+      '    ["CUS_SUGGEST_CODE", suggestReferenceCode],',
+      "  ]);",
+      "",
+      "  getAction(key: string) {",
+      "    return this.actionMap.get(key) ?? null; // never throw",
+      "  }",
+      "}",
+      "",
+      "export default CustomActionFactory;",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  fs.writeFileSync(
+    path.join(root, "src", "Module", "index.ts"),
+    [
+      "/**",
+      " * slug -> schema. The slug is the URL segment after the Vite base; the schema",
+      " * is the JSON the core renders. A slug with no branch here is page-not-found.",
+      " */",
+      "export const getSchemaBySlugService = (_slug: string, _appCode: string): any => {",
+      "  return null;",
+      "};",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  fs.writeFileSync(
+    path.join(root, "src", "AdapterProvider", "AdapterFactory.ts"),
+    [
+      "/**",
+      " * screenId -> adapter. Keyed by the `screenId` INSIDE the schema JSON, never by",
+      " * the slug. Read the id out of the file; never guess it.",
+      " *",
+      " * Registered onto window as `getAdapter<APPLICATION_CODE>` by main.tsx.",
+      " */",
+      "export const getAdapter = (_screenId: string): any => {",
+      "  return null;",
+      "};",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+}
+
+export async function run(argv) {
+  const { opts, positionals } = parseArgs(argv);
+
+  if (opts.help) {
+    log(helpText(PKG.version));
+    return;
+  }
+  if (opts.version) {
+    log(PKG.version);
+    return;
+  }
+
+  log("");
+  log("  " + c.bold(c.magenta("ProCode")) + " " + c.dim("project generator") + " " + c.dim("v" + PKG.version));
+  log("  " + c.dim("React + TypeScript + Vite, wired to the four ProCode libraries"));
+  log("");
+
+  let o;
+  try {
+    o = await collectOptions(opts, positionals);
+  } finally {
+    closePrompt();
+  }
+
+  const targetRoot = path.resolve(process.cwd(), o.name);
+
+  // ---- target directory ---------------------------------------------------
+  const target = inspectTarget(targetRoot);
+  if (target.notADirectory) throw new Error(targetRoot + " exists and is not a directory.");
+  if (!target.empty && !o.force) {
+    const shown = target.conflicts.slice(0, 5).join(", ") + (target.conflicts.length > 5 ? ", ..." : "");
+    throw new Error(
+      targetRoot +
+        " is not empty (" +
+        shown +
+        ").\n  Pick another name, empty the directory, or pass --force to scaffold into it anyway.",
+    );
+  }
+
+  log("");
+  step("Scaffolding into " + c.bold(targetRoot));
+  info("package   " + o.packageName);
+  info("app code  " + o.appCode + "   " + c.dim("(global: getAdapter" + o.appCode + ")"));
+  info("base path " + o.basePath);
+  info("api       " + o.apiUrl);
+  log("");
+
+  // ---- library versions ---------------------------------------------------
+  // The newest published ProCode packages, with the peers and bundled packages
+  // those versions declare. Any failure (offline, a registry without the
+  // packages, a timeout) falls back to the set this generator was tested with.
+  let set = PINNED_SET;
+  if (o.latest) {
+    step("Resolving the latest ProCode library versions from the npm registry");
+    try {
+      set = await resolveDependencySet();
+      ok(
+        Object.entries(set.procode)
+          .map(([name, range]) => name.replace(/^procode-(lowcode-)?/, "") + " " + range.replace(/^\^/, ""))
+          .join(", "),
+      );
+    } catch (err) {
+      warn("Could not resolve the latest versions (" + (err?.message ?? err) + ").");
+      info("Using the versions this generator was tested with. Pass --no-latest to skip the lookup.");
+    }
+  } else {
+    info("using the tested library versions (--no-latest)");
+  }
+  log("");
+
+  // ---- files --------------------------------------------------------------
+  const tokens = buildTokens(o, set);
+  const created = copyTree(BASE_DIR, targetRoot, tokens);
+  ok(created.length + " project files written");
+
+  if (!o.withSample) {
+    stripSample(targetRoot);
+    info("sample module screen omitted (--no-sample)");
+  }
+
+  if (!o.withLint) {
+    fs.rmSync(path.join(targetRoot, ".eslintrc.cjs"), { force: true });
+    // Its only recommendation is the ESLint extension.
+    fs.rmSync(path.join(targetRoot, ".vscode"), { recursive: true, force: true });
+  }
+
+  // ---- package.json -------------------------------------------------------
+  const pkgFile = path.join(targetRoot, "package.json");
+  const generated = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
+  generated.dependencies = buildDependencies(set);
+  generated.devDependencies = buildDevDependencies({ lint: o.withLint, set });
+  if (!o.withLint) delete generated.scripts.lint;
+  generated._procodeBundled = {
+    note:
+      "Bundled INSIDE the four ProCode packages. Do not add them here and do not bump them independently - react-redux in particular must stay on 8.x, or the core's store becomes invisible and every screen renders blank.",
+    ...set.bundled,
+  };
+  writeJson(pkgFile, generated);
+  ok(
+    "package.json written (" + (set.source === "latest" ? "latest" : "tested") + " versions): " +
+      Object.keys(generated.dependencies).length +
+      " dependencies, " +
+      Object.keys(generated.devDependencies).length +
+      " dev",
+  );
+
+  // ---- git ----------------------------------------------------------------
+  if (o.git) {
+    if (fs.existsSync(path.join(targetRoot, ".git"))) {
+      info("git repository already present, skipping init");
+    } else if (runCommand("git", ["init", "-q"], targetRoot)) {
+      ok("git repository initialised");
+    } else {
+      warn("git init failed - carrying on without it");
+    }
+  }
+
+  // ---- install ------------------------------------------------------------
+  let installed = false;
+  if (o.install) {
+    log("");
+    step("Installing dependencies with " + o.pm + " - this takes a few minutes");
+    log("");
+    installed = runCommand(o.pm, ["install"], targetRoot);
+    log("");
+    if (installed) ok("dependencies installed");
+    else warn(o.pm + " install failed - run it yourself in " + o.name + " and read the error");
+  }
+
+  // ---- what to do next ----------------------------------------------------
+  const runCmd = o.pm === "npm" ? "npm run" : o.pm;
+  log("");
+  log("  " + c.green(c.bold("Done.")) + " Next:");
+  log("");
+  log("    " + c.cyan("cd") + " " + o.name);
+  if (!installed) log("    " + c.cyan(o.pm) + " install");
+  log("    " + c.cyan(runCmd) + " dev");
+  log("");
+  if (o.withSample) {
+    log("  The sample screen is at " + c.bold("http://localhost:5173" + o.basePath + "/sample"));
+    log("  " + c.dim(o.basePath + " is the Vite base, /sample is the slug in src/Module/index.ts"));
+    log("");
+  }
+  log("  " + c.yellow("Before it will load real data:"));
+  log("    1. Point " + c.bold("VITE_CENTRAL_SERVICE_BASE_URL") + " in .env at your environment.");
+  log(
+    "    2. Put a dev token in " +
+      c.bold(".env.local") +
+      " as VITE_HARDCODED_TOKEN, or sign in for the AuthToken cookie.",
+  );
+  log("       " + c.dim(".env.local is gitignored. Never commit a token to .env."));
+  log("    3. " + c.bold("README.md") + " holds the rules - schema first, no axios under src/ outside main.tsx.");
+  log("");
+}

package/src/deps.mjs

@@ -0,0 +1,195 @@
+/**
+ * Dependency set for a generated ProCode app.
+ *
+ * By default the CLI resolves it at scaffold time with resolveDependencySet():
+ * the newest published version of each ProCode package, plus the peers and
+ * bundled packages THOSE versions declare — so an app scaffolded after a
+ * library release gets that release and the peers it was built against, with
+ * no generator update. The constants below are the fallback (--no-latest, or
+ * the registry is unreachable): the set verified against a running ProCode
+ * host app (vsbackoffice / WorksLogicERP, 2026-10-08) at core 2.5.0 /
+ * kendo-widget 2.11.0 / vs-template 2.13.1 / vs-theme 2.6.0.
+ *
+ * Three rules encoded here, each of which is a hard failure if broken:
+ *
+ *  1. React stays on 18. All three runtime libraries declare `react ^18.2.0`
+ *     as a peer; React 19 installs cleanly and then fails at runtime.
+ *  2. `react-redux` stays on 8.x. On 9.x you get two Provider contexts, the
+ *     core's store becomes invisible to your components, and every screen
+ *     renders blank with nothing in the console.
+ *  3. `@progress/kendo-theme-default` is a MISSING peer declaration, not an
+ *     optional extra — the widget library's SCSS imports it by name, so
+ *     leaving it out is a hard build failure on the first `npm run dev`.
+ */
+
+/** The four ProCode packages. */
+export const PROCODE = {
+  "procode-lowcode-core": "^2.5.0",
+  "procode-lowcode-kendo-widget": "^2.11.0",
+  "procode-vs-template": "^2.13.1",
+  "procode-vs-theme": "^2.6.0",
+};
+
+/** Every peer the four packages declare. peerDependenciesMeta is empty on all
+ *  four — nothing here is optional. */
+export const DECLARED_PEERS = {
+  react: "^18.2.0",
+  "react-dom": "^18.2.0",
+  "react-router-dom": "^6.22.3",
+  axios: "^1.6.7",
+  "@progress/kendo-data-query": "^1.7.1",
+  "@progress/kendo-svg-icons": "^4.5.0",
+  "@progress/kendo-react-buttons": "^12.1.0",
+  "@progress/kendo-react-charts": "^12.1.0",
+  "@progress/kendo-react-common": "^12.1.0",
+  "@progress/kendo-react-conversational-ui": "^12.1.0",
+  "@progress/kendo-react-data-tools": "^12.1.0",
+  "@progress/kendo-react-dateinputs": "^12.1.0",
+  "@progress/kendo-react-dialogs": "^12.1.0",
+  "@progress/kendo-react-dropdowns": "^12.1.0",
+  "@progress/kendo-react-editor": "^12.1.0",
+  "@progress/kendo-react-gauges": "^12.1.0",
+  "@progress/kendo-react-grid": "^12.1.0",
+  "@progress/kendo-react-inputs": "^12.1.0",
+  "@progress/kendo-react-layout": "^12.1.0",
+  "@progress/kendo-react-listview": "^12.1.0",
+};
+
+/** Required at runtime or build time, but NOT declared as a peer by anything. */
+export const UNDECLARED_BUT_REQUIRED = {
+  "@progress/kendo-theme-default": "^12.1.0",
+  "@progress/kendo-licensing": "^1.11.3",
+  "@progress/kendo-react-labels": "^12.1.0",
+  "@progress/kendo-intl": "^3.1.1",
+  "react-toastify": "^11.0.5",
+  sass: "^1.38.0",
+};
+
+export const DEV_DEPS = {
+  // vite.config.ts imports node:url.
+  "@types/node": "^24.9.2",
+  "@types/react": "^18.2.43",
+  "@types/react-dom": "^18.2.17",
+  "@vitejs/plugin-react": "^4.2.1",
+  typescript: "^5.2.2",
+  vite: "^5.2.0",
+};
+
+export const LINT_DEV_DEPS = {
+  eslint: "^8.57.0",
+  "@typescript-eslint/eslint-plugin": "^7.2.0",
+  "@typescript-eslint/parser": "^7.2.0",
+  "eslint-plugin-react-hooks": "^4.6.0",
+  "eslint-plugin-react-refresh": "^0.4.6",
+};
+
+/** Bundled INSIDE the libraries. Listed for documentation only — do not add
+ *  them to a generated package.json, and never bump them independently. */
+export const BUNDLED_DO_NOT_ADD = {
+  "procode-lowcode-core": {
+    "@reduxjs/toolkit": "^1.9.1",
+    "react-redux": "^8.0.5",
+    "redux-saga": "^1.2.3",
+    uuid: "^11.1.1",
+  },
+  "procode-lowcode-kendo-widget": { lodash: "^4.17.21", uuid: "^11.1.1" },
+  "procode-vs-template": {
+    lodash: "^4.17.21",
+    "react-beautiful-dnd": "^13.1.1",
+    uuid: "^11.1.1",
+  },
+  "procode-vs-theme": {},
+};
+
+const sortKeys = (obj) =>
+  Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+
+/** The tested set, used with --no-latest or when the registry is unreachable. */
+export const PINNED_SET = {
+  procode: PROCODE,
+  peers: DECLARED_PEERS,
+  extras: UNDECLARED_BUT_REQUIRED,
+  bundled: BUNDLED_DO_NOT_ADD,
+  source: "pinned",
+};
+
+/** Lowest version a range admits, as [major, minor, patch]; [0,0,0] if none. */
+const floorOf = (range) => (String(range).match(/(\d+)\.(\d+)\.(\d+)/) ?? [0, 0, 0, 0]).slice(1).map(Number);
+const newer = (a, b) => {
+  const [x, y] = [floorOf(a), floorOf(b)];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i] ? a : b;
+  return a;
+};
+
+/**
+ * Ask the registry for the newest published version of each ProCode package,
+ * and derive everything else from those manifests:
+ *
+ *   peers   every peerDependency the four declare; where two declare the same
+ *           peer, the range with the higher floor wins (vs-template wants
+ *           react-router-dom ^6.22.3 where core wants ^6.6.1).
+ *   extras  required but undeclared. kendo-theme-default and kendo-react-labels
+ *           follow the kendo-react range the widget library declares — the
+ *           theme's major must match the components' major. The rest stay on
+ *           their tested pins.
+ *   bundled each package's own dependencies, for the _procodeBundled note.
+ *
+ * Uses the registry npm/npx was invoked with (npm_config_registry), so a
+ * mirror or proxy registry is honoured. Throws on any failure; the caller
+ * falls back to PINNED_SET.
+ */
+export async function resolveDependencySet({ registry, timeoutMs = 10000 } = {}) {
+  const base = String(registry || process.env.npm_config_registry || "https://registry.npmjs.org/").replace(/\/?$/, "/");
+
+  const manifests = await Promise.all(
+    Object.keys(PROCODE).map(async (name) => {
+      const res = await fetch(base + name.replace("/", "%2f") + "/latest", {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!res.ok) throw new Error(name + ": HTTP " + res.status + " from " + base);
+      const manifest = await res.json();
+      if (typeof manifest?.version !== "string") throw new Error(name + ": no version in the registry response");
+      return manifest;
+    }),
+  );
+
+  const procode = {};
+  const peers = {};
+  const bundled = {};
+  for (const m of manifests) {
+    procode[m.name] = "^" + m.version;
+    bundled[m.name] = m.dependencies ?? {};
+    for (const [peer, range] of Object.entries(m.peerDependencies ?? {})) {
+      peers[peer] = peers[peer] ? newer(peers[peer], range) : range;
+    }
+  }
+
+  const extras = { ...UNDECLARED_BUT_REQUIRED };
+  const kendoReact = Object.entries(peers).find(([n]) => n.startsWith("@progress/kendo-react-"))?.[1];
+  if (kendoReact) {
+    extras["@progress/kendo-theme-default"] = kendoReact;
+    extras["@progress/kendo-react-labels"] = kendoReact;
+  }
+
+  return { procode, peers, extras, bundled, source: "latest" };
+}
+
+/** `set` is PINNED_SET or what resolveDependencySet() returned. */
+export function buildDependencies(set = PINNED_SET) {
+  return sortKeys({ ...set.procode, ...set.peers, ...set.extras });
+}
+
+/**
+ * The React type packages follow the React major the libraries declare, so a
+ * future move off React 18 does not leave @types/react behind.
+ */
+export function buildDevDependencies({ lint = true, set = PINNED_SET } = {}) {
+  const devDeps = { ...DEV_DEPS, ...(lint ? LINT_DEV_DEPS : {}) };
+  const reactMajor = floorOf(set.peers.react ?? "")[0];
+  if (reactMajor && reactMajor !== floorOf(DEV_DEPS["@types/react"])[0]) {
+    devDeps["@types/react"] = "^" + reactMajor + ".0.0";
+    devDeps["@types/react-dom"] = "^" + reactMajor + ".0.0";
+  }
+  return sortKeys(devDeps);
+}

package/src/log.mjs

@@ -0,0 +1,23 @@
+const useColor =
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb" &&
+  process.stdout.isTTY !== false;
+
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const c = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  magenta: wrap("35"),
+  cyan: wrap("36"),
+};
+
+export const log = (msg = "") => console.log(msg);
+export const step = (msg) => console.log(`${c.cyan("›")} ${msg}`);
+export const ok = (msg) => console.log(`${c.green("✔")} ${msg}`);
+export const warn = (msg) => console.log(`${c.yellow("!")} ${msg}`);
+export const info = (msg) => console.log(`  ${c.dim(msg)}`);

package/src/prompt.mjs

@@ -0,0 +1,60 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { c } from "./log.mjs";
+
+let rl = null;
+const getRl = () => (rl ??= readline.createInterface({ input, output }));
+
+export const closePrompt = () => {
+  rl?.close();
+  rl = null;
+};
+
+export const isInteractive = () => Boolean(input.isTTY && output.isTTY);
+
+/** Free-text question with a default. */
+export async function ask(question, def, validate) {
+  for (;;) {
+    const hint = def ? c.dim(` (${def})`) : "";
+    const raw = (await getRl().question(`${c.cyan("?")} ${question}${hint} `)).trim();
+    const value = raw || def || "";
+    const problem = validate?.(value);
+    if (!problem) return value;
+    console.log(`  ${c.red(problem)}`);
+  }
+}
+
+/** Yes/no question. */
+export async function confirm(question, def = true) {
+  const hint = def ? "Y/n" : "y/N";
+  for (;;) {
+    const raw = (await getRl().question(`${c.cyan("?")} ${question} ${c.dim(`(${hint})`)} `))
+      .trim()
+      .toLowerCase();
+    if (!raw) return def;
+    if (["y", "yes"].includes(raw)) return true;
+    if (["n", "no"].includes(raw)) return false;
+    console.log(`  ${c.red("Please answer y or n.")}`);
+  }
+}
+
+/** Single choice from a list of { value, label, hint }. */
+export async function select(question, choices, defIndex = 0) {
+  console.log(`${c.cyan("?")} ${question}`);
+  choices.forEach((ch, i) => {
+    const mark = i === defIndex ? c.green("›") : " ";
+    const hint = ch.hint ? c.dim(` — ${ch.hint}`) : "";
+    console.log(`  ${mark} ${c.bold(String(i + 1))}. ${ch.label}${hint}`);
+  });
+  for (;;) {
+    const raw = (
+      await getRl().question(`  ${c.dim(`Choose 1-${choices.length}`)} ${c.dim(`(${defIndex + 1})`)} `)
+    ).trim();
+    if (!raw) return choices[defIndex].value;
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= 1 && n <= choices.length) return choices[n - 1].value;
+    const byValue = choices.find((ch) => ch.value === raw.toLowerCase());
+    if (byValue) return byValue.value;
+    console.log(`  ${c.red(`Enter a number between 1 and ${choices.length}.`)}`);
+  }
+}