@wchen.ai/env-from-example 1.0.0

package/README.md

@@ -0,0 +1,240 @@
+# env-from-example
+
+Interactive and non-interactive CLI to set up `.env` from `.env.example`.
+
+Walks you through each variable, validates types, auto-generates secrets, and prints a summary of what was configured. All type detection and validation are driven by a bundled [`schema.json`](schema.json).
+
+## Quick Start
+
+```bash
+# Run without installing (npx fetches and runs)
+npx @wchen.ai/env-from-example
+
+# After installing in your project, use the short form:
+npx env-from-example
+
+# Don't have a .env.example yet? Create one:
+npx env-from-example --init            # starter template, add env vars, then polish
+npx env-from-example --init .env       # from your existing .env
+
+# Don't have a .env? Generate one from .env.example
+npx env-from-example                   # Generate .env
+npx env-from-example -e staging        # Generate .env.staging
+```
+
+## Installation
+
+Install in your project so you can run `npx env-from-example` from the project root:
+
+```bash
+npm install @wchen.ai/env-from-example
+# or
+pnpm add @wchen.ai/env-from-example
+# or as a dev dependency (recommended for CLI tools)
+npm install -D @wchen.ai/env-from-example
+pnpm add -D @wchen.ai/env-from-example
+```
+
+Then run from your project root: **`npx env-from-example`** (or add it to your `package.json` scripts).
+
+## Setup
+
+Add a `.env.example` in your project root (or run `env-from-example --init` to create one).
+
+```bash
+npx env-from-example --init            # starter template
+npx env-from-example --init .env       # from your existing .env
+```
+
+### Before and after (first run)
+
+If you start with only a `.env.example` and no `.env` (or an empty one), running the tool fills in `.env` from your answers and defaults.
+
+**Before** — you have `.env.example` and no `.env` (or `.env` is empty):
+
+```env
+# .env.example (excerpt)
+DATABASE_URL=postgres://localhost:5432/myapp
+API_KEY=
+NODE_ENV=development
+SESSION_SECRET=
+```
+
+```env
+# .env — missing or empty
+```
+
+**After** — run `env-from-example` (or `env-from-example -y` to accept defaults). The CLI prompts for required values, can auto-generate secrets (e.g. `SESSION_SECRET`), and writes:
+
+```env
+# .env — created/updated by env-from-example
+DATABASE_URL=postgres://localhost:5432/myapp
+API_KEY=your-api-key-here
+NODE_ENV=development
+SESSION_SECRET=a1b2c3d4e5f6...
+```
+
+Use `env-from-example -y --dry-run` to preview the result without writing files.
+
+## Usage
+
+Run from your project root (where `.env.example` lives):
+
+```bash
+env-from-example
+```
+
+**Options:**
+
+| Flag                   | Description                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `-y, --yes`            | Non-interactive: accept existing values or defaults without prompting               |
+| `-f, --force`          | Force re-run even if `.env` is already up-to-date                                   |
+| `-e, --env <name>`     | Target environment (e.g., `local`, `test`, `production`)                            |
+| `--cwd <path>`         | Project root directory (default: current working directory)                         |
+| `--init [source]`      | Create `.env.example` from an existing env file or from scratch                     |
+| `--polish`             | Polish `.env.example`: add descriptions, types, defaults (`-y` for non-interactive) |
+| `--version [bump]`     | Bump or set `ENV_SCHEMA_VERSION` (`patch`, `minor`, `major`, or exact semver)       |
+| `--sync-package`       | With `--version`: also update `package.json` version                                |
+| `--validate [envFile]` | Validate `.env` against `.env.example` schema (exit 1 if invalid)                   |
+| `--dry-run`            | Preview what would be written without creating/modifying files                      |
+
+**Examples:**
+
+```bash
+# Interactive setup (default .env)
+env-from-example
+
+# Non-interactive: create/update .env with defaults or existing values
+env-from-example -y
+
+# Preview what would be generated (no files written)
+env-from-example -y --dry-run
+
+# Create .env.local with prompts
+env-from-example -e local
+
+# Create .env.test without prompts (e.g. CI)
+env-from-example -y -e test
+
+# Force re-run even if .env is up-to-date
+env-from-example -f
+
+# Run from another directory (e.g. monorepo package)
+env-from-example --cwd ./apps/api
+
+# Override a variable via CLI
+env-from-example --database-url "postgres://prod:5432/db" -y
+
+# Bump ENV_SCHEMA_VERSION
+env-from-example --version patch
+env-from-example --version minor --sync-package
+
+# Validate .env against .env.example schema
+env-from-example --validate
+```
+
+## Annotations
+
+Each variable in `.env.example` can be annotated with structured tags in the comment line above it:
+
+```env
+# <description> [REQUIRED] [TYPE: <schema-type>] [CONSTRAINTS: key=value,...] Default: <value>
+VARIABLE_NAME=default_value
+```
+
+| Annotation  | Syntax                         | Purpose                                              |
+| ----------- | ------------------------------ | ---------------------------------------------------- |
+| Description | Free text at start of comment  | Human-readable explanation                           |
+| Required    | `[REQUIRED]`                   | Variable must be non-empty                           |
+| Type        | `[TYPE: <schema-type>]`        | Type from `schema.json` for validation and detection |
+| Constraints | `[CONSTRAINTS: key=value,...]` | Constraints (min, max, pattern, etc.)                |
+| Default     | `Default: <value>`             | Documented default (informational)                   |
+
+All annotations are optional. The `--polish` command auto-detects and adds them.
+
+### Polish: before and after
+
+`env-from-example --polish` (or `--polish -y` for non-interactive) updates your `.env.example` with inferred descriptions, types, and default annotations.
+
+**Before** — minimal `.env.example`:
+
+```env
+DATABASE_URL=postgres://localhost:5432/myapp
+PORT=3000
+NODE_ENV=development
+API_KEY=
+```
+
+**After** — run `env-from-example --polish -y`:
+
+```env
+# env-from-example (https://www.npmjs.com/package/@wchen.ai/env-from-example)
+
+# ENV_SCHEMA_VERSION="1.0.0"
+
+# ========================================
+#                Database
+# ========================================
+
+# Database Url
+# [REQUIRED] [TYPE: network/uri] Default: postgres://localhost:5432/myapp
+DATABASE_URL=postgres://localhost:5432/myapp
+
+# ========================================
+#                  App
+# ========================================
+
+# Application port
+# [REQUIRED] [TYPE: integer] [CONSTRAINTS: min=3000,max=10000] Default: 3000
+PORT=3000
+
+# Node Env
+# [TYPE: structured/enum] [CONSTRAINTS: pattern=^(development|test|staging|production|ci)$] Default: development
+NODE_ENV=development
+
+# ========================================
+#                 Other
+# ========================================
+
+# OPEN AI API KEY
+# [REQUIRED] [TYPE: credentials/secret] Default: (empty)
+API_KEY=
+```
+
+Use `env-from-example --polish --dry-run` to preview changes without writing the file.
+
+## CI / CD
+
+**GitHub Actions** -- generate `.env.test` before running tests:
+
+```yaml
+# .github/workflows/test.yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx env-from-example -y -e test
+      - run: npm test
+```
+
+**Pre-commit hook** -- validate `.env` stays in sync:
+
+```bash
+# .husky/pre-commit
+npx env-from-example --validate
+```
+
+## Requirements
+
+- A `.env.example` file in the project root (or the path given by `--cwd`). Run `env-from-example --init` to create one.
+- `schema.json` is bundled with the package and used automatically.
+
+## License
+
+ISC

