@flui-cloud/cli 0.0.1

package/lib/cli/src/lib/config.js

@@ -0,0 +1,113 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = getConfig;
+exports.setConfig = setConfig;
+exports.getToken = getToken;
+exports.getConfigPath = getConfigPath;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const profile_manager_1 = require("./profile-manager");
+function getConfigDir() {
+    return profile_manager_1.ProfileManager.getProfileDir();
+}
+function getConfigFile() {
+    return path.join(getConfigDir(), 'config.json');
+}
+/**
+ * Ensure config directory exists
+ */
+function ensureConfigDir() {
+    const dir = getConfigDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Read configuration from ~/.flui/config.json
+ * @returns Configuration object
+ */
+function getConfig() {
+    ensureConfigDir();
+    const configFile = getConfigFile();
+    if (!fs.existsSync(configFile)) {
+        return {};
+    }
+    try {
+        const content = fs.readFileSync(configFile, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to read config file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Write configuration to ~/.flui/config.json
+ * @param key Configuration key
+ * @param value Configuration value
+ */
+function setConfig(key, value) {
+    ensureConfigDir();
+    const config = getConfig();
+    config[key] = value;
+    try {
+        fs.writeFileSync(getConfigFile(), JSON.stringify(config, null, 2));
+    }
+    catch (error) {
+        throw new Error(`Failed to write config file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Get Hetzner token from config
+ * @returns Hetzner API token
+ * @throws Error if token is not configured
+ */
+function getToken() {
+    const config = getConfig();
+    if (!config.hetzner_token) {
+        throw new Error('Hetzner token not configured.\n' +
+            'Please set it using:\n' +
+            '  flui config set hetzner_token YOUR_TOKEN\n\n' +
+            'Get your token from: https://console.hetzner.cloud/');
+    }
+    return config.hetzner_token;
+}
+/**
+ * Get config file path
+ * @returns Path to config file
+ */
+function getConfigPath() {
+    return getConfigFile();
+}

package/lib/cli/src/lib/context-banner.d.ts

@@ -0,0 +1,12 @@
+export interface ContextBannerOptions {
+    /** Optional override of the API URL display (e.g. when caller already loaded ConfigStorage). */
+    apiUrl?: string | null;
+    /** Optional cluster provider/region pair to show inline. */
+    cluster?: {
+        provider?: string;
+        region?: string;
+    };
+    /** Print a trailing blank line. Default true. */
+    trailingNewline?: boolean;
+}
+export declare function printContextBanner(opts?: ContextBannerOptions): void;

package/lib/cli/src/lib/context-banner.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printContextBanner = printContextBanner;
+const chalk_1 = __importDefault(require("chalk"));
+const profile_manager_1 = require("./profile-manager");
+const config_storage_1 = require("./config-storage");
+function printContextBanner(opts = {}) {
+    const profile = profile_manager_1.ProfileManager.getActiveProfile();
+    const apiUrl = opts.apiUrl ?? new config_storage_1.ConfigStorage().getApiUrl();
+    const apiDisplay = apiUrl ? chalk_1.default.dim(apiUrl) : chalk_1.default.yellow('(not set)');
+    const parts = [
+        `${chalk_1.default.bold('context')} ${chalk_1.default.cyan(profile)}`,
+        `${chalk_1.default.bold('api')} ${apiDisplay}`,
+    ];
+    if (opts.cluster?.provider) {
+        const region = opts.cluster.region ? `/${opts.cluster.region}` : '';
+        parts.push(`${chalk_1.default.bold('cluster')} ${chalk_1.default.cyan(opts.cluster.provider + region)}`);
+    }
+    console.log(chalk_1.default.dim('┌─ ') + parts.join(chalk_1.default.dim(' · ')));
+    if (opts.trailingNewline !== false)
+        console.log('');
+}

package/lib/cli/src/lib/format-bytes.d.ts

@@ -0,0 +1 @@
+export declare function formatBytes(bytes: number, fractionDigits?: number): string;

package/lib/cli/src/lib/format-bytes.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBytes = formatBytes;
+function formatBytes(bytes, fractionDigits = 1) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return 'unknown';
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    const formatted = unit === 0 ? value.toString() : value.toFixed(fractionDigits);
+    return `${formatted} ${units[unit]}`;
+}

package/lib/cli/src/lib/framework-detector.d.ts

@@ -0,0 +1,12 @@
+export interface DetectedVersion {
+    framework: string;
+    major: string;
+    source: string;
+}
+/**
+ * Try every rule in the registry against the project and return the first
+ * match. Used when the caller does not know the framework upfront (e.g.
+ * `flui deploy` running post-checks on an existing manifest).
+ */
+export declare function detectFrameworkFromProject(cwd: string): DetectedVersion | undefined;
+export declare function detectFrameworkVersion(framework: string, cwd: string): DetectedVersion | undefined;

package/lib/cli/src/lib/framework-detector.js

@@ -0,0 +1,216 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFrameworkFromProject = detectFrameworkFromProject;
+exports.detectFrameworkVersion = detectFrameworkVersion;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const RULES = [
+    { kind: 'npm', framework: 'nextjs', pkg: 'next' },
+    { kind: 'npm', framework: 'nuxt', pkg: 'nuxt' },
+    { kind: 'npm', framework: 'nestjs', pkg: '@nestjs/core' },
+    { kind: 'npm', framework: 'angular', pkg: '@angular/core' },
+    { kind: 'npm', framework: 'sveltekit', pkg: '@sveltejs/kit' },
+    { kind: 'npm', framework: 'astro', pkg: 'astro' },
+    { kind: 'pyproject', framework: 'fastapi', pkg: 'fastapi' },
+    { kind: 'pyproject', framework: 'django', pkg: 'django' },
+    { kind: 'requirements', framework: 'fastapi', pkg: 'fastapi' },
+    { kind: 'requirements', framework: 'django', pkg: 'django' },
+    { kind: 'maven', framework: 'spring-boot' },
+    { kind: 'gradle', framework: 'spring-boot' },
+    { kind: 'csproj', framework: 'aspnet-core' },
+];
+/**
+ * Try every rule in the registry against the project and return the first
+ * match. Used when the caller does not know the framework upfront (e.g.
+ * `flui deploy` running post-checks on an existing manifest).
+ */
+function detectFrameworkFromProject(cwd) {
+    for (const rule of RULES) {
+        const result = tryRule(rule, cwd);
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+function detectFrameworkVersion(framework, cwd) {
+    for (const rule of RULES.filter((r) => r.framework === framework)) {
+        const result = tryRule(rule, cwd);
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+function tryRule(rule, cwd) {
+    switch (rule.kind) {
+        case 'npm':
+            return detectNpm(rule.framework, rule.pkg, cwd);
+        case 'pyproject':
+            return detectPyproject(rule.framework, rule.pkg, cwd);
+        case 'requirements':
+            return detectRequirements(rule.framework, rule.pkg, cwd);
+        case 'maven':
+            return detectMaven(rule.framework, cwd);
+        case 'gradle':
+            return detectGradle(rule.framework, cwd);
+        case 'csproj':
+            return detectCsproj(rule.framework, cwd);
+    }
+}
+function readIfExists(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractMajor(versionSpec) {
+    const match = /(\d+)/.exec(versionSpec);
+    return match ? match[1] : undefined;
+}
+function detectNpm(framework, pkg, cwd) {
+    const file = path.join(cwd, 'package.json');
+    const raw = readIfExists(file);
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const spec = parsed.dependencies?.[pkg] ?? parsed.devDependencies?.[pkg];
+    if (!spec)
+        return undefined;
+    const major = extractMajor(spec);
+    if (!major)
+        return undefined;
+    return { framework, major, source: `package.json (${pkg}@${spec})` };
+}
+function detectPyproject(framework, pkg, cwd) {
+    const file = path.join(cwd, 'pyproject.toml');
+    const raw = readIfExists(file);
+    if (!raw)
+        return undefined;
+    const regex = new RegExp(String.raw `^\s*${escapeRegex(pkg)}\s*=\s*["']([^"']+)["']`, 'mi');
+    const match = regex.exec(raw);
+    if (!match)
+        return undefined;
+    const major = extractMajor(match[1]);
+    if (!major)
+        return undefined;
+    return {
+        framework,
+        major,
+        source: `pyproject.toml (${pkg}=${match[1]})`,
+    };
+}
+function detectRequirements(framework, pkg, cwd) {
+    const file = path.join(cwd, 'requirements.txt');
+    const raw = readIfExists(file);
+    if (!raw)
+        return undefined;
+    const regex = new RegExp(String.raw `^\s*${escapeRegex(pkg)}\s*[~=<>!]+\s*([\d.*]+)`, 'mi');
+    const match = regex.exec(raw);
+    if (!match)
+        return undefined;
+    const major = extractMajor(match[1]);
+    if (!major)
+        return undefined;
+    return {
+        framework,
+        major,
+        source: `requirements.txt (${pkg} ${match[1]})`,
+    };
+}
+function detectMaven(framework, cwd) {
+    const file = path.join(cwd, 'pom.xml');
+    const raw = readIfExists(file);
+    if (!raw)
+        return undefined;
+    const match = /spring-boot-starter-parent[\s\S]{0,500}?<version>([^<]+)<\/version>/i.exec(raw) ?? /<spring-boot\.version>([^<]+)<\/spring-boot\.version>/i.exec(raw);
+    if (!match)
+        return undefined;
+    const major = extractMajor(match[1]);
+    if (!major)
+        return undefined;
+    return {
+        framework,
+        major,
+        source: `pom.xml (spring-boot ${match[1]})`,
+    };
+}
+function detectGradle(framework, cwd) {
+    const file = ['build.gradle.kts', 'build.gradle']
+        .map((f) => path.join(cwd, f))
+        .find((f) => fs.existsSync(f));
+    if (!file)
+        return undefined;
+    const raw = readIfExists(file);
+    if (!raw)
+        return undefined;
+    const match = /org\.springframework\.boot["']?\s*\)?\s*version\s*["']([^"']+)["']/i.exec(raw);
+    if (!match)
+        return undefined;
+    const major = extractMajor(match[1]);
+    if (!major)
+        return undefined;
+    return {
+        framework,
+        major,
+        source: `${path.basename(file)} (spring-boot ${match[1]})`,
+    };
+}
+function detectCsproj(framework, cwd) {
+    const file = fs.readdirSync(cwd).find((f) => f.endsWith('.csproj'));
+    if (!file)
+        return undefined;
+    const raw = readIfExists(path.join(cwd, file));
+    if (!raw)
+        return undefined;
+    const match = /<TargetFramework>net(\d+)\.\d+<\/TargetFramework>/i.exec(raw);
+    if (!match)
+        return undefined;
+    return {
+        framework,
+        major: match[1],
+        source: `${file} (net${match[1]})`,
+    };
+}
+function escapeRegex(s) {
+    return s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+}

package/lib/cli/src/lib/framework-postchecks.d.ts

@@ -0,0 +1,11 @@
+export interface PostCheckIssue {
+    level: 'warn' | 'info';
+    title: string;
+    detail: string;
+    hint: string;
+}
+export interface FrameworkPostCheck {
+    framework: string;
+    run(targetDir: string): PostCheckIssue[];
+}
+export declare function runFrameworkPostChecks(framework: string, targetDir: string): PostCheckIssue[];

package/lib/cli/src/lib/framework-postchecks.js

@@ -0,0 +1,152 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFrameworkPostChecks = runFrameworkPostChecks;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function readIfExists(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function findFirstExisting(targetDir, names) {
+    for (const name of names) {
+        const p = path.join(targetDir, name);
+        if (fs.existsSync(p))
+            return p;
+    }
+    return undefined;
+}
+const NEXTJS_CONFIG_FILES = [
+    'next.config.js',
+    'next.config.mjs',
+    'next.config.cjs',
+    'next.config.ts',
+];
+const NEXTJS_STANDALONE_RX = /output\s*:\s*['"`]standalone['"`]/;
+const NEXTJS_CHECK = {
+    framework: 'nextjs',
+    run(targetDir) {
+        const configPath = findFirstExisting(targetDir, NEXTJS_CONFIG_FILES);
+        if (!configPath) {
+            return [
+                {
+                    level: 'warn',
+                    title: 'Missing next.config — standalone output not configured',
+                    detail: 'The Dockerfile copies from `.next/standalone` and `.next/static`, which only exist when Next.js is built with `output: "standalone"`. Without it the build will fail with "/app/.next/standalone: not found".',
+                    hint: 'Create `next.config.js` at the project root containing:\n    module.exports = { output: "standalone" };',
+                },
+            ];
+        }
+        const raw = readIfExists(configPath) ?? '';
+        if (NEXTJS_STANDALONE_RX.test(raw))
+            return [];
+        const filename = path.basename(configPath);
+        return [
+            {
+                level: 'warn',
+                title: `${filename} does not enable Next.js standalone output`,
+                detail: 'The Dockerfile copies from `.next/standalone` and `.next/static`, which only exist when Next.js is built with `output: "standalone"`. Without it the build will fail with "/app/.next/standalone: not found".',
+                hint: `Add \`output: "standalone"\` to the config object in ${filename}, for example:\n    /** @type {import("next").NextConfig} */\n    const nextConfig = {\n      output: "standalone",\n      // ...your existing options\n    };\n    module.exports = nextConfig;`,
+            },
+        ];
+    },
+};
+const NUXT_CONFIG_FILES = [
+    'nuxt.config.ts',
+    'nuxt.config.js',
+    'nuxt.config.mjs',
+];
+const NUXT_NODE_PRESET_RX = /preset\s*:\s*['"`]node[_-]server['"`]/;
+const NUXT_CHECK = {
+    framework: 'nuxt',
+    run(targetDir) {
+        const configPath = findFirstExisting(targetDir, NUXT_CONFIG_FILES);
+        if (!configPath) {
+            return [
+                {
+                    level: 'info',
+                    title: 'No nuxt.config found',
+                    detail: 'The Dockerfile runs `.output/server/index.mjs`, the default Nitro Node preset output. If you have set a custom Nitro preset (vercel, cloudflare, ...) the build artifacts will differ and the Dockerfile may need adjusting.',
+                    hint: 'No action needed if you use the default Node preset. Otherwise, ensure the Nitro preset emits a Node server entrypoint.',
+                },
+            ];
+        }
+        const raw = readIfExists(configPath) ?? '';
+        if (!NUXT_NODE_PRESET_RX.test(raw))
+            return [];
+        return [];
+    },
+};
+const SVELTEKIT_PKG = 'package.json';
+const SVELTEKIT_ADAPTER_RX = /@sveltejs\/adapter-node/;
+const SVELTEKIT_CHECK = {
+    framework: 'sveltekit',
+    run(targetDir) {
+        const pkgPath = path.join(targetDir, SVELTEKIT_PKG);
+        const raw = readIfExists(pkgPath);
+        if (!raw)
+            return [];
+        if (SVELTEKIT_ADAPTER_RX.test(raw))
+            return [];
+        return [
+            {
+                level: 'warn',
+                title: 'SvelteKit project is not using @sveltejs/adapter-node',
+                detail: 'The Dockerfile runs `node build/index.js`, the output of the Node adapter. Other adapters (vercel, cloudflare, static) emit different artifacts and the container build will fail.',
+                hint: 'Install the Node adapter and reference it in svelte.config.js:\n    npm i -D @sveltejs/adapter-node\n    // svelte.config.js\n    import adapter from "@sveltejs/adapter-node";\n    export default { kit: { adapter: adapter() } };',
+            },
+        ];
+    },
+};
+const CHECKS = new Map([
+    [NEXTJS_CHECK.framework, NEXTJS_CHECK],
+    [NUXT_CHECK.framework, NUXT_CHECK],
+    [SVELTEKIT_CHECK.framework, SVELTEKIT_CHECK],
+]);
+function runFrameworkPostChecks(framework, targetDir) {
+    const check = CHECKS.get(framework);
+    if (!check)
+        return [];
+    try {
+        return check.run(targetDir);
+    }
+    catch {
+        return [];
+    }
+}

package/lib/cli/src/lib/nest-app.d.ts

@@ -0,0 +1,17 @@
+import { INestApplication } from '@nestjs/common';
+/**
+ * Get or create NestJS application (singleton)
+ * Uses full NestJS application instead of just application context
+ * to support TypeORM and Bull which require ModuleRef
+ * @returns NestJS application
+ */
+export declare function getNestApp(): Promise<INestApplication>;
+/**
+ * Close NestJS application context and cleanup
+ */
+export declare function closeNestApp(): Promise<void>;
+/**
+ * Get service from NestJS DI container
+ * Convenience helper for type-safe service retrieval
+ */
+export declare function getService<T>(serviceClass: new (...args: any[]) => T): Promise<T>;

package/lib/cli/src/lib/nest-app.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestApp = getNestApp;
+exports.closeNestApp = closeNestApp;
+exports.getService = getService;
+const core_1 = require("@nestjs/core");
+const cli_module_1 = require("../cli.module");
+const profile_manager_1 = require("./profile-manager");
+let appInstance = null;
+/**
+ * Ensure base .flui directory exists and migrate legacy layout if needed.
+ */
+function ensureCliDataDir() {
+    profile_manager_1.ProfileManager.migrateIfNeeded();
+}
+/**
+ * Get or create NestJS application (singleton)
+ * Uses full NestJS application instead of just application context
+ * to support TypeORM and Bull which require ModuleRef
+ * @returns NestJS application
+ */
+async function getNestApp() {
+    if (!appInstance) {
+        // Ensure data directory exists before bootstrap
+        ensureCliDataDir();
+        // CLI does not use Redis — disable cache unless explicitly enabled
+        process.env.CACHE_ENABLED ??= 'false';
+        // Create full NestJS application (with HTTP server but we won't listen)
+        // This is required for TypeORM and Bull to work properly
+        appInstance = await core_1.NestFactory.create(cli_module_1.CliModule, {
+            logger: ['error', 'warn'], // Only show errors and warnings
+            abortOnError: true, // Exit on errors to see what's wrong
+        });
+        // Don't call init() - NestFactory.create() already initializes the app
+    }
+    return appInstance;
+}
+/**
+ * Close NestJS application context and cleanup
+ */
+async function closeNestApp() {
+    if (appInstance) {
+        await appInstance.close();
+        appInstance = null;
+    }
+    // process.exit() drops pending async pipe writes — flush first.
+    await Promise.all([
+        new Promise((resolve) => {
+            if (!process.stdout.writable)
+                return resolve();
+            process.stdout.write('', () => resolve());
+        }),
+        new Promise((resolve) => {
+            if (!process.stderr.writable)
+                return resolve();
+            process.stderr.write('', () => resolve());
+        }),
+    ]);
+    // Bull/TypeORM keepalive timers prevent natural exit.
+    process.exit(process.exitCode ?? 0);
+}
+/**
+ * Get service from NestJS DI container
+ * Convenience helper for type-safe service retrieval
+ */
+async function getService(serviceClass) {
+    const app = await getNestApp();
+    return app.get(serviceClass);
+}

package/lib/cli/src/lib/nip-base-domain.util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Build the nip.io base domain for a cluster.
+ *
+ * The IP is encoded with dashes (`162-55-56-10.nip.io`) so the per-cluster
+ * token (which may end in digits) cannot collide with nip.io's greedy IPv4
+ * extraction across labels.
+ */
+export declare function buildNipBaseDomain(masterIp: string, token?: string | null): string;

package/lib/cli/src/lib/nip-base-domain.util.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildNipBaseDomain = buildNipBaseDomain;
+/**
+ * Build the nip.io base domain for a cluster.
+ *
+ * The IP is encoded with dashes (`162-55-56-10.nip.io`) so the per-cluster
+ * token (which may end in digits) cannot collide with nip.io's greedy IPv4
+ * extraction across labels.
+ */
+function buildNipBaseDomain(masterIp, token) {
+    const ip = masterIp.replaceAll('.', '-');
+    if (token) {
+        return `${token}.${ip}.nip.io`;
+    }
+    return `${ip}.nip.io`;
+}