@nocobase/cli 2.2.0-alpha.1 → 2.2.0-alpha.2

package/dist/commands/source/dev.js

@@ -8,8 +8,9 @@
  */
 import { Command, Flags } from '@oclif/core';
 import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
-import { ensureLocalPostinstall } from '../../lib/app-managed-resources.js';
+import { ensureLocalPostinstall, ensureNpmSourceDevDependencies } from '../../lib/app-managed-resources.js';
 import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, runLocalNocoBaseCommand, } from '../../lib/app-runtime.js';
+import { findAvailableTcpPort } from '../../lib/prompt-validators.js';
 import { announceTargetEnv, failTask, printInfo, startTask, succeedTask } from '../../lib/ui.js';
 function formatUnsupportedRuntimeMessage(kind, envName) {
     if (kind === 'docker') {
@@ -129,10 +130,7 @@ export default class SourceDev extends Command {
             this.error(formatUnsupportedRuntimeMessage(runtime.kind, runtime.envName));
         }
         announceTargetEnv(runtime.envName);
-        const devPort = flags.port ||
-            (runtime.env.appPort !== undefined && runtime.env.appPort !== null
-                ? String(runtime.env.appPort).trim()
-                : undefined);
+        const devPort = flags.port?.trim() || (await findAvailableTcpPort());
         const appUrl = appUrlForPort(devPort);
         if (await isAppAlreadyRunning(appUrl)) {
             this.error([
@@ -160,6 +158,12 @@ export default class SourceDev extends Command {
         }
         printInfo(`Starting NocoBase dev mode for "${runtime.envName}" from ${runtime.projectRoot}. Press Ctrl+C to stop.`);
         try {
+            await ensureNpmSourceDevDependencies(runtime, {
+                onStartTask: startTask,
+                onSucceedTask: succeedTask,
+                onFailTask: failTask,
+                verbose: true,
+            });
             await ensureLocalPostinstall(runtime, {
                 onStartTask: startTask,
                 onSucceedTask: succeedTask,

package/dist/commands/source/download.js

@@ -13,10 +13,13 @@ import { stdin as stdinStream, stdout as stdoutStream } from 'node:process';
 import { runPromptCatalog, } from "../../lib/prompt-catalog.js";
 import { applyCliLocale, CLI_LOCALE_FLAG_DESCRIPTION, CLI_LOCALE_FLAG_OPTIONS, localeText, resolveCliLocale, translateCli, } from "../../lib/cli-locale.js";
 import { DEFAULT_DOCKER_REGISTRY, DEFAULT_DOCKER_REGISTRY_ZH_CN, resolveDockerImageRef, } from "../../lib/docker-image.js";
+import { getEnv } from '../../lib/auth-store.js';
+import { resolveDefaultConfigScope } from '../../lib/cli-home.js';
+import { buildBeforeDependencyInstallHookContext, runBeforeDependencyInstallHook, } from '../../lib/hook-script.js';
 import { run } from "../../lib/run-npm.js";
 import { printVerbose, setVerboseMode, startTask, stopTask, updateTask } from '../../lib/ui.js';
 const DEFAULT_DOCKER_PLATFORM = 'auto';
-const DEFAULT_DOWNLOAD_VERSION = 'beta';
+const DEFAULT_DOWNLOAD_VERSION = 'latest';
 const downloadText = (key, values) => localeText(`commands.download.${key}`, values);
 const downloadTranslatedText = (key, values, fallback) => translateCli(`commands.download.${key}`, values, { fallback });
 function defaultOutputDirForVersion(versionTag) {
@@ -231,6 +234,26 @@ export default class SourceDownload extends Command {
         'npm-registry': Flags.string({
             description: 'npm registry for npm/git downloads and dependency installation.',
         }),
+        'hook-script': Flags.string({
+            description: 'Hook module to run after npm scaffold or git clone and before dependency installation.',
+        }),
+        'hook-phase': Flags.string({
+            hidden: true,
+            options: ['init', 'upgrade', 'restore', 'source-download', 'app-start'],
+        }),
+        'hook-command': Flags.string({
+            hidden: true,
+            options: ['init', 'source:download', 'app:start', 'app:restart', 'app:upgrade'],
+        }),
+        'hook-env-name': Flags.string({
+            hidden: true,
+        }),
+        'hook-app-path': Flags.string({
+            hidden: true,
+        }),
+        'hook-storage-path': Flags.string({
+            hidden: true,
+        }),
         build: Flags.boolean({
             allowNo: true,
             description: 'Build npm/git source after dependencies are installed.',
@@ -276,7 +299,6 @@ export default class SourceDownload extends Command {
                     value: 'latest',
                     label: downloadText('prompts.version.latestLabel'),
                     hint: downloadText('prompts.version.latestHint'),
-                    disabled: true,
                 },
                 {
                     value: 'beta',
@@ -574,6 +596,9 @@ export default class SourceDownload extends Command {
         const npmRegistryRaw = results.npmRegistry !== undefined ? String(results.npmRegistry) : flags['npm-registry'] ?? '';
         const npmRegistry = npmRegistryRaw.trim() || undefined;
         const npmDevDependencies = devDependencies ?? false;
+        const hookScript = flags['hook-script']?.trim()
+            ? path.resolve(process.cwd(), flags['hook-script'].trim())
+            : undefined;
         return {
             source,
             version,
@@ -587,6 +612,14 @@ export default class SourceDownload extends Command {
             ...(source === 'docker' ? { 'docker-platform': dockerPlatform } : {}),
             ...(source === 'docker' ? { 'docker-save': dockerSave } : {}),
             ...(npmRegistry ? { 'npm-registry': npmRegistry } : {}),
+            ...(hookScript ? { 'hook-script': hookScript } : {}),
+            ...(flags['hook-phase'] ? { 'hook-phase': flags['hook-phase'] } : {}),
+            ...(flags['hook-command'] ? { 'hook-command': flags['hook-command'] } : {}),
+            ...(flags['hook-env-name'] ? { 'hook-env-name': flags['hook-env-name'].trim() } : {}),
+            ...(flags['hook-app-path'] ? { 'hook-app-path': path.resolve(process.cwd(), flags['hook-app-path']) } : {}),
+            ...(flags['hook-storage-path']
+                ? { 'hook-storage-path': path.resolve(process.cwd(), flags['hook-storage-path']) }
+                : {}),
         };
     }
     async resolveDownloadFlags(flags) {
@@ -719,6 +752,36 @@ export default class SourceDownload extends Command {
         }
         return argv;
     }
+    async runBeforeDependencyInstallHookIfNeeded(flags, projectRoot) {
+        const hookScript = flags['hook-script']?.trim();
+        if (!hookScript || (flags.source !== 'npm' && flags.source !== 'git')) {
+            return;
+        }
+        const envName = flags['hook-env-name']?.trim() || '';
+        const env = envName ? await getEnv(envName, { scope: resolveDefaultConfigScope() }) : undefined;
+        const appPath = flags['hook-app-path']?.trim() || projectRoot;
+        const storagePath = flags['hook-storage-path']?.trim() || path.join(appPath, 'storage');
+        const context = buildBeforeDependencyInstallHookContext({
+            phase: flags['hook-phase'] ?? 'source-download',
+            command: flags['hook-command'] ?? 'source:download',
+            envName,
+            source: flags.source,
+            version: flags.version,
+            appPath,
+            sourcePath: projectRoot,
+            storagePath,
+            hookScript,
+            envConfig: env?.config ?? {},
+        });
+        if (!context) {
+            return;
+        }
+        this.log(`Running hook before dependency install: ${hookScript}`);
+        await runBeforeDependencyInstallHook({
+            hookScriptPath: hookScript,
+            context,
+        });
+    }
     async downloadFromDocker(flags) {
         const imageRef = resolveDockerImageRef(flags['docker-registry'], flags.version, {
             defaultRegistry: defaultDockerRegistryForLang(process.env.NB_LOCALE),
@@ -778,6 +841,7 @@ export default class SourceDownload extends Command {
             errorName: 'npx create-nocobase-app',
             loadingMessage: 'Creating the app scaffold',
         });
+        await this.runBeforeDependencyInstallHookIfNeeded(flags, projectRoot);
         const installArgs = ['install'];
         if (!flags['dev-dependencies']) {
             installArgs.push('--production');
@@ -821,6 +885,7 @@ export default class SourceDownload extends Command {
         });
         const projectRoot = path.resolve(process.cwd(), outputDir);
         const registryEnv = this.npmRegistryEnv(flags);
+        await this.runBeforeDependencyInstallHookIfNeeded(flags, projectRoot);
         this.log(`Installing dependencies in ${projectRoot}`);
         await this.runExternalCommand('yarn', ['install'], {
             ...this.runOptionsWithCwd(projectRoot, registryEnv),

package/dist/lib/api-command-compat.js

@@ -114,12 +114,22 @@ function compareWithOperator(version, operator, expected) {
 }
 function normalizeAppByChannelComparableVersion(version) {
     const normalized = String(version ?? '').trim();
-    const match = normalized.match(/^(\d+\.\d+\.\d+)-(alpha|beta|rc)(?:\.(\d+))?(?:\..+)?$/);
+    const match = normalized.match(/^(\d+\.\d+\.\d+)(?:-([0-9A-Za-z-.]+))?$/);
     if (!match) {
         return normalized;
     }
-    const [, base, channel, sequence] = match;
-    return sequence ? `${base}-${channel}.${sequence}` : `${base}-${channel}`;
+    const [, base, prerelease] = match;
+    if (!prerelease) {
+        return base;
+    }
+    const [channel, sequence] = prerelease.split('.');
+    if ((channel === 'alpha' || channel === 'beta') && sequence && /^\d+$/.test(sequence)) {
+        return `${base}-${channel}.${sequence}`;
+    }
+    if (channel === 'alpha' || channel === 'beta') {
+        return `${base}-${channel}`;
+    }
+    return base;
 }
 function normalizeAppByChannelCondition(condition) {
     if (!condition) {
@@ -134,6 +144,42 @@ function normalizeAppByChannelCondition(condition) {
     }
     return normalized;
 }
+function compareAppByChannelVersions(version, expected) {
+    const comparableVersion = normalizeAppByChannelComparableVersion(version);
+    const comparableExpected = normalizeAppByChannelComparableVersion(expected);
+    if (comparableVersion === comparableExpected ||
+        comparableVersion.startsWith(`${comparableExpected}.`) ||
+        comparableVersion.startsWith(`${comparableExpected}-`)) {
+        return 0;
+    }
+    return compareVersions(comparableVersion, comparableExpected);
+}
+function compareAppByChannelWithOperator(version, operator, expected) {
+    const compared = compareAppByChannelVersions(version, expected);
+    switch (operator) {
+        case 'eq':
+            return compared === 0;
+        case 'gt':
+            return compared > 0;
+        case 'gte':
+            return compared >= 0;
+        case 'lt':
+            return compared < 0;
+        case 'lte':
+            return compared <= 0;
+        default:
+            return false;
+    }
+}
+function matchesAppByChannelVersionCondition(version, condition) {
+    if (!condition) {
+        return true;
+    }
+    return ['eq', 'gt', 'gte', 'lt', 'lte'].every((operator) => {
+        const expected = condition[operator];
+        return expected ? compareAppByChannelWithOperator(version, operator, expected) : true;
+    });
+}
 function matchesVersionCondition(version, condition) {
     if (!condition) {
         return true;
@@ -168,10 +214,7 @@ function resolveAppChannel(version) {
     if (channel === 'beta') {
         return 'beta';
     }
-    if (channel === 'rc') {
-        return 'rc';
-    }
-    return 'unknownPrerelease';
+    return 'stable';
 }
 function evaluateAppByChannelCondition(version, condition) {
     if (!condition) {
@@ -208,7 +251,7 @@ function evaluateAppByChannelCondition(version, condition) {
     const comparableVersion = normalizeAppByChannelComparableVersion(version);
     const comparableCondition = normalizeAppByChannelCondition(channelCondition);
     return {
-        result: matchesVersionCondition(comparableVersion, comparableCondition) ? 'match' : 'mismatch',
+        result: matchesAppByChannelVersionCondition(comparableVersion, comparableCondition) ? 'match' : 'mismatch',
         channel,
         condition: channelCondition,
     };

package/dist/lib/app-managed-resources.js

@@ -6,13 +6,16 @@
  * 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 { mkdir, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { resolveAppPublicPath } from './app-public-path.js';
 import { dockerContainerExists, managedAppLifecycleEnvVars, runLocalNocoBaseCommand, startDockerContainer, } from './app-runtime.js';
 import { deriveBuiltinDbConnection, resolveBuiltinDbConnection } from './builtin-db.js';
 import { resolveConfiguredStoragePath } from './env-paths.js';
 import { resolveDockerEnvFileArg } from "./docker-env-file.js";
 import { DEFAULT_DOCKER_REGISTRY, DEFAULT_DOCKER_VERSION, resolveDockerImageRef, } from "./docker-image.js";
+import { resolveHookScriptPath } from './hook-script.js';
 import { commandSucceeds, ensureDockerDaemonRunning, run } from './run-npm.js';
 import Install from '../commands/install.js';
 const DOCKER_APP_STORAGE_DESTINATION = '/app/nocobase/storage';
@@ -90,6 +93,15 @@ function formatLocalPostinstallFailure(envName, message) {
         `Details: ${message}`,
     ].join('\n');
 }
+function formatNpmSourceDevDependenciesFailure(envName, projectRoot, message) {
+    return [
+        `Couldn't prepare source dev dependencies for "${envName}".`,
+        '`nb source dev` requires @nocobase/devtools in npm source envs.',
+        `Source directory: ${projectRoot}`,
+        `Run \`cd ${projectRoot} && yarn install\` after fixing package.json, then try again.`,
+        `Details: ${message}`,
+    ].join('\n');
+}
 function formatSavedDockerSettingsIncomplete(envName, missing) {
     return [
         `Can't start NocoBase for "${envName}" yet.`,
@@ -114,6 +126,45 @@ async function localProjectHasFiles(projectRoot) {
         return false;
     }
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function readPackageJson(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    const content = await readFile(packageJsonPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    if (!isRecord(parsed)) {
+        throw new Error(`${packageJsonPath} must contain a JSON object.`);
+    }
+    return parsed;
+}
+function getStringDependency(packageJson, section, packageName) {
+    const dependencies = packageJson[section];
+    if (!isRecord(dependencies)) {
+        return undefined;
+    }
+    const version = dependencies[packageName];
+    return typeof version === 'string' && version.trim() ? version.trim() : undefined;
+}
+function ensureDevDependencies(packageJson) {
+    const devDependencies = packageJson.devDependencies;
+    if (devDependencies === undefined) {
+        const next = {};
+        packageJson.devDependencies = next;
+        return next;
+    }
+    if (!isRecord(devDependencies)) {
+        throw new Error('package.json devDependencies must be an object.');
+    }
+    return devDependencies;
+}
+function hasNpmSourceDevtools(projectRoot) {
+    return existsSync(path.join(projectRoot, 'node_modules', '@nocobase', 'devtools', 'package.json'));
+}
+function npmRegistryEnv(runtime) {
+    const npmRegistry = String(runtime.env.config?.npmRegistry ?? '').trim();
+    return npmRegistry ? { npm_config_registry: npmRegistry } : undefined;
+}
 export async function buildSavedDockerRunArgs(runtime, options) {
     const config = runtime.env.config ?? {};
     const storagePath = trimValue(resolveConfiguredStoragePath(config));
@@ -302,6 +353,13 @@ export function buildSavedLocalDownloadArgv(runtime, options) {
     if (config.buildDts === true) {
         argv.push('--build-dts');
     }
+    const hookScriptPath = resolveHookScriptPath({
+        appPath: runtime.env.appPath,
+        hookScript: config.hookScript,
+    });
+    if (hookScriptPath) {
+        argv.push('--hook-script', hookScriptPath, '--hook-phase', options?.hookPhase ?? 'restore', '--hook-command', options?.hookCommand ?? 'app:start', '--hook-env-name', runtime.envName, '--hook-app-path', runtime.env.appPath, '--hook-storage-path', runtime.env.storagePath);
+    }
     return argv;
 }
 export async function ensureSavedLocalSource(runtime, runCommand, options) {
@@ -313,6 +371,8 @@ export async function ensureSavedLocalSource(runtime, runCommand, options) {
     try {
         await runCommand('source:download', buildSavedLocalDownloadArgv(runtime, {
             verbose: options?.verbose,
+            hookPhase: options?.hookPhase,
+            hookCommand: options?.hookCommand,
         }));
         options?.onSucceedTask?.(`NocoBase files are ready for "${runtime.envName}".`);
     }
@@ -335,3 +395,43 @@ export async function ensureLocalPostinstall(runtime, options) {
         throw new Error(formatLocalPostinstallFailure(runtime.envName, error instanceof Error ? error.message : String(error)));
     }
 }
+export async function ensureNpmSourceDevDependencies(runtime, options) {
+    if (runtime.source !== 'npm') {
+        return;
+    }
+    let taskStarted = false;
+    try {
+        const packageJson = await readPackageJson(runtime.projectRoot);
+        const appVersion = getStringDependency(packageJson, 'dependencies', '@nocobase/app');
+        const devtoolsVersion = getStringDependency(packageJson, 'devDependencies', '@nocobase/devtools');
+        let updatedPackageJson = false;
+        if (!devtoolsVersion) {
+            if (!appVersion) {
+                throw new Error('Cannot determine @nocobase/devtools version because dependencies["@nocobase/app"] is missing.');
+            }
+            const devDependencies = ensureDevDependencies(packageJson);
+            devDependencies['@nocobase/devtools'] = appVersion;
+            updatedPackageJson = true;
+            await writeFile(path.join(runtime.projectRoot, 'package.json'), `${JSON.stringify(packageJson, null, 2)}\n`, 'utf-8');
+        }
+        const needsInstall = updatedPackageJson || !hasNpmSourceDevtools(runtime.projectRoot);
+        if (!needsInstall) {
+            return;
+        }
+        options?.onStartTask?.(`Preparing source dev dependencies for "${runtime.envName}"...`);
+        taskStarted = true;
+        await run('yarn', ['install'], {
+            cwd: runtime.projectRoot,
+            env: npmRegistryEnv(runtime),
+            errorName: 'yarn install',
+            stdio: commandStdio(options?.verbose),
+        });
+        options?.onSucceedTask?.(`Source dev dependencies are ready for "${runtime.envName}".`);
+    }
+    catch (error) {
+        if (taskStarted) {
+            options?.onFailTask?.(`Failed to prepare source dev dependencies for "${runtime.envName}".`);
+        }
+        throw new Error(formatNpmSourceDevDependenciesFailure(runtime.envName, runtime.projectRoot, error instanceof Error ? error.message : String(error)));
+    }
+}

package/dist/lib/auth-store.js

@@ -12,6 +12,7 @@ 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 { ENV_CONFIG_SCHEMA_VERSION, normalizeEnvConfigSchemaVersion } from './env-config.js';
 import { cleanupCurrentSessionAfterEnvRemoval, resolveEffectiveCurrentEnv, setSessionCurrentEnv, } from './session-store.js';
 function normalizeStoredEnvKind(value) {
     const kind = String(value ?? '').trim();
@@ -76,11 +77,13 @@ function normalizeEnvConfigEntry(entry) {
     if (!entry) {
         return entry;
     }
-    const { kind: _kind, apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, ...rest } = entry;
+    const { kind: _kind, apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, schemaVersion: _schemaVersion, ...rest } = entry;
     const normalizedKind = resolveEnvKind(entry);
     const apiBaseUrl = readEnvApiBaseUrl(entry);
+    const schemaVersion = normalizeEnvConfigSchemaVersion(entry.schemaVersion);
     return {
         ...rest,
+        ...(schemaVersion ? { schemaVersion } : {}),
         ...(normalizedKind ? { kind: normalizedKind } : {}),
         ...(apiBaseUrl !== undefined ? { apiBaseUrl } : {}),
         ...(normalizeOptionalString(entry.appPublicPath) ? { appPublicPath: resolveAppPublicPath(entry.appPublicPath) } : {}),
@@ -96,6 +99,17 @@ function normalizeAuthConfig(config) {
         ? settings.log.retentionDays
         : undefined;
     const logEnabled = typeof settings.log?.enabled === 'boolean' ? settings.log.enabled : undefined;
+    const hasBinSettings = settings.bin?.docker ||
+        settings.bin?.caddy ||
+        settings.bin?.git ||
+        settings.bin?.nginx ||
+        settings.bin?.pnpm ||
+        settings.bin?.yarn;
+    const hasProxySettings = settings.proxy?.nbCliRoot ||
+        settings.proxy?.caddyDriver ||
+        settings.proxy?.nginxDriver ||
+        settings.proxy?.upstreamHost ||
+        settings.proxy?.host;
     return {
         name: config.name || config.dockerResourcePrefix,
         settings: {
@@ -120,22 +134,19 @@ function normalizeAuthConfig(config) {
                     },
                 }
                 : {}),
-            ...(settings.bin?.docker || settings.bin?.caddy || settings.bin?.git || settings.bin?.nginx || settings.bin?.yarn
+            ...(hasBinSettings
                 ? {
                     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?.pnpm ? { pnpm: normalizeOptionalString(settings.bin.pnpm) } : {}),
                         ...(settings.bin?.yarn ? { yarn: normalizeOptionalString(settings.bin.yarn) } : {}),
                     },
                 }
                 : {}),
-            ...(settings.proxy?.nbCliRoot ||
-                settings.proxy?.caddyDriver ||
-                settings.proxy?.nginxDriver ||
-                settings.proxy?.upstreamHost ||
-                settings.proxy?.host
+            ...(hasProxySettings
                 ? {
                     proxy: {
                         ...(settings.proxy?.nbCliRoot ? { nbCliRoot: normalizeOptionalString(settings.proxy.nbCliRoot) } : {}),
@@ -366,7 +377,13 @@ function areAuthConfigsEquivalent(left, right) {
 async function writeEnv(envName, updater, options = {}) {
     const config = await loadExactAuthConfig(options);
     const previous = config.envs[envName];
-    config.envs[envName] = updater(previous);
+    const next = updater(previous);
+    config.envs[envName] = {
+        ...next,
+        schemaVersion: normalizeEnvConfigSchemaVersion(next.schemaVersion) ??
+            normalizeEnvConfigSchemaVersion(previous?.schemaVersion) ??
+            ENV_CONFIG_SCHEMA_VERSION,
+    };
     await saveAuthConfig(config, options);
 }
 function normalizeConfiguredAuthType(value) {
@@ -377,18 +394,19 @@ export function resolveConfiguredAuthType(config) {
 }
 export async function upsertEnv(envName, config, options = {}) {
     await writeEnv(envName, (previous) => {
-        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, ...rest } = config;
+        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, schemaVersion, ...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 nextAccessToken = normalizeOptionalString(accessToken);
+        const nextAuthType = requestedAuthType ?? (nextAccessToken ? 'token' : previousAuthType);
         const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(authUsername) ?? previous?.authUsername : undefined;
-        const nextAuth = accessToken
+        const nextAuth = nextAccessToken
             ? {
                 type: 'token',
-                accessToken,
+                accessToken: nextAccessToken,
             }
             : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
                 ? previous.auth
@@ -396,6 +414,9 @@ export async function upsertEnv(envName, config, options = {}) {
         const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
         const authTypeChanged = previousAuthType !== nextAuthType;
         const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
+        const nextSchemaVersion = normalizeEnvConfigSchemaVersion(schemaVersion) ??
+            normalizeEnvConfigSchemaVersion(previous?.schemaVersion) ??
+            ENV_CONFIG_SCHEMA_VERSION;
         return {
             ...previous,
             apiBaseUrl: nextApiBaseUrl,
@@ -403,6 +424,7 @@ export async function upsertEnv(envName, config, options = {}) {
             authUsername: nextAuthUsername,
             auth: nextAuth,
             ...rest,
+            schemaVersion: nextSchemaVersion,
             runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
         };
     }, options);

package/dist/lib/cli-config.js

@@ -16,6 +16,7 @@ export const DEFAULT_DOCKER_BIN = 'docker';
 export const DEFAULT_CADDY_BIN = 'caddy';
 export const DEFAULT_GIT_BIN = 'git';
 export const DEFAULT_NGINX_BIN = 'nginx';
+export const DEFAULT_PNPM_BIN = 'pnpm';
 export const PROXY_PROVIDER_OPTIONS = ['nginx', 'caddy'];
 export const DEFAULT_PROXY_PROVIDER = 'nginx';
 export const NGINX_PROXY_DRIVER_OPTIONS = ['local', 'docker'];
@@ -40,6 +41,7 @@ export const SUPPORTED_CLI_CONFIG_KEYS = [
     'bin.caddy',
     'bin.git',
     'bin.nginx',
+    'bin.pnpm',
     'proxy.nb-cli-root',
     'proxy.caddy-driver',
     'proxy.nginx-driver',
@@ -136,6 +138,7 @@ function pruneSettings(config) {
         !trimValue(bin.caddy) &&
         !trimValue(bin.git) &&
         !trimValue(bin.nginx) &&
+        !trimValue(bin.pnpm) &&
         !trimValue(bin.yarn)) {
         delete config.settings?.bin;
     }
@@ -187,6 +190,8 @@ export function getExplicitCliConfigValue(config, key) {
             return trimValue(config.settings?.bin?.git);
         case 'bin.nginx':
             return trimValue(config.settings?.bin?.nginx);
+        case 'bin.pnpm':
+            return trimValue(config.settings?.bin?.pnpm);
         case 'proxy.nb-cli-root':
             return trimValue(config.settings?.proxy?.nbCliRoot);
         case 'proxy.caddy-driver':
@@ -233,6 +238,8 @@ export function getEffectiveCliConfigValue(config, key) {
             return DEFAULT_GIT_BIN;
         case 'bin.nginx':
             return DEFAULT_NGINX_BIN;
+        case 'bin.pnpm':
+            return DEFAULT_PNPM_BIN;
         case 'proxy.nb-cli-root':
             return explicit ?? resolveCliHomeRoot();
         case 'proxy.caddy-driver':
@@ -387,6 +394,12 @@ export async function setCliConfigValue(key, value, options = {}) {
                 nginx: normalized,
             };
             break;
+        case 'bin.pnpm':
+            config.settings.bin = {
+                ...(config.settings.bin ?? {}),
+                pnpm: normalized,
+            };
+            break;
         case 'proxy.nb-cli-root':
             config.settings.proxy = {
                 ...(config.settings.proxy ?? {}),
@@ -496,6 +509,11 @@ export async function deleteCliConfigValue(key, options = {}) {
                 delete config.settings.bin.nginx;
             }
             break;
+        case 'bin.pnpm':
+            if (config.settings.bin) {
+                delete config.settings.bin.pnpm;
+            }
+            break;
         case 'proxy.nb-cli-root':
             if (config.settings.proxy) {
                 delete config.settings.proxy.nbCliRoot;
@@ -556,6 +574,7 @@ const CONFIGURABLE_COMMAND_KEYS = {
     caddy: 'bin.caddy',
     git: 'bin.git',
     nginx: 'bin.nginx',
+    pnpm: 'bin.pnpm',
     yarn: 'bin.yarn',
 };
 export function isConfigurableCommandName(value) {

package/dist/lib/env-config.js

@@ -14,6 +14,7 @@ const STRING_ENV_CONFIG_KEYS = [
     'dockerPlatform',
     'gitUrl',
     'npmRegistry',
+    'hookScript',
     'appPath',
     'appRootPath',
     'storagePath',
@@ -46,6 +47,7 @@ const BOOLEAN_ENV_CONFIG_KEYS = [
     'buildDts',
     'dbUnderscored',
 ];
+export const ENV_CONFIG_SCHEMA_VERSION = 1;
 function trimConfigValue(value) {
     const text = String(value ?? '').trim();
     return text || undefined;
@@ -53,6 +55,9 @@ function trimConfigValue(value) {
 function resolveSetupState(value) {
     return value === 'prepared' || value === 'installed' ? value : undefined;
 }
+export function normalizeEnvConfigSchemaVersion(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
 function resolveEnvKind(input) {
     const source = trimConfigValue(input.source);
     const appPath = trimConfigValue(input.appPath);
@@ -67,6 +72,7 @@ function resolveEnvKind(input) {
 }
 export function buildStoredEnvConfig(input) {
     const envConfig = {
+        schemaVersion: normalizeEnvConfigSchemaVersion(input.schemaVersion) ?? ENV_CONFIG_SCHEMA_VERSION,
         kind: resolveEnvKind(input),
         apiBaseUrl: trimConfigValue(input.apiBaseUrl) ?? '',
     };