package/dist/env-from-example.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { Command } from "commander";
+import { input, confirm, select } from "@inquirer/prompts";
+import pc from "picocolors";
+import { findSchemaType, parseEnumChoices, } from "./src/schema.js";
+import { parseEnvExample, getExistingEnvVersion, getExistingEnvVariables, groupVariablesBySection, getGroup, inferDescription, stripMetaFromComment, initEnvExample, } from "./src/parse.js";
+import { validateValue, validateEnv, coerceToType, generateAutoValue, } from "./src/validate.js";
+import { polishEnvExample, polishEnvExampleInteractive } from "./src/polish.js";
+import { bumpSemver, updateEnvSchemaVersion } from "./src/version.js";
+// ─── Re-exports (public API consumed by tests and external users) ────────────
+export { loadSchema, resetSchemaCache, getSchemaTypes, findSchemaType, parseEnumChoices, getAvailableConstraints, } from "./src/schema.js";
+export { parseEnvExample, getExistingEnvVersion, getExistingEnvVariables, serializeEnvExample, inferDescription, initEnvExample, } from "./src/parse.js";
+export { detectType, matchesSchemaType, validateValue, validateEnv, coerceToType, generateAutoValue, } from "./src/validate.js";
+export { polishEnvExample, polishEnvExampleInteractive } from "./src/polish.js";
+export { bumpSemver, updateEnvSchemaVersion } from "./src/version.js";
+// ─── CLI helpers ─────────────────────────────────────────────────────────────
+export function getRootDirFromArgv() {
+    const argv = process.argv;
+    const cwdIdx = argv.indexOf("--cwd");
+    if (cwdIdx !== -1 && argv[cwdIdx + 1]) {
+        return path.resolve(argv[cwdIdx + 1]);
+    }
+    return process.cwd();
+}
+function renderGroupBanner(groupName) {
+    const W = 40;
+    const bar = "# " + "=".repeat(W);
+    const padLen = Math.max(1, Math.floor((W - groupName.length) / 2));
+    const center = "#" + " ".repeat(padLen) + groupName;
+    return [bar, center, bar];
+}
+function buildEnvContent(schemaVersion, variables, finalValues) {
+    let content = `# ==============================================\n`;
+    content += `# Environment Variables\n`;
+    content += `# ==============================================\n`;
+    if (schemaVersion) {
+        content += `# ENV_SCHEMA_VERSION="${schemaVersion}"\n`;
+    }
+    content += `# Generated on ${new Date().toISOString()}\n`;
+    content += `# Generated by env-from-example (https://www.npmjs.com/package/env-from-example)\n`;
+    content += `# ==============================================\n\n`;
+    const grouped = groupVariablesBySection(variables);
+    let lastGroup = "";
+    for (const v of grouped) {
+        const group = getGroup(v);
+        if (group && group !== lastGroup) {
+            content += "\n" + renderGroupBanner(group).join("\n") + "\n\n";
+            lastGroup = group;
+        }
+        const desc = inferDescription(v);
+        if (desc) {
+            content += `# ${desc}\n`;
+        }
+        if (v.key in finalValues) {
+            const val = finalValues[v.key];
+            const needsQuotes = /[\s#"']/.test(val) || val === "";
+            const safeValue = needsQuotes && val !== "" ? `"${val.replace(/"/g, '\\"')}"` : val;
+            content += `${v.key}=${safeValue}\n`;
+        }
+        else {
+            content += `# ${v.key}=\n`;
+        }
+    }
+    return content;
+}
+function printSummary(summary, envFileName, schemaVersion) {
+    console.log("");
+    console.log(pc.green(pc.bold(`✅ ${envFileName} successfully created/updated!`)));
+    if (schemaVersion) {
+        console.log(pc.gray(`   Schema version: ${schemaVersion}`));
+    }
+    console.log("");
+    const total = summary.fromExisting.length +
+        summary.fromDefault.length +
+        summary.autoGenerated.length +
+        summary.fromCli.length +
+        summary.skippedCommented.length;
+    console.log(pc.bold(`   ${total} variables configured:`));
+    if (summary.fromCli.length > 0) {
+        console.log(pc.cyan(`   ⮑  ${summary.fromCli.length} from CLI flags: `) +
+            pc.dim(summary.fromCli.join(", ")));
+    }
+    if (summary.fromExisting.length > 0) {
+        console.log(pc.green(`   ⮑  ${summary.fromExisting.length} from existing ${envFileName}: `) + pc.dim(summary.fromExisting.join(", ")));
+    }
+    if (summary.fromDefault.length > 0) {
+        console.log(pc.blue(`   ⮑  ${summary.fromDefault.length} from defaults: `) +
+            pc.dim(summary.fromDefault.join(", ")));
+    }
+    if (summary.autoGenerated.length > 0) {
+        console.log(pc.magenta(`   ⮑  ${summary.autoGenerated.length} auto-generated: `) +
+            pc.dim(summary.autoGenerated.join(", ")));
+    }
+    if (summary.skippedCommented.length > 0) {
+        console.log(pc.gray(`   ⮑  ${summary.skippedCommented.length} commented-out (kept as-is): `) + pc.dim(summary.skippedCommented.join(", ")));
+    }
+    if (summary.requiredMissing.length > 0) {
+        console.log(pc.yellow(`   ⚠  ${summary.requiredMissing.length} required but empty: `) + pc.dim(summary.requiredMissing.join(", ")));
+    }
+    console.log("");
+}
+// ─── Main CLI ────────────────────────────────────────────────────────────────
+async function run() {
+    const program = new Command();
+    program
+        .name("env-from-example")
+        .description("Interactive and non-interactive CLI to set up .env from .env.example")
+        .option("-y, --yes", "Non-interactive: accept existing values or defaults without prompting")
+        .option("-f, --force", "Force re-run even if .env is already up-to-date")
+        .option("-e, --env <environment>", "Target environment (e.g., local, test, production)")
+        .option("--cwd <path>", "Project root directory (default: current working directory)")
+        .option("--init [source]", "Create .env.example from an existing env file (default: .env) or from scratch")
+        .option("--polish", "Polish .env.example: add descriptions, types, defaults (use -y for non-interactive)")
+        .option("--version [bump]", "Bump or set ENV_SCHEMA_VERSION (patch|minor|major or exact semver)")
+        .option("--sync-package", "With --version: also update package.json version")
+        .option("--validate [envFile]", "Validate .env against .env.example schema (exit 1 if invalid)")
+        .option("--dry-run", "Preview what would be written without creating/modifying files");
+    const earlyRoot = getRootDirFromArgv();
+    try {
+        const { variables: earlyVars } = parseEnvExample(earlyRoot);
+        earlyVars.forEach((v) => {
+            const optName = `--${v.key.toLowerCase().replace(/_/g, "-")}`;
+            const desc = stripMetaFromComment(v.comment) || `Set ${v.key}`;
+            program.option(`${optName} <value>`, desc);
+        });
+    }
+    catch {
+        /* .env.example may not exist yet */
+    }
+    program.parse();
+    const options = program.opts();
+    const ROOT_DIR = path.resolve(options.cwd || process.cwd());
+    if (options.init !== undefined) {
+        try {
+            const source = typeof options.init === "string" ? options.init : undefined;
+            initEnvExample(ROOT_DIR, { from: source });
+            console.log(pc.green(pc.bold("✅ .env.example created.")));
+            if (!source) {
+                return;
+            }
+            if (options.yes) {
+                polishEnvExample(ROOT_DIR);
+                console.log(pc.green(pc.bold("✅ .env.example polished (non-interactive).")));
+            }
+            else {
+                await polishEnvExampleInteractive(ROOT_DIR);
+                console.log(pc.green(pc.bold("✅ .env.example polished.")));
+            }
+            return;
+        }
+        catch (e) {
+            console.error(pc.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+    }
+    if (options.polish) {
+        try {
+            if (options.yes) {
+                polishEnvExample(ROOT_DIR);
+                console.log(pc.green(pc.bold("✅ .env.example polished (non-interactive).")));
+            }
+            else {
+                console.log(pc.cyan(pc.bold("Interactive polish: conform .env.example to convention (description, default, type, etc.)\n")));
+                await polishEnvExampleInteractive(ROOT_DIR);
+                console.log(pc.green(pc.bold("✅ .env.example polished.")));
+            }
+            return;
+        }
+        catch (e) {
+            console.error(pc.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+    }
+    if (options.validate !== undefined) {
+        const envFile = options.validate === true ? ".env" : `.env.${options.validate}`;
+        try {
+            const result = validateEnv(ROOT_DIR, { envFile });
+            if (result.warnings.length > 0) {
+                result.warnings.forEach((w) => console.warn(pc.yellow("Warning:"), w));
+            }
+            if (result.valid) {
+                console.log(pc.green(pc.bold(`✅ ${envFile} is valid against .env.example schema.`)));
+                return;
+            }
+            result.errors.forEach((e) => console.error(pc.red("Error:"), e));
+            process.exit(1);
+        }
+        catch (e) {
+            console.error(pc.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+    }
+    if (options.version !== undefined) {
+        try {
+            const { version } = parseEnvExample(ROOT_DIR);
+            const current = version || "1.0.0";
+            const bump = options.version === true ? undefined : options.version;
+            let newVersion;
+            if (bump === "patch" || bump === "minor" || bump === "major") {
+                newVersion = bumpSemver(current, bump);
+            }
+            else if (bump && typeof bump === "string") {
+                newVersion = bump;
+            }
+            else {
+                newVersion = bumpSemver(current, "patch");
+            }
+            updateEnvSchemaVersion(ROOT_DIR, newVersion, {
+                syncPackage: options.syncPackage,
+            });
+            console.log(pc.green(pc.bold(`✅ ENV_SCHEMA_VERSION set to ${newVersion}`)));
+            if (options.syncPackage) {
+                console.log(pc.gray("   package.json version updated."));
+            }
+            return;
+        }
+        catch (e) {
+            console.error(pc.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+    }
+    // ─── Main: generate .env ─────────────────────────────────────────────────
+    let schemaVersion;
+    let variables;
+    try {
+        const result = parseEnvExample(ROOT_DIR);
+        schemaVersion = result.version;
+        variables = result.variables;
+    }
+    catch {
+        const examplePath = path.join(ROOT_DIR, ".env.example");
+        console.error(pc.red(`No .env.example found at ${examplePath}`));
+        console.error("");
+        console.error(pc.bold("To get started:"));
+        console.error(pc.cyan("  env-from-example --init") +
+            pc.gray("          Create a starter .env.example"));
+        console.error(pc.cyan("  env-from-example --init .env") +
+            pc.gray("     Create .env.example from existing .env"));
+        console.error("");
+        console.error(pc.gray("Or create .env.example manually — see https://www.npmjs.com/package/env-from-example"));
+        process.exit(1);
+    }
+    const activeVars = variables.filter((v) => !v.isCommentedOut);
+    const totalPromptable = activeVars.length;
+    console.log("");
+    console.log(pc.cyan(pc.bold("  env-from-example")) +
+        pc.gray(` — ${totalPromptable} variables from .env.example`));
+    console.log("");
+    let targetEnv = options.env;
+    if (!targetEnv && !options.yes) {
+        const envChoice = await select({
+            message: "Select target environment to generate:",
+            choices: [
+                { name: "default (.env)", value: "default" },
+                { name: "local (.env.local)", value: "local" },
+                { name: "test (.env.test)", value: "test" },
+                { name: "staging (.env.stage)", value: "stage" },
+                { name: "production (.env.production)", value: "production" },
+                { name: "custom", value: "custom" },
+            ],
+        });
+        if (envChoice === "custom") {
+            targetEnv = await input({
+                message: "Enter custom environment name (e.g., ci, demo):",
+                validate: (val) => val.trim().length > 0 || "Environment name is required",
+            });
+        }
+        else {
+            targetEnv = envChoice === "default" ? "" : envChoice;
+        }
+    }
+    else if (!targetEnv) {
+        targetEnv = "";
+    }
+    const envFileName = targetEnv ? `.env.${targetEnv}` : ".env";
+    const envPath = path.join(ROOT_DIR, envFileName);
+    const existingEnvExists = fs.existsSync(envPath);
+    const existingVars = getExistingEnvVariables(envPath);
+    let existingVersion = null;
+    if (existingEnvExists) {
+        const content = fs.readFileSync(envPath, "utf-8");
+        existingVersion = getExistingEnvVersion(content);
+    }
+    if (existingEnvExists &&
+        existingVersion === schemaVersion &&
+        !options.force &&
+        !options.yes) {
+        const proceed = await confirm({
+            message: pc.green(`${envFileName} is already up-to-date (v${schemaVersion}). Re-run setup?`),
+            default: false,
+        });
+        if (!proceed) {
+            console.log(pc.gray("Nothing changed."));
+            process.exit(0);
+        }
+    }
+    const finalValues = {};
+    const summary = {
+        fromExisting: [],
+        fromDefault: [],
+        autoGenerated: [],
+        fromCli: [],
+        skippedCommented: [],
+        requiredMissing: [],
+    };
+    let promptIndex = 0;
+    for (const v of variables) {
+        const camelKey = v.key
+            .toLowerCase()
+            .replace(/_([a-z0-9])/gi, (_, c) => c.toUpperCase());
+        const valFromCli = options[camelKey];
+        if (valFromCli !== undefined &&
+            valFromCli !== null &&
+            typeof valFromCli === "string") {
+            finalValues[v.key] = valFromCli;
+            summary.fromCli.push(v.key);
+            continue;
+        }
+        const hasExisting = v.key in existingVars;
+        let currentDefault = existingVars[v.key] ?? v.defaultValue;
+        const schemaType = v.type ? findSchemaType(v.type) : undefined;
+        const autoGen = schemaType?.auto_generate;
+        let wasAutoGenerated = false;
+        if (autoGen && !currentDefault) {
+            currentDefault = generateAutoValue(autoGen);
+            wasAutoGenerated = true;
+        }
+        if (v.isCommentedOut) {
+            finalValues[v.key] = currentDefault;
+            summary.skippedCommented.push(v.key);
+            continue;
+        }
+        if (options.yes) {
+            if (v.required && !currentDefault) {
+                console.warn(pc.yellow(`  ⚠ [REQUIRED] ${v.key} has no value — set it manually in ${envFileName}`));
+                summary.requiredMissing.push(v.key);
+            }
+            finalValues[v.key] = currentDefault;
+            if (wasAutoGenerated)
+                summary.autoGenerated.push(v.key);
+            else if (hasExisting)
+                summary.fromExisting.push(v.key);
+            else
+                summary.fromDefault.push(v.key);
+            continue;
+        }
+        promptIndex++;
+        const progress = pc.dim(`[${promptIndex}/${totalPromptable}]`);
+        const desc = stripMetaFromComment(v.comment);
+        if (desc) {
+            console.log(pc.gray(`  ${desc}`));
+        }
+        let answer;
+        const isEnum = v.type === "structured/enum" && v.constraints?.pattern;
+        const enumChoices = isEnum ? parseEnumChoices(v.constraints.pattern) : [];
+        if (enumChoices.length > 0) {
+            const choiceValue = currentDefault && enumChoices.includes(currentDefault)
+                ? currentDefault
+                : enumChoices[0];
+            answer = await select({
+                message: `${progress} ${v.key}` +
+                    (v.required ? pc.bold(pc.yellow(" REQUIRED")) : ""),
+                choices: enumChoices.map((c) => ({ name: c, value: c })),
+                default: choiceValue,
+            });
+        }
+        else {
+            const hint = wasAutoGenerated ? pc.dim(" (auto-generated)") : "";
+            answer = await input({
+                message: `${progress} ${v.key}` +
+                    (v.required ? pc.bold(pc.yellow(" REQUIRED")) : "") +
+                    hint,
+                default: currentDefault,
+                validate: (val) => validateValue(val, v) ?? true,
+            });
+        }
+        const coerced = coerceToType(answer, v.type);
+        finalValues[v.key] = coerced;
+        if (wasAutoGenerated && coerced === currentDefault)
+            summary.autoGenerated.push(v.key);
+        else if (hasExisting && coerced === existingVars[v.key])
+            summary.fromExisting.push(v.key);
+        else
+            summary.fromDefault.push(v.key);
+    }
+    const newEnvContent = buildEnvContent(schemaVersion, variables, finalValues);
+    if (options.dryRun) {
+        console.log("");
+        console.log(pc.bold(pc.cyan(`--- Dry run: ${envFileName} (not written) ---`)));
+        console.log(pc.dim(newEnvContent));
+        console.log(pc.bold(pc.cyan("--- End dry run ---")));
+        printSummary(summary, envFileName, schemaVersion);
+        return;
+    }
+    fs.writeFileSync(envPath, newEnvContent, "utf-8");
+    printSummary(summary, envFileName, schemaVersion);
+}
+// ─── Entry ───────────────────────────────────────────────────────────────────
+const __filename = fileURLToPath(import.meta.url);
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename);
+if (isMain) {
+    run().catch((err) => {
+        if (err &&
+            typeof err === "object" &&
+            "name" in err &&
+            err.name === "ExitPromptError") {
+            console.log(pc.gray("\nCancelled."));
+            process.exit(0);
+        }
+        console.error(pc.red("Error:"), err);
+        process.exit(1);
+    });
+}