nuxt-gin-tools 0.2.23 → 0.3.1

package/src/cli/commands/cleanup.d.ts

@@ -0,0 +1,11 @@
+export type CleanupOptions = {
+    dryRun?: boolean;
+};
+export declare function ifExistsRemove(relativePath: string, options?: CleanupOptions, actions?: string[]): void;
+export declare function cleanUpNuxt(options?: CleanupOptions, actions?: string[]): Promise<void> | Promise<import("concurrently").CloseEvent[]>;
+export declare function cleanUpBuild(options?: CleanupOptions, actions?: string[]): void;
+/**
+ * 清理构建目录和临时文件
+ */
+export declare function cleanUp(options?: CleanupOptions): Promise<void>;
+export default cleanUp;

package/src/cli/commands/cleanup.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ifExistsRemove = ifExistsRemove;
+exports.cleanUpNuxt = cleanUpNuxt;
+exports.cleanUpBuild = cleanUpBuild;
+exports.cleanUp = cleanUp;
+const FS = __importStar(require("fs-extra"));
+const Path = __importStar(require("path"));
+const concurrently_1 = __importDefault(require("concurrently"));
+const nuxt_gin_1 = require("../../nuxt-gin");
+const terminal_ui_1 = require("../terminal-ui");
+const cwd = process.cwd();
+const CLEANUP_PATHS = [
+    ".build/production",
+    "dist",
+    ".build",
+    "tmp",
+    "vue/.output",
+    ".openapi-generator",
+];
+function ifExistsRemove(relativePath, options = {}, actions = []) {
+    const absolutePath = Path.resolve(cwd, relativePath);
+    if (FS.existsSync(absolutePath)) {
+        if (options.dryRun) {
+            (0, terminal_ui_1.printCommandInfo)("cleanup", `would remove ${absolutePath}`);
+            actions.push(`would remove ${relativePath}`);
+            return;
+        }
+        FS.removeSync(absolutePath);
+        actions.push(`removed ${relativePath}`);
+    }
+}
+function cleanUpNuxt(options = {}, actions = []) {
+    if (options.dryRun) {
+        (0, terminal_ui_1.printCommandInfo)("cleanup", "would run `npx nuxt cleanup`");
+        actions.push("would run nuxt cleanup");
+        return Promise.resolve();
+    }
+    actions.push("ran nuxt cleanup");
+    return (0, concurrently_1.default)([
+        {
+            command: "npx nuxt cleanup",
+        },
+    ]).result;
+}
+function cleanUpBuild(options = {}, actions = []) {
+    for (const path of CLEANUP_PATHS) {
+        ifExistsRemove(path, options, actions);
+    }
+}
+/**
+ * 清理构建目录和临时文件
+ */
+function cleanUp() {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
+        (0, terminal_ui_1.printCommandBanner)("cleanup", "Remove generated build output and temporary files");
+        const projectConfig = (0, nuxt_gin_1.resolveNuxtGinProjectConfig)();
+        for (const warning of projectConfig.warnings) {
+            (0, terminal_ui_1.printCommandWarn)(`[config] ${warning}`);
+        }
+        const resolvedOptions = (0, nuxt_gin_1.mergeDefined)(projectConfig.config.cleanup, options);
+        const actions = [];
+        const result = cleanUpNuxt(resolvedOptions, actions);
+        cleanUpBuild(resolvedOptions, actions);
+        yield result;
+        (0, terminal_ui_1.printCommandSuccess)("cleanup", resolvedOptions.dryRun ? "Dry run completed" : "Temporary files removed");
+        (0, terminal_ui_1.printCommandSummary)("cleanup", actions);
+    });
+}
+exports.default = cleanUp;

package/src/cli/commands/develop.d.ts

@@ -0,0 +1,26 @@
+export type DevelopOptions = {
+    noCleanup?: boolean;
+    skipGo?: boolean;
+    skipNuxt?: boolean;
+};
+/**
+ * 启动本地开发环境。
+ *
+ * 行为包括：按配置执行预清理、释放开发端口、并行启动 Nuxt 与 Go 监听流程。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
+export declare function develop(options?: DevelopOptions): Promise<void>;
+/**
+ * 仅启动 Nuxt 开发服务（带 nuxt 标签输出）。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
+export declare function developNuxt(options?: DevelopOptions): Promise<void>;
+/**
+ * 仅启动 Go 开发监听流程。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
+export declare function developGo(options?: DevelopOptions): Promise<void>;
+export default develop;

package/src/cli/commands/develop.js

@@ -0,0 +1,168 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.develop = develop;
+exports.developNuxt = developNuxt;
+exports.developGo = developGo;
+const concurrently_1 = __importDefault(require("concurrently"));
+const fs_extra_1 = require("fs-extra");
+const path_1 = require("path");
+const cleanup_1 = __importDefault(require("./cleanup"));
+const install_1 = __importDefault(require("./install"));
+const go_dev_service_1 = require("../../services/go-dev-service");
+const nuxt_gin_1 = require("../../nuxt-gin");
+const ports_1 = require("../../system/ports");
+const terminal_ui_1 = require("../terminal-ui");
+const cwd = process.cwd();
+function resolveDevelopContext(options = {}) {
+    var _a, _b, _c, _d;
+    const projectConfig = (0, nuxt_gin_1.resolveNuxtGinProjectConfig)();
+    for (const warning of projectConfig.warnings) {
+        (0, terminal_ui_1.printCommandWarn)(`[config] ${warning}`);
+    }
+    const serverConfig = (0, nuxt_gin_1.readLegacyServerConfig)();
+    if (!serverConfig) {
+        throw new Error("server.config.json is required in project root for ginPort, nuxtPort, and baseUrl.");
+    }
+    const resolvedOptions = (0, nuxt_gin_1.mergeDefined)(projectConfig.config.dev, options);
+    const cleanupBeforeDevelop = (_b = (_a = projectConfig.config.dev) === null || _a === void 0 ? void 0 : _a.cleanupBeforeDevelop) !== null && _b !== void 0 ? _b : false;
+    const killPortBeforeDevelop = (_d = (_c = projectConfig.config.dev) === null || _c === void 0 ? void 0 : _c.killPortBeforeDevelop) !== null && _d !== void 0 ? _d : true;
+    return {
+        options: resolvedOptions,
+        serverConfig,
+        cleanupBeforeDevelop,
+        killPortBeforeDevelop,
+    };
+}
+function prepareDevelop(context) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const shouldPrepare = !context.options.noCleanup;
+        if (!shouldPrepare) {
+            return;
+        }
+        if (context.cleanupBeforeDevelop) {
+            yield (0, cleanup_1.default)();
+            yield (0, install_1.default)({
+                skipGo: context.options.skipGo,
+                skipNuxt: context.options.skipNuxt,
+            });
+            return;
+        }
+        if (!(0, fs_extra_1.existsSync)((0, path_1.join)(cwd, "vue/.nuxt")) || !(0, fs_extra_1.existsSync)((0, path_1.join)(cwd, "go.sum"))) {
+            yield (0, cleanup_1.default)();
+            yield (0, install_1.default)({
+                skipGo: context.options.skipGo,
+                skipNuxt: context.options.skipNuxt,
+            });
+        }
+    });
+}
+function runNuxtDev(serverConfig) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield (0, concurrently_1.default)([
+            {
+                command: `npx nuxt dev --port=${serverConfig.nuxtPort} --host`,
+                name: "nuxt",
+                prefixColor: "blue",
+            },
+        ]).result;
+    });
+}
+function runGoDev(serverConfig) {
+    return __awaiter(this, void 0, void 0, function* () {
+        (0, fs_extra_1.ensureDirSync)((0, path_1.join)(cwd, ".build/.server"));
+        yield (0, go_dev_service_1.startGoDev)(serverConfig.ginPort);
+    });
+}
+/**
+ * 启动本地开发环境。
+ *
+ * 行为包括：按配置执行预清理、释放开发端口、并行启动 Nuxt 与 Go 监听流程。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
+function develop() {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
+        (0, terminal_ui_1.printCommandBanner)("dev", "Start Nuxt and Go development workflows");
+        const context = resolveDevelopContext(options);
+        const actions = [];
+        yield prepareDevelop(context);
+        // 在开发前确保占用端口被释放
+        if (context.killPortBeforeDevelop) {
+            (0, ports_1.killPorts)([
+                context.options.skipGo ? undefined : context.serverConfig.ginPort,
+                context.options.skipNuxt ? undefined : context.serverConfig.nuxtPort,
+            ]);
+            actions.push("released occupied development ports");
+        }
+        const tasks = [];
+        if (!context.options.skipGo) {
+            tasks.push(runGoDev(context.serverConfig));
+            actions.push(`started Go watcher on port ${context.serverConfig.ginPort}`);
+        }
+        if (!context.options.skipNuxt) {
+            tasks.push(runNuxtDev(context.serverConfig));
+            actions.push(`started Nuxt dev server on port ${context.serverConfig.nuxtPort}`);
+        }
+        if (context.options.skipGo) {
+            actions.push("skipped Go workflow");
+        }
+        if (context.options.skipNuxt) {
+            actions.push("skipped Nuxt workflow");
+        }
+        (0, terminal_ui_1.printCommandSummary)("dev", actions);
+        yield Promise.all(tasks);
+    });
+}
+/**
+ * 仅启动 Nuxt 开发服务（带 nuxt 标签输出）。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
+function developNuxt() {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
+        (0, terminal_ui_1.printCommandBanner)("dev:nuxt", "Start Nuxt development server only");
+        const context = resolveDevelopContext(options);
+        const actions = [];
+        yield prepareDevelop(Object.assign(Object.assign({}, context), { options: Object.assign(Object.assign({}, context.options), { skipGo: true }) }));
+        if (context.killPortBeforeDevelop) {
+            (0, ports_1.killPorts)([context.serverConfig.nuxtPort]);
+            actions.push("released Nuxt dev port");
+        }
+        actions.push(`started Nuxt dev server on port ${context.serverConfig.nuxtPort}`);
+        (0, terminal_ui_1.printCommandSummary)("dev:nuxt", actions);
+        yield runNuxtDev(context.serverConfig);
+    });
+}
+/**
+ * 仅启动 Go 开发监听流程。
+ *
+ * @returns {Promise<void>} 仅在开发进程退出或出现异常时返回。
+ */
+function developGo() {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
+        (0, terminal_ui_1.printCommandBanner)("dev:go", "Start Go watcher only");
+        const context = resolveDevelopContext(options);
+        const actions = [];
+        yield prepareDevelop(Object.assign(Object.assign({}, context), { options: Object.assign(Object.assign({}, context.options), { skipNuxt: true }) }));
+        if (context.killPortBeforeDevelop) {
+            (0, ports_1.killPorts)([context.serverConfig.ginPort]);
+            actions.push("released Go server port");
+        }
+        actions.push(`started Go watcher on port ${context.serverConfig.ginPort}`);
+        (0, terminal_ui_1.printCommandSummary)("dev:go", actions);
+        yield runGoDev(context.serverConfig);
+    });
+}
+exports.default = develop;

package/src/cli/commands/install.d.ts

@@ -0,0 +1,6 @@
+export type PostInstallOptions = {
+    skipGo?: boolean;
+    skipNuxt?: boolean;
+};
+export declare function postInstall(options?: PostInstallOptions): Promise<void>;
+export default postInstall;

package/src/cli/commands/install.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postInstall = postInstall;
+const concurrently_1 = __importDefault(require("concurrently"));
+const node_child_process_1 = require("node:child_process");
+const nuxt_gin_1 = require("../../nuxt-gin");
+const terminal_ui_1 = require("../terminal-ui");
+function postInstall(options = {}) {
+    (0, terminal_ui_1.printCommandBanner)("install", "Prepare Nuxt and optional Go dependencies");
+    const projectConfig = (0, nuxt_gin_1.resolveNuxtGinProjectConfig)();
+    for (const warning of projectConfig.warnings) {
+        (0, terminal_ui_1.printCommandWarn)(`[config] ${warning}`);
+    }
+    const resolvedOptions = (0, nuxt_gin_1.mergeDefined)(projectConfig.config.install, options);
+    const actions = [];
+    const commands = [];
+    const hasGo = (0, node_child_process_1.spawnSync)("go", ["version"], { stdio: "ignore", shell: true }).status ===
+        0;
+    if (!resolvedOptions.skipNuxt) {
+        actions.push("prepared Nuxt runtime");
+        commands.push({
+            command: "npx nuxt prepare",
+            name: "nuxt",
+            prefixColor: "blue",
+        });
+    }
+    if (!resolvedOptions.skipGo && hasGo) {
+        actions.push("downloaded and tidied Go modules");
+        commands.push({
+            command: "go mod download && go mod tidy",
+            name: "go",
+            prefixColor: "green",
+        });
+    }
+    else if (!resolvedOptions.skipGo) {
+        (0, terminal_ui_1.printCommandWarn)("Go was not detected, skipping Go dependency bootstrap");
+        actions.push("skipped Go bootstrap because Go was not detected");
+    }
+    else {
+        actions.push("skipped Go bootstrap by option");
+    }
+    if (resolvedOptions.skipNuxt) {
+        actions.push("skipped Nuxt prepare by option");
+    }
+    if (commands.length === 0) {
+        (0, terminal_ui_1.printCommandWarn)("Nothing selected for install, skipping bootstrap");
+        (0, terminal_ui_1.printCommandSummary)("install", actions.length > 0 ? actions : ["nothing was executed"]);
+        return Promise.resolve();
+    }
+    // 执行并发命令
+    return (0, concurrently_1.default)(commands).result.then(() => {
+        (0, terminal_ui_1.printCommandSuccess)("install", "Project bootstrap completed");
+        (0, terminal_ui_1.printCommandSummary)("install", actions);
+    });
+}
+exports.default = postInstall;

package/src/cli/commands/update.d.ts

@@ -0,0 +1,9 @@
+import { type PackageManagerSelection } from "../../config/package-manager";
+export type UpdateOptions = {
+    latest?: boolean;
+    packageManager?: PackageManagerSelection;
+    skipGo?: boolean;
+    skipNode?: boolean;
+};
+export declare function update(options?: UpdateOptions): Promise<void>;
+export default update;

package/src/cli/commands/update.js

@@ -0,0 +1,89 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.update = update;
+const concurrently_1 = __importDefault(require("concurrently"));
+const promises_1 = require("node:readline/promises");
+const package_manager_1 = require("../../config/package-manager");
+const nuxt_gin_1 = require("../../nuxt-gin");
+const terminal_ui_1 = require("../terminal-ui");
+function resolveLatestPreference(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof options.latest === "boolean") {
+            return options.latest;
+        }
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            (0, terminal_ui_1.printCommandWarn)("Non-interactive terminal detected, defaulting update mode to conservative");
+            return false;
+        }
+        const rl = (0, promises_1.createInterface)({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        try {
+            const answer = yield rl.question("Use latest dependency upgrade strategy? [y/N] ");
+            const normalized = answer.trim().toLowerCase();
+            return ["y", "yes"].includes(normalized);
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+function update() {
+    return __awaiter(this, arguments, void 0, function* (options = {}) {
+        var _a, _b;
+        (0, terminal_ui_1.printCommandBanner)("update", "Update Node and Go dependencies");
+        const projectConfig = (0, nuxt_gin_1.resolveNuxtGinProjectConfig)();
+        for (const warning of projectConfig.warnings) {
+            (0, terminal_ui_1.printCommandWarn)(`[config] ${warning}`);
+        }
+        const resolvedOptions = (0, nuxt_gin_1.mergeDefined)(Object.assign({ packageManager: "auto" }, ((_a = projectConfig.config.update) !== null && _a !== void 0 ? _a : {})), options);
+        const latest = yield resolveLatestPreference(resolvedOptions);
+        const actions = [];
+        const commands = [];
+        const packageManager = (0, package_manager_1.resolvePackageManager)((_b = resolvedOptions.packageManager) !== null && _b !== void 0 ? _b : "auto");
+        if (!resolvedOptions.skipNode) {
+            actions.push(`updated Node dependencies with ${packageManager} (${latest ? "latest" : "conservative"} mode)`);
+            commands.push({
+                command: (0, package_manager_1.packageManagerUpdateCommand)(packageManager, latest),
+                name: packageManager,
+                prefixColor: "magenta",
+            });
+        }
+        if (!resolvedOptions.skipGo) {
+            actions.push(`updated Go modules with ${latest ? "latest" : "patch"} strategy`);
+            commands.push({
+                command: latest ? "go get -u ./... && go mod tidy" : "go get -u=patch ./... && go mod tidy",
+                name: "go",
+                prefixColor: "green",
+            });
+        }
+        if (resolvedOptions.skipNode) {
+            actions.push("skipped Node dependency update");
+        }
+        if (resolvedOptions.skipGo) {
+            actions.push("skipped Go dependency update");
+        }
+        if (commands.length === 0) {
+            (0, terminal_ui_1.printCommandWarn)("No update targets selected, nothing to do");
+            (0, terminal_ui_1.printCommandSummary)("update", actions.length > 0 ? actions : ["nothing was executed"]);
+            return;
+        }
+        yield (0, concurrently_1.default)(commands).result;
+        (0, terminal_ui_1.printCommandSuccess)("update", "Dependency update completed");
+        (0, terminal_ui_1.printCommandSummary)("update", actions);
+    });
+}
+exports.default = update;

package/src/cli/options.d.ts

@@ -0,0 +1,10 @@
+export type CLIOptions = {
+    flags: Set<string>;
+    values: Map<string, string>;
+    positionals: string[];
+};
+export declare function parseCLIOptions(args: string[]): CLIOptions;
+export declare function hasFlag(options: CLIOptions, key: string): boolean;
+export declare function getOption(options: CLIOptions, key: string): string | undefined;
+export declare function getBooleanOption(options: CLIOptions, key: string, defaultValue: boolean): boolean;
+export declare function getOptionalBooleanOption(options: CLIOptions, key: string): boolean | undefined;

package/src/cli/options.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCLIOptions = parseCLIOptions;
+exports.hasFlag = hasFlag;
+exports.getOption = getOption;
+exports.getBooleanOption = getBooleanOption;
+exports.getOptionalBooleanOption = getOptionalBooleanOption;
+function normalizeKey(key) {
+    return key.replace(/^-+/, "").trim();
+}
+function parseCLIOptions(args) {
+    var _a, _b, _c, _d;
+    const flags = new Set();
+    const values = new Map();
+    const positionals = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const current = (_b = (_a = args[i]) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "";
+        if (!current)
+            continue;
+        if (!current.startsWith("-")) {
+            positionals.push(current);
+            continue;
+        }
+        const eqIndex = current.indexOf("=");
+        if (eqIndex >= 0) {
+            values.set(normalizeKey(current.slice(0, eqIndex)), current.slice(eqIndex + 1));
+            continue;
+        }
+        const key = normalizeKey(current);
+        const next = (_d = (_c = args[i + 1]) === null || _c === void 0 ? void 0 : _c.trim()) !== null && _d !== void 0 ? _d : "";
+        if (next && !next.startsWith("-")) {
+            values.set(key, next);
+            i += 1;
+            continue;
+        }
+        flags.add(key);
+    }
+    return { flags, values, positionals };
+}
+function hasFlag(options, key) {
+    return options.flags.has(normalizeKey(key));
+}
+function getOption(options, key) {
+    return options.values.get(normalizeKey(key));
+}
+function getBooleanOption(options, key, defaultValue) {
+    const value = getOptionalBooleanOption(options, key);
+    if (value === undefined) {
+        return defaultValue;
+    }
+    return value;
+}
+function getOptionalBooleanOption(options, key) {
+    const value = getOption(options, key);
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "y", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["false", "0", "no", "n", "off"].includes(normalized)) {
+        return false;
+    }
+    throw new Error(`Invalid boolean value for --${key}: ${value}`);
+}

package/src/cli/terminal-ui.d.ts

@@ -0,0 +1,7 @@
+export declare function printCommandBanner(command: string, subtitle: string): void;
+export declare function printCommandSuccess(command: string, message: string): void;
+export declare function printCommandInfo(label: string, message: string): void;
+export declare function printCommandWarn(message: string): void;
+export declare function printCommandError(message: string, error?: unknown): void;
+export declare function printCommandLog(label: string, message: string): void;
+export declare function printCommandSummary(command: string, items: string[]): void;