@nocobase/cli 2.1.0-beta.9 → 2.1.0

package/dist/lib/auth-store.js

@@ -0,0 +1,528 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { resolveAppPublicPath } from './app-public-path.js';
+import { resolveCliHomeDir, resolveConfiguredEnvPath, resolveEnvRelativePath } from './cli-home.js';
+import { normalizeCliLocale } from './cli-locale.js';
+import { inferConfiguredAppPathFromLegacyConfig, resolveConfiguredAppPath, resolveConfiguredSourcePath, resolveConfiguredStoragePath, } from './env-paths.js';
+import { cleanupCurrentSessionAfterEnvRemoval, resolveEffectiveCurrentEnv, setSessionCurrentEnv, } from './session-store.js';
+function normalizeStoredEnvKind(value) {
+    const kind = String(value ?? '').trim();
+    if (kind === 'remote') {
+        return 'http';
+    }
+    if (kind === 'local' || kind === 'http' || kind === 'docker' || kind === 'ssh') {
+        return kind;
+    }
+    return undefined;
+}
+function normalizeOptionalString(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+function normalizeOptionalCliLocale(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return undefined;
+    }
+    return normalizeCliLocale(normalized);
+}
+function normalizeOptionalCliUpdatePolicy(value) {
+    const normalized = normalizeOptionalString(value);
+    if (normalized === 'prompt' || normalized === 'auto' || normalized === 'off') {
+        return normalized;
+    }
+    return undefined;
+}
+export function readEnvApiBaseUrl(config) {
+    if (!config) {
+        return undefined;
+    }
+    return (normalizeOptionalString(config.apiBaseUrl) ??
+        normalizeOptionalString(config.baseUrl) ??
+        normalizeOptionalString(config.apibaseUrl));
+}
+export function resolveEnvKind(config) {
+    if (!config) {
+        return undefined;
+    }
+    const explicitKind = normalizeStoredEnvKind(config.kind);
+    if (explicitKind) {
+        return explicitKind;
+    }
+    const source = String(config.source ?? '').trim();
+    if (source === 'docker') {
+        return 'docker';
+    }
+    if (source === 'npm' || source === 'git' || source === 'local') {
+        return 'local';
+    }
+    if (String(config.appPath ?? '').trim() || String(config.appRootPath ?? '').trim()) {
+        return 'local';
+    }
+    if (readEnvApiBaseUrl(config) || config.auth) {
+        return 'http';
+    }
+    return undefined;
+}
+function normalizeEnvConfigEntry(entry) {
+    if (!entry) {
+        return entry;
+    }
+    const { kind: _kind, apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, ...rest } = entry;
+    const normalizedKind = resolveEnvKind(entry);
+    const apiBaseUrl = readEnvApiBaseUrl(entry);
+    return {
+        ...rest,
+        ...(normalizedKind ? { kind: normalizedKind } : {}),
+        ...(apiBaseUrl !== undefined ? { apiBaseUrl } : {}),
+        ...(normalizeOptionalString(entry.appPublicPath) ? { appPublicPath: resolveAppPublicPath(entry.appPublicPath) } : {}),
+    };
+}
+function normalizeAuthConfig(config) {
+    const settings = config.settings ?? {};
+    const locale = normalizeOptionalCliLocale(settings.locale);
+    const defaultUiHost = normalizeOptionalString(settings.init?.defaultUiHost);
+    const defaultApiHost = normalizeOptionalString(settings.init?.defaultApiHost);
+    const updatePolicy = normalizeOptionalCliUpdatePolicy(settings.update?.policy);
+    const logRetentionDays = typeof settings.log?.retentionDays === 'number' && Number.isInteger(settings.log.retentionDays)
+        ? settings.log.retentionDays
+        : undefined;
+    const logEnabled = typeof settings.log?.enabled === 'boolean' ? settings.log.enabled : undefined;
+    return {
+        name: config.name || config.dockerResourcePrefix,
+        settings: {
+            ...(locale ? { locale } : {}),
+            ...(defaultUiHost || defaultApiHost
+                ? {
+                    init: {
+                        ...(defaultUiHost ? { defaultUiHost } : {}),
+                        ...(defaultApiHost ? { defaultApiHost } : {}),
+                    },
+                }
+                : {}),
+            ...(updatePolicy ? { update: { policy: updatePolicy } } : {}),
+            ...(settings.license?.pkgUrl ? { license: { pkgUrl: normalizeOptionalString(settings.license.pkgUrl) } } : {}),
+            ...(settings.docker?.network || settings.docker?.containerPrefix
+                ? {
+                    docker: {
+                        ...(settings.docker?.network ? { network: normalizeOptionalString(settings.docker.network) } : {}),
+                        ...(settings.docker?.containerPrefix
+                            ? { containerPrefix: normalizeOptionalString(settings.docker.containerPrefix) }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(settings.bin?.docker || settings.bin?.caddy || settings.bin?.git || settings.bin?.nginx || settings.bin?.yarn
+                ? {
+                    bin: {
+                        ...(settings.bin?.docker ? { docker: normalizeOptionalString(settings.bin.docker) } : {}),
+                        ...(settings.bin?.caddy ? { caddy: normalizeOptionalString(settings.bin.caddy) } : {}),
+                        ...(settings.bin?.git ? { git: normalizeOptionalString(settings.bin.git) } : {}),
+                        ...(settings.bin?.nginx ? { nginx: normalizeOptionalString(settings.bin.nginx) } : {}),
+                        ...(settings.bin?.yarn ? { yarn: normalizeOptionalString(settings.bin.yarn) } : {}),
+                    },
+                }
+                : {}),
+            ...(settings.proxy?.nbCliRoot ||
+                settings.proxy?.caddyDriver ||
+                settings.proxy?.nginxDriver ||
+                settings.proxy?.upstreamHost ||
+                settings.proxy?.host
+                ? {
+                    proxy: {
+                        ...(settings.proxy?.nbCliRoot ? { nbCliRoot: normalizeOptionalString(settings.proxy.nbCliRoot) } : {}),
+                        ...(settings.proxy?.caddyDriver
+                            ? { caddyDriver: normalizeOptionalString(settings.proxy.caddyDriver) }
+                            : {}),
+                        ...(settings.proxy?.nginxDriver
+                            ? { nginxDriver: normalizeOptionalString(settings.proxy.nginxDriver) }
+                            : {}),
+                        ...(settings.proxy?.upstreamHost || settings.proxy?.host
+                            ? {
+                                upstreamHost: normalizeOptionalString(settings.proxy?.upstreamHost ?? settings.proxy.host),
+                            }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(logEnabled !== undefined || logRetentionDays !== undefined
+                ? {
+                    log: {
+                        ...(logEnabled !== undefined ? { enabled: logEnabled } : {}),
+                        ...(logRetentionDays !== undefined ? { retentionDays: logRetentionDays } : {}),
+                    },
+                }
+                : {}),
+        },
+        lastEnv: config.lastEnv ||
+            config.currentEnv ||
+            'default',
+        envs: Object.fromEntries(Object.entries(config.envs || {}).map(([envName, entry]) => [envName, normalizeEnvConfigEntry(entry) ?? {}])),
+    };
+}
+function getConfigFile(options = {}) {
+    return path.join(resolveCliHomeDir(options.scope), 'config.json');
+}
+function createDefaultConfig() {
+    return {
+        lastEnv: 'default',
+        envs: {},
+    };
+}
+async function readStoredAuthConfig(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        return normalizeAuthConfig(parsed);
+    }
+    catch (_error) {
+        return undefined;
+    }
+}
+export async function loadExactAuthConfig(options = {}) {
+    return (await readStoredAuthConfig(getConfigFile(options))) ?? createDefaultConfig();
+}
+export async function loadAuthConfig(options = {}) {
+    return await loadExactAuthConfig(options);
+}
+export async function saveAuthConfig(config, options = {}) {
+    const filePath = getConfigFile(options);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(normalizeAuthConfig(config), null, 2));
+}
+export async function listEnvs(options = {}) {
+    const config = await loadAuthConfig(options);
+    return {
+        lastEnv: config.lastEnv || 'default',
+        envs: config.envs,
+    };
+}
+export async function getCurrentEnvName(options = {}) {
+    const config = await loadAuthConfig(options);
+    return await resolveEffectiveCurrentEnv(Object.keys(config.envs).sort(), {
+        scope: options.scope,
+        lastEnv: config.lastEnv,
+    });
+}
+export async function setCurrentEnv(envName, options = {}) {
+    const config = await loadExactAuthConfig(options);
+    if (!config.envs[envName]) {
+        throw new Error(`Env "${envName}" is not configured`);
+    }
+    config.lastEnv = envName;
+    await setSessionCurrentEnv(envName, options.scope);
+    await saveAuthConfig(config, options);
+}
+export class Env {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    get name() {
+        return this.config.name;
+    }
+    get baseUrl() {
+        return readEnvApiBaseUrl(this.config);
+    }
+    get apiBaseUrl() {
+        return readEnvApiBaseUrl(this.config);
+    }
+    get auth() {
+        return this.config.auth;
+    }
+    get authType() {
+        return resolveConfiguredAuthType(this.config);
+    }
+    get runtime() {
+        return this.config.runtime;
+    }
+    get kind() {
+        return resolveEnvKind(this.config);
+    }
+    get appRootPath() {
+        if (this.kind === 'ssh') {
+            const configuredPath = String(this.config.appRootPath ?? '').trim();
+            if (configuredPath) {
+                return configuredPath;
+            }
+        }
+        const legacyPath = resolveConfiguredEnvPath(this.config.appRootPath);
+        if (legacyPath) {
+            return legacyPath;
+        }
+        return this.kind === 'local' ? this.sourcePath : resolveEnvRelativePath('.');
+    }
+    get appPath() {
+        if (this.kind === 'ssh') {
+            const configuredPath = String(this.config.appPath ?? inferConfiguredAppPathFromLegacyConfig(this.config) ?? '').trim();
+            if (configuredPath) {
+                return configuredPath;
+            }
+        }
+        return resolveConfiguredAppPath(this.config) ?? resolveEnvRelativePath('.');
+    }
+    get sourcePath() {
+        if (this.kind === 'ssh') {
+            const configuredPath = String(this.config.appRootPath ?? '').trim();
+            if (configuredPath) {
+                return configuredPath;
+            }
+        }
+        return resolveConfiguredSourcePath(this.config) ?? path.join(this.appPath, 'source');
+    }
+    get storagePath() {
+        if (this.kind === 'ssh') {
+            const configuredPath = String(this.config.storagePath ?? '').trim();
+            if (configuredPath) {
+                return configuredPath;
+            }
+        }
+        const resolvedStoragePath = resolveConfiguredStoragePath(this.config);
+        if (resolvedStoragePath) {
+            return resolvedStoragePath;
+        }
+        return this.kind === 'local' || this.kind === 'docker'
+            ? path.join(this.appPath, 'storage')
+            : resolveEnvRelativePath('.');
+    }
+    get appPort() {
+        return this.config.appPort;
+    }
+    get envVars() {
+        const out = {
+            STORAGE_PATH: this.storagePath,
+        };
+        const put = (key, value) => {
+            if (value === undefined || value === null) {
+                return;
+            }
+            out[key] = String(value);
+        };
+        put('APP_PORT', this.appPort);
+        put('APP_PUBLIC_PATH', this.config.appPublicPath ? resolveAppPublicPath(this.config.appPublicPath) : undefined);
+        put('CDN_BASE_URL', this.config.cdnBaseUrl);
+        put('APP_KEY', this.config.appKey);
+        put('TZ', this.config.timezone);
+        put('DB_DIALECT', this.config.dbDialect);
+        if (!this.config.builtinDb) {
+            put('DB_HOST', this.config.dbHost);
+            put('DB_PORT', this.config.dbPort);
+        }
+        else if (String(this.config.source ?? '').trim() !== 'docker') {
+            put('DB_PORT', this.config.dbPort);
+        }
+        put('DB_DATABASE', this.config.dbDatabase);
+        put('DB_USER', this.config.dbUser);
+        put('DB_PASSWORD', this.config.dbPassword);
+        put('DB_SCHEMA', this.config.dbSchema);
+        put('DB_TABLE_PREFIX', this.config.dbTablePrefix);
+        put('DB_UNDERSCORED', this.config.dbUnderscored);
+        return out;
+    }
+}
+export async function getEnv(envName, options = {}) {
+    const { config: snapshot, ...loadOptions } = options;
+    const config = snapshot ?? (await loadAuthConfig(loadOptions));
+    const resolved = envName?.trim() ||
+        (await resolveEffectiveCurrentEnv(Object.keys(config.envs).sort(), {
+            scope: loadOptions.scope,
+            lastEnv: config.lastEnv,
+        }));
+    const envConfig = config.envs[resolved];
+    if (!envConfig) {
+        return undefined;
+    }
+    return new Env({ ...(normalizeEnvConfigEntry(envConfig) ?? {}), name: resolved });
+}
+function areAuthConfigsEquivalent(left, right) {
+    if (!left && !right) {
+        return true;
+    }
+    if (!left || !right || left.type !== right.type) {
+        return false;
+    }
+    if (left.type === 'token' && right.type === 'token') {
+        return left.accessToken === right.accessToken;
+    }
+    if (left.type === 'oauth' && right.type === 'oauth') {
+        return (left.accessToken === right.accessToken &&
+            left.refreshToken === right.refreshToken &&
+            left.expiresAt === right.expiresAt &&
+            left.scope === right.scope &&
+            left.issuer === right.issuer &&
+            left.clientId === right.clientId &&
+            left.resource === right.resource);
+    }
+    return false;
+}
+async function writeEnv(envName, updater, options = {}) {
+    const config = await loadExactAuthConfig(options);
+    const previous = config.envs[envName];
+    config.envs[envName] = updater(previous);
+    await saveAuthConfig(config, options);
+}
+function normalizeConfiguredAuthType(value) {
+    return value === 'basic' || value === 'token' || value === 'oauth' ? value : undefined;
+}
+export function resolveConfiguredAuthType(config) {
+    return normalizeConfiguredAuthType(config?.authType) ?? normalizeConfiguredAuthType(config?.auth?.type);
+}
+export async function upsertEnv(envName, config, options = {}) {
+    await writeEnv(envName, (previous) => {
+        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, ...rest } = config;
+        const nextApiBaseUrl = readEnvApiBaseUrl(config);
+        const previousApiBaseUrl = readEnvApiBaseUrl(previous);
+        const baseUrlChanged = previousApiBaseUrl !== nextApiBaseUrl;
+        const previousAuthType = resolveConfiguredAuthType(previous);
+        const requestedAuthType = normalizeConfiguredAuthType(authType);
+        const nextAuthType = requestedAuthType ?? (accessToken ? 'token' : previousAuthType);
+        const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(authUsername) ?? previous?.authUsername : undefined;
+        const nextAuth = accessToken
+            ? {
+                type: 'token',
+                accessToken,
+            }
+            : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
+                ? previous.auth
+                : undefined;
+        const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
+        const authTypeChanged = previousAuthType !== nextAuthType;
+        const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
+        return {
+            ...previous,
+            apiBaseUrl: nextApiBaseUrl,
+            authType: nextAuthType,
+            authUsername: nextAuthUsername,
+            auth: nextAuth,
+            ...rest,
+            runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
+        };
+    }, options);
+}
+export async function updateEnvConnection(envName, updates, options = {}) {
+    await writeEnv(envName, (previous) => {
+        const nextApiBaseUrl = readEnvApiBaseUrl(updates) ?? readEnvApiBaseUrl(previous);
+        const previousApiBaseUrl = readEnvApiBaseUrl(previous);
+        const baseUrlChanged = previousApiBaseUrl !== nextApiBaseUrl;
+        const previousAuthType = resolveConfiguredAuthType(previous);
+        const requestedAuthType = normalizeConfiguredAuthType(updates.authType);
+        const nextAuthType = requestedAuthType ?? (updates.accessToken ? 'token' : previousAuthType);
+        const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(updates.authUsername) ?? previous?.authUsername : undefined;
+        const nextAuth = updates.accessToken
+            ? {
+                type: 'token',
+                accessToken: updates.accessToken,
+            }
+            : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
+                ? previous.auth
+                : undefined;
+        const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
+        const authTypeChanged = previousAuthType !== nextAuthType;
+        const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
+        return {
+            ...previous,
+            ...(nextApiBaseUrl !== undefined ? { apiBaseUrl: nextApiBaseUrl } : {}),
+            authType: nextAuthType,
+            authUsername: nextAuthUsername,
+            auth: nextAuth,
+            runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
+        };
+    }, options);
+}
+export async function replaceEnvConfig(envName, config, options = {}) {
+    await writeEnv(envName, (previous) => {
+        if (!previous) {
+            throw new Error(`Env "${envName}" is not configured`);
+        }
+        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, ...rest } = config;
+        const nextApiBaseUrl = readEnvApiBaseUrl(config);
+        const previousApiBaseUrl = readEnvApiBaseUrl(previous);
+        const baseUrlChanged = previousApiBaseUrl !== nextApiBaseUrl;
+        const previousAuthType = resolveConfiguredAuthType(previous);
+        const nextAuthType = normalizeConfiguredAuthType(authType) ?? (accessToken ? 'token' : undefined);
+        const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(authUsername) : undefined;
+        const nextAuth = accessToken
+            ? {
+                type: 'token',
+                accessToken,
+            }
+            : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
+                ? previous.auth
+                : undefined;
+        const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
+        const authTypeChanged = previousAuthType !== nextAuthType;
+        const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
+        return {
+            ...rest,
+            ...(nextApiBaseUrl !== undefined ? { apiBaseUrl: nextApiBaseUrl } : {}),
+            ...(nextAuthType ? { authType: nextAuthType } : {}),
+            ...(nextAuthUsername ? { authUsername: nextAuthUsername } : {}),
+            ...(nextAuth ? { auth: nextAuth } : {}),
+            runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
+        };
+    }, options);
+}
+export async function setEnvOauthSession(envName, auth, options = {}) {
+    await writeEnv(envName, (previous) => ({
+        ...previous,
+        authType: 'oauth',
+        auth,
+        runtime: options.preserveRuntime ? previous?.runtime : undefined,
+    }), options);
+}
+export async function setEnvRuntime(envName, runtime, options = {}) {
+    const config = await loadExactAuthConfig(options);
+    const current = config.envs[envName] ?? {};
+    config.envs[envName] = {
+        ...current,
+        runtime,
+    };
+    await saveAuthConfig(config, options);
+}
+export async function clearEnvRootSetup(envName, options = {}) {
+    const config = await loadExactAuthConfig(options);
+    const current = config.envs[envName];
+    if (!current) {
+        return false;
+    }
+    const { rootUsername: _rootUsername, rootEmail: _rootEmail, rootPassword: _rootPassword, rootNickname: _rootNickname, ...rest } = current;
+    config.envs[envName] = rest;
+    await saveAuthConfig(config, options);
+    return true;
+}
+export async function removeEnv(envName, options = {}) {
+    const config = await loadExactAuthConfig(options);
+    if (!config.envs[envName]) {
+        throw new Error(`Env "${envName}" is not configured`);
+    }
+    delete config.envs[envName];
+    if (config.lastEnv === envName) {
+        const nextEnv = Object.keys(config.envs).sort()[0];
+        config.lastEnv = nextEnv ?? 'default';
+    }
+    await saveAuthConfig(config, options);
+    const remainingEnvNames = Object.keys(config.envs).sort();
+    const fallbackEnv = remainingEnvNames.length
+        ? await resolveEffectiveCurrentEnv(remainingEnvNames, {
+            scope: options.scope,
+            lastEnv: config.lastEnv,
+        })
+        : undefined;
+    await cleanupCurrentSessionAfterEnvRemoval(envName, {
+        scope: options.scope,
+        fallbackEnv,
+    });
+    return {
+        removed: envName,
+        lastEnv: config.lastEnv || 'default',
+        hasEnvs: Object.keys(config.envs).length > 0,
+    };
+}

package/dist/lib/backup.js

@@ -0,0 +1,171 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getCurrentEnvName, getEnv, listEnvs } from './auth-store.js';
+import { updateEnvRuntime } from './bootstrap.js';
+import { resolveDefaultConfigScope } from './cli-home.js';
+import { commandOutput } from './run-npm.js';
+import { loadRuntimeSync } from './runtime-store.js';
+import { failTask, startTask, succeedTask } from './ui.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const CLI_CONFIG_FILE = path.join(CLI_PACKAGE_ROOT, 'nocobase-ctl.config.json');
+const CLI_ENTRY_FILE = path.join(CLI_PACKAGE_ROOT, 'bin', 'run.js');
+export const BACKUP_POLL_INTERVAL_MS = 2_000;
+export const BACKUP_CREATE_TIMEOUT_MS = 600_000;
+export const BACKUP_RUNTIME_COMMANDS = {
+    create: 'backup create',
+    status: 'backup status',
+    download: 'backup download',
+    restoreUpload: 'backup restore-upload',
+};
+function hasRequiredBackupCommands(runtime, commandIds) {
+    if (!runtime) {
+        return false;
+    }
+    const available = new Set(runtime.commands.map((command) => command.commandId));
+    return commandIds.every((commandId) => available.has(commandId));
+}
+function formatMissingBackupRuntimeCommands(envName, commandIds) {
+    const missing = commandIds.map((commandId) => `nb api ${commandId}`).join(', ');
+    return [
+        `The selected env "${envName}" does not expose the backup API commands required by \`nb backup\`.`,
+        `Missing commands: ${missing}`,
+        'Enable or upgrade the backup/restore capability for that env, then try again.',
+    ].join('\n');
+}
+export function buildBackupEnvArgv(options) {
+    const argv = [];
+    if (options.explicitEnvSelection && options.requestedEnv) {
+        argv.push('--env', options.requestedEnv);
+    }
+    if (options.yes || options.explicitEnvSelection) {
+        argv.push('--yes');
+    }
+    return argv;
+}
+export async function resolveBackupTargetEnv(requestedEnv) {
+    const scope = resolveDefaultConfigScope();
+    const envName = requestedEnv?.trim() || (await getCurrentEnvName({ scope }));
+    const env = await getEnv(envName, { scope });
+    if (env) {
+        return { scope, envName, env };
+    }
+    const { envs } = await listEnvs({ scope });
+    const configuredEnvNames = Object.keys(envs);
+    if (!configuredEnvNames.length) {
+        throw new Error('No env is configured. Run `nb init --ui` first.');
+    }
+    if (requestedEnv?.trim()) {
+        throw new Error(`Env "${envName}" is not configured. Run \`nb init --ui --env ${envName}\` first.`);
+    }
+    throw new Error([
+        `Current env "${envName}" is not configured.`,
+        `Switch to an existing env with \`nb env use <name>\`, or run \`nb init --ui --env ${envName}\` to create or connect it.`,
+    ].join('\n'));
+}
+export async function ensureBackupRuntimeCommands(params) {
+    const scope = resolveDefaultConfigScope();
+    const env = params.env ?? (await getEnv(params.envName, { scope }));
+    const currentRuntime = loadRuntimeSync(env?.runtime?.version, { scope });
+    if (hasRequiredBackupCommands(currentRuntime, params.commandIds)) {
+        return;
+    }
+    if (!params.quiet) {
+        startTask(`Refreshing env runtime for "${params.envName}" to load backup commands...`);
+    }
+    try {
+        const runtime = await updateEnvRuntime({
+            envName: params.envName,
+            scope,
+            configFile: CLI_CONFIG_FILE,
+            quiet: params.quiet,
+        });
+        if (!hasRequiredBackupCommands(runtime, params.commandIds)) {
+            throw new Error(formatMissingBackupRuntimeCommands(params.envName, params.commandIds));
+        }
+        if (!params.quiet) {
+            succeedTask(`Env runtime is ready for backup commands in "${params.envName}".`);
+        }
+    }
+    catch (error) {
+        if (!params.quiet) {
+            failTask(`Failed to refresh backup commands for "${params.envName}".`);
+        }
+        throw error;
+    }
+}
+export async function runBackupCliCommand(argv, options) {
+    return await commandOutput(process.execPath, [CLI_ENTRY_FILE, ...argv], {
+        errorName: options?.errorName ?? `nb ${argv.join(' ')}`,
+        env: {
+            NB_SKIP_STARTUP_UPDATE: '1',
+            // When the parent CLI already runs in tsx source mode, it sets
+            // `_NOCO_CLI_TSX_CHILD=1`. Clear it here so `bin/run.js` can re-exec
+            // itself with `--import tsx` again instead of trying to import `.ts`
+            // sources without the loader.
+            _NOCO_CLI_TSX_CHILD: '',
+        },
+    });
+}
+export async function runBackupCliJsonCommand(argv, options) {
+    const output = await runBackupCliCommand([...argv, '--json-output'], options);
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        throw new Error(`Unexpected JSON output from ${options?.errorName ?? `nb ${argv.join(' ')}`}: ${output || '(empty output)'}`);
+    }
+}
+export async function resolveBackupCreateOutputPath(output, remoteName) {
+    const requestedOutput = String(output ?? '').trim();
+    if (!requestedOutput) {
+        return path.resolve(process.cwd(), remoteName);
+    }
+    const resolvedOutput = path.resolve(process.cwd(), requestedOutput);
+    try {
+        const stats = await fs.stat(resolvedOutput);
+        if (stats.isDirectory()) {
+            return path.join(resolvedOutput, remoteName);
+        }
+    }
+    catch {
+        // Treat non-existing paths as an explicit target file path.
+    }
+    return resolvedOutput;
+}
+export async function resolveBackupRestoreFilePath(file) {
+    const resolvedFile = path.resolve(process.cwd(), file);
+    let stats;
+    try {
+        stats = await fs.stat(resolvedFile);
+    }
+    catch {
+        throw new Error(`Backup file not found: ${resolvedFile}`);
+    }
+    if (!stats.isFile()) {
+        throw new Error(`Backup restore input must be a file: ${resolvedFile}`);
+    }
+    return resolvedFile;
+}
+export function resolveBackupWaitApiBaseUrl(env) {
+    const baseUrl = String(env.baseUrl ?? '').trim();
+    if (baseUrl) {
+        return baseUrl.replace(/\/+$/, '');
+    }
+    const appPort = env.appPort === undefined || env.appPort === null
+        ? ''
+        : String(env.appPort).trim();
+    return appPort ? `http://127.0.0.1:${appPort}/api` : undefined;
+}
+export async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}