@nocobase/app-server 0.11.1-alpha.5 → 2.0.0-beta.1

package/dist/config/placeholder-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder-secret.js","sourceRoot":"","sources":["../../src/config/placeholder-secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;AAEjE,MAAM,UAAU,mBAAmB,CAAC,KAAyB;IAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,kBAAkB,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,KAAyB,EACzB,GAAW;IAEX,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO;IACT,CAAC;IAED,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,gJAAgJ,CACvJ,CAAC;AACJ,CAAC"}

package/dist/config/runtime-environment.d.ts

@@ -0,0 +1,11 @@
+export interface RuntimeEnvironmentVariable {
+    readonly name: string;
+    readonly description: string;
+}
+/**
+ * Environment variables the runtime reads itself rather than through a section's `env`. With the sections'
+ * declarations they are everything an application can be configured with from its environment, which is what
+ * `pnpm nocobase config env` lists and what `.env.example` may name.
+ */
+export declare const RUNTIME_ENVIRONMENT_VARIABLES: readonly RuntimeEnvironmentVariable[];
+//# sourceMappingURL=runtime-environment.d.ts.map

package/dist/config/runtime-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-environment.d.ts","sourceRoot":"","sources":["../../src/config/runtime-environment.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,0BAA0B,EAgB5E,CAAC"}

package/dist/config/runtime-environment.js

@@ -0,0 +1,20 @@
+/**
+ * Environment variables the runtime reads itself rather than through a section's `env`. With the sections'
+ * declarations they are everything an application can be configured with from its environment, which is what
+ * `pnpm nocobase config env` lists and what `.env.example` may name.
+ */
+export const RUNTIME_ENVIRONMENT_VARIABLES = [
+    {
+        name: 'APP_BASE_PATH',
+        description: 'The path the application is served under; its name follows from it.',
+    },
+    {
+        name: 'APP_CONFIG_FILE',
+        description: 'The configuration file to read instead of config.yml in the deployment root.',
+    },
+    {
+        name: 'NOCOBASE_STRICT_STARTUP',
+        description: 'Set to true to exit the process as soon as startup fails.',
+    },
+];
+//# sourceMappingURL=runtime-environment.js.map

package/dist/config/runtime-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-environment.js","sourceRoot":"","sources":["../../src/config/runtime-environment.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GACxC;IACE;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,qEAAqE;KACxE;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,8EAA8E;KACjF;IACD;QACE,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EAAE,2DAA2D;KACzE;CACF,CAAC"}

package/dist/config/types.d.ts

@@ -0,0 +1,12 @@
+export type EnvMap = Record<string, string | undefined>;
+export type { AppPaths } from './paths.js';
+import type { AppPaths } from './paths.js';
+export interface ConfigContext {
+    readonly environment: EnvMap;
+    readonly paths: AppPaths;
+}
+export interface CreateConfigContextOptions {
+    readonly env: EnvMap;
+    readonly paths: AppPaths;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAExD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B"}

package/dist/config/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":""}

package/dist/config/validation.d.ts

@@ -0,0 +1,36 @@
+import type { ConfigMap } from '@nocobase/config';
+import type { AppConfigRules } from './define-app-config.js';
+export interface ConfigIssue {
+    readonly level: 'error' | 'warning';
+    /** The full path, such as `auth.emailAndPassword.disableSignUp`. */
+    readonly path: string;
+    readonly message: string;
+    readonly fix?: string;
+}
+/**
+ * The configuration breaks a rule its sections declare.
+ *
+ * Carries every issue found, warnings included, so a caller can report all of them at once rather than one per start.
+ * Recognised by `name` as well as by class, so a second copy of this package in the process is still recognised.
+ */
+export declare class AppConfigInvalidError extends Error {
+    readonly issues: readonly ConfigIssue[];
+    constructor(issues: readonly ConfigIssue[]);
+}
+/** Whether `error`, or anything in its cause chain, is an {@link AppConfigInvalidError}. */
+export declare function findAppConfigInvalid(error: unknown): AppConfigInvalidError | undefined;
+export declare function formatConfigIssues(issues: readonly ConfigIssue[]): string;
+/**
+ * Runs every section's validators against the merged configuration, and checks each section's public paths.
+ *
+ * Issues are collected rather than thrown, so one run reports everything that is wrong.
+ */
+export declare function validateConfigSections(current: ConfigMap, overrides: ConfigMap, sections: ReadonlyMap<string, AppConfigRules>): Promise<ConfigIssue[]>;
+/**
+ * The values sections publish, nested under their section name. A path with no value is left out, so the browser
+ * sees `undefined` and falls back to its own default.
+ */
+export declare function collectPublicConfig(current: ConfigMap, sections: ReadonlyMap<string, AppConfigRules>): ConfigMap;
+/** Every published path, in full, such as `auth.emailAndPassword.disableSignUp`. */
+export declare function listPublicPaths(sections: ReadonlyMap<string, AppConfigRules>): string[];
+//# sourceMappingURL=validation.d.ts.map

package/dist/config/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;gBAE5B,MAAM,EAAE,SAAS,WAAW,EAAE;CAKlD;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,qBAAqB,GAAG,SAAS,CAWnC;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAOzE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,SAAS,EAClB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,GAC5C,OAAO,CAAC,WAAW,EAAE,CAAC,CAmBxB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,GAC5C,SAAS,CAYX;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,GAC5C,MAAM,EAAE,CAIV"}

package/dist/config/validation.js

@@ -0,0 +1,186 @@
+/**
+ * The configuration breaks a rule its sections declare.
+ *
+ * Carries every issue found, warnings included, so a caller can report all of them at once rather than one per start.
+ * Recognised by `name` as well as by class, so a second copy of this package in the process is still recognised.
+ */
+export class AppConfigInvalidError extends Error {
+    issues;
+    constructor(issues) {
+        super(formatConfigIssues(issues));
+        this.name = 'AppConfigInvalidError';
+        this.issues = issues;
+    }
+}
+/** Whether `error`, or anything in its cause chain, is an {@link AppConfigInvalidError}. */
+export function findAppConfigInvalid(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+        if (current instanceof AppConfigInvalidError ||
+            current.name === 'AppConfigInvalidError')
+            return current;
+        current = current.cause;
+    }
+    return undefined;
+}
+export function formatConfigIssues(issues) {
+    const errors = issues.filter((issue) => issue.level === 'error');
+    const lines = errors.map((issue) => `  ✖ ${issue.path}  ${issue.message}${issue.fix ? `\n      ${issue.fix}` : ''}`);
+    return ['Application configuration is invalid:', ...lines].join('\n');
+}
+/**
+ * Runs every section's validators against the merged configuration, and checks each section's public paths.
+ *
+ * Issues are collected rather than thrown, so one run reports everything that is wrong.
+ */
+export async function validateConfigSections(current, overrides, sections) {
+    const issues = [];
+    for (const [section, rules] of sections) {
+        issues.push(...publicPathIssues(current, section, rules.public));
+        const value = readPath(current, [section]);
+        const context = createValidationContext(section, overrides, issues);
+        for (const validator of rules.validators) {
+            try {
+                await validator(value ?? {}, context);
+            }
+            catch (error) {
+                issues.push({
+                    level: 'error',
+                    path: section,
+                    message: `validation failed: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * The values sections publish, nested under their section name. A path with no value is left out, so the browser
+ * sees `undefined` and falls back to its own default.
+ */
+export function collectPublicConfig(current, sections) {
+    const output = {};
+    for (const [section, rules] of sections) {
+        for (const relative of rules.public) {
+            if (!relative || !isValidPublicPath(relative))
+                continue;
+            const segments = [section, ...splitPath(relative)];
+            const value = readPath(current, segments);
+            if (value === undefined || !isPublishableLeaf(value))
+                continue;
+            writePath(output, segments, value);
+        }
+    }
+    return output;
+}
+/** Every published path, in full, such as `auth.emailAndPassword.disableSignUp`. */
+export function listPublicPaths(sections) {
+    return [...sections].flatMap(([section, rules]) => rules.public.map((relative) => `${section}.${relative}`));
+}
+function createValidationContext(section, overrides, issues) {
+    const push = (level, path, message, options = {}) => {
+        issues.push({
+            level,
+            path: path ? `${section}.${path}` : section,
+            message,
+            ...(options.fix ? { fix: options.fix } : {}),
+        });
+    };
+    return {
+        error: (path, message, options) => push('error', path, message, options),
+        warning: (path, message, options) => push('warning', path, message, options),
+        isUserProvided: (path) => readPath(overrides, [section, ...splitPath(path)]) !== undefined,
+    };
+}
+function publicPathIssues(current, section, paths) {
+    const issues = [];
+    for (const relative of paths) {
+        const full = relative ? `${section}.${relative}` : section;
+        if (!relative) {
+            issues.push({
+                level: 'error',
+                path: section,
+                message: 'cannot be published as a whole: name each field to expose instead.',
+            });
+            continue;
+        }
+        if (!isValidPublicPath(relative)) {
+            issues.push({
+                level: 'error',
+                path: full,
+                message: 'is not a valid public path.',
+            });
+            continue;
+        }
+        const value = readPath(current, [section, ...splitPath(relative)]);
+        if (value === undefined)
+            continue;
+        if (typeof value === 'function' || !isPublishableLeaf(value)) {
+            issues.push({
+                level: 'error',
+                path: full,
+                message: isPlainObject(value)
+                    ? 'cannot be published: name each field to expose instead of the whole object.'
+                    : 'cannot be published: only plain values can reach the browser.',
+            });
+        }
+    }
+    return issues;
+}
+function isPublishableLeaf(value) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value))) {
+        return true;
+    }
+    return (Array.isArray(value) &&
+        value.every((item) => item === null ||
+            typeof item === 'string' ||
+            typeof item === 'boolean' ||
+            (typeof item === 'number' && Number.isFinite(item))));
+}
+function isPlainObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype ||
+            Object.getPrototypeOf(value) === null));
+}
+const FORBIDDEN_SEGMENTS = new Set([
+    '__proto__',
+    'prototype',
+    'constructor',
+]);
+function splitPath(path) {
+    return path ? path.split('.') : [];
+}
+function isValidPublicPath(path) {
+    return splitPath(path).every((segment) => segment !== '' && !FORBIDDEN_SEGMENTS.has(segment));
+}
+function readPath(root, segments) {
+    let value = root;
+    for (const segment of segments) {
+        if (!isPlainObject(value) || !Object.hasOwn(value, segment)) {
+            return undefined;
+        }
+        value = value[segment];
+    }
+    return value;
+}
+function writePath(root, segments, value) {
+    let target = root;
+    for (const segment of segments.slice(0, -1)) {
+        const existing = target[segment];
+        if (isPlainObject(existing)) {
+            target = existing;
+        }
+        else {
+            const child = {};
+            target[segment] = child;
+            target = child;
+        }
+    }
+    target[segments[segments.length - 1]] = value;
+}
+//# sourceMappingURL=validation.js.map

package/dist/config/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"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"}

package/dist/config/variables.d.ts

@@ -0,0 +1,57 @@
+import type { ConfigMap } from '@nocobase/config';
+import { type EnvironmentMapping, type EnvironmentValueGenerator } from '@nocobase/config/providers/env';
+/**
+ * Values the templates' `config.example.yml` ship that only stand in for a real one. A path holding one of them in the
+ * example counts as having no value there, so a deployment is still asked for it. The application itself is not told:
+ * an example copied by hand keeps working exactly as before.
+ */
+export declare const KNOWN_EXAMPLE_PLACEHOLDERS: readonly string[];
+/** One variable in the manifest. `runtime` marks one the runtime reads itself rather than through a section. */
+export interface VariablesManifestEntry {
+    readonly name: string;
+    readonly path?: string;
+    readonly type: string;
+    readonly description?: string;
+    readonly secret: boolean;
+    readonly required: boolean;
+    /** The code defaults hold a value at the path. */
+    readonly hasDefault: boolean;
+    /** `config.example.yml` holds a value at the path that is not a known placeholder. */
+    readonly exampleProvided: boolean;
+    readonly firstStartOnly: boolean;
+    readonly generate: EnvironmentValueGenerator | null;
+    readonly runtime?: true;
+}
+/** `dist/variables.json`: every environment variable an application reads, as a deployment needs to know them. */
+export interface VariablesManifest {
+    readonly schemaVersion: 1;
+    readonly app: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    readonly generatedAt: string;
+    readonly variables: readonly VariablesManifestEntry[];
+}
+export interface BuildVariablesManifestOptions {
+    readonly app: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    /** What `AppConfig.environmentVariableMappings()` returns: absolute paths. */
+    readonly variables: Readonly<Record<string, EnvironmentMapping>>;
+    /** The code defaults, `AppConfig.layers().defaults`. */
+    readonly defaults: ConfigMap;
+    /** `config.example.yml`, parsed; left out when the application ships none. */
+    readonly example?: ConfigMap;
+    readonly generatedAt?: Date;
+}
+/** Whether a value, or any string inside it, is one of {@link KNOWN_EXAMPLE_PLACEHOLDERS}. */
+export declare function isExamplePlaceholder(value: unknown): boolean;
+/**
+ * Whether a deployment must supply a variable: the mapping says so, or else nothing else would give the path a value —
+ * no code default, no real value in `config.example.yml`, and no way for the deployment to generate one.
+ */
+export declare function requiredOf(mapping: EnvironmentMapping, defaults: ConfigMap, example: ConfigMap | undefined): boolean;
+/** Builds the manifest `pnpm nocobase config variables` prints and `pnpm build` writes to `dist/variables.json`. */
+export declare function buildVariablesManifest(options: BuildVariablesManifestOptions): VariablesManifest;
+//# sourceMappingURL=variables.d.ts.map

package/dist/config/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../src/config/variables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC;AAKxC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAGvD,CAAC;AAEF,gHAAgH;AAChH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;CACzB;AAED,kHAAkH;AAClH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACjE,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;CAC7B;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,SAAS,GAAG,SAAS,GAC7B,OAAO,CAOT;AAED,oHAAoH;AACpH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,iBAAiB,CAqCnB"}

package/dist/config/variables.js

@@ -0,0 +1,89 @@
+import { isSecretPath, } from '@nocobase/config/providers/env';
+import { PLACEHOLDER_SECRET } from './placeholder-secret.js';
+import { RUNTIME_ENVIRONMENT_VARIABLES } from './runtime-environment.js';
+/**
+ * Values the templates' `config.example.yml` ship that only stand in for a real one. A path holding one of them in the
+ * example counts as having no value there, so a deployment is still asked for it. The application itself is not told:
+ * an example copied by hand keeps working exactly as before.
+ */
+export const KNOWN_EXAMPLE_PLACEHOLDERS = [
+    PLACEHOLDER_SECRET,
+    'admin123',
+];
+/** Whether a value, or any string inside it, is one of {@link KNOWN_EXAMPLE_PLACEHOLDERS}. */
+export function isExamplePlaceholder(value) {
+    if (typeof value === 'string')
+        return KNOWN_EXAMPLE_PLACEHOLDERS.includes(value.trim());
+    if (Array.isArray(value))
+        return value.some(isExamplePlaceholder);
+    if (typeof value === 'object' && value !== null)
+        return Object.values(value).some(isExamplePlaceholder);
+    return false;
+}
+/**
+ * Whether a deployment must supply a variable: the mapping says so, or else nothing else would give the path a value —
+ * no code default, no real value in `config.example.yml`, and no way for the deployment to generate one.
+ */
+export function requiredOf(mapping, defaults, example) {
+    if (mapping.required !== undefined)
+        return mapping.required;
+    return (!hasValue(defaults, mapping.path) &&
+        !hasRealValue(example, mapping.path) &&
+        mapping.generate === undefined);
+}
+/** Builds the manifest `pnpm nocobase config variables` prints and `pnpm build` writes to `dist/variables.json`. */
+export function buildVariablesManifest(options) {
+    const declared = Object.entries(options.variables)
+        .map(([name, mapping]) => ({
+        name,
+        path: mapping.path,
+        type: mapping.type ?? 'string',
+        ...(mapping.description === undefined
+            ? {}
+            : { description: mapping.description }),
+        secret: mapping.secret ?? isSecretPath(mapping.path),
+        required: requiredOf(mapping, options.defaults, options.example),
+        hasDefault: hasValue(options.defaults, mapping.path),
+        exampleProvided: hasRealValue(options.example, mapping.path),
+        firstStartOnly: mapping.firstStartOnly ?? false,
+        generate: mapping.generate ?? null,
+    }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+    const runtime = RUNTIME_ENVIRONMENT_VARIABLES.map((variable) => ({
+        name: variable.name,
+        type: 'string',
+        description: variable.description,
+        secret: false,
+        required: false,
+        hasDefault: false,
+        exampleProvided: false,
+        firstStartOnly: false,
+        generate: null,
+        runtime: true,
+    }));
+    return {
+        schemaVersion: 1,
+        app: options.app,
+        generatedAt: (options.generatedAt ?? new Date()).toISOString(),
+        variables: [...declared, ...runtime],
+    };
+}
+function valueAt(map, path) {
+    let value = map;
+    for (const segment of path.split('.')) {
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        value = value[segment];
+    }
+    return value;
+}
+function hasValue(map, path) {
+    const value = valueAt(map, path);
+    if (Array.isArray(value))
+        return value.length > 0;
+    return value !== undefined && value !== null && value !== '';
+}
+function hasRealValue(map, path) {
+    return hasValue(map, path) && !isExamplePlaceholder(valueAt(map, path));
+}
+//# sourceMappingURL=variables.js.map

package/dist/config/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../src/config/variables.ts"],"names":[],"mappings":"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"}

package/dist/database/collections-artifact.d.ts

@@ -0,0 +1,99 @@
+import { type DatabaseDriverRegistration, type DatabaseManager } from '@nocobase/db';
+import type { AppPaths } from '../config/index.js';
+import type { AppDatabaseTasksResult } from './tasks.js';
+import type { AppDatabaseConfig } from './types.js';
+/**
+ * Reads every Collection a connection resolves and writes it under
+ * `database/<connection>/collections/<name>/` as three files, plus a
+ * connection-level manifest. The directory is a cache for every connection,
+ * external ones included: nothing here is read back at runtime, the generator
+ * may rewrite or delete any of it, and migrations — or, for an external
+ * connection, the database it points at and its hand-written
+ * `database/<connection>/metadata/` — remain the authority.
+ */
+export interface AppCollectionsArtifactOptions {
+    readonly paths?: AppPaths;
+    readonly drivers?: Record<string, DatabaseDriverRegistration>;
+    /** One connection; defaults to the default connection. Exclusive with `all`. */
+    readonly connection?: string;
+    /** Every configured connection, external ones included. */
+    readonly all?: boolean;
+    /** Compare the generated result with the files on disk and write nothing. */
+    readonly check?: boolean;
+    /** Reuse an open manager instead of creating and destroying one. */
+    readonly database?: DatabaseManager;
+}
+export type AppCollectionsArtifactDifferenceKind = 'missing' | 'stale' | 'unexpected';
+/** One file that differs between the database and the directory; `path` is relative to the collections directory. */
+export interface AppCollectionsArtifactDifference {
+    path: string;
+    kind: AppCollectionsArtifactDifferenceKind;
+}
+export interface AppCollectionsArtifactManifestSummary {
+    dialect: string;
+    /** An `external` connection has no migration history, so `migrationHead` is always `null` there. */
+    schemaManagement: 'managed' | 'external';
+    migrationHead: string | null;
+    collections: string[];
+}
+export interface AppCollectionsArtifactConnectionResult {
+    connection: string;
+    /** Absolute path of `database/<connection>/collections`. */
+    directory: string;
+    status: 'completed' | 'stale' | 'failed';
+    manifest?: AppCollectionsArtifactManifestSummary;
+    /** Files created or rewritten, relative to `directory`. Empty in check mode. */
+    written?: string[];
+    /** Files removed because their Collection no longer exists. Empty in check mode. */
+    deleted?: string[];
+    /** Collections whose three files already matched. */
+    unchanged?: number;
+    /** Check mode only. */
+    differences?: AppCollectionsArtifactDifference[];
+    /**
+     * Check mode only. False when `directory` does not exist: nothing has been
+     * generated for this connection yet, which a reader has to tell apart from
+     * artifacts that have drifted, because every expected file is then reported
+     * `missing` and the two look alike.
+     */
+    directoryExists?: boolean;
+    /**
+     * Hand-written metadata documents, in this connection's metadata directory,
+     * that name a Collection the database does not have. Reported for a person
+     * to fix or remove; the generator never touches that directory.
+     */
+    unusedMetadata?: string[];
+    error?: string;
+}
+export interface AppCollectionsArtifactResult {
+    ok: boolean;
+    status: 'completed' | 'stale' | 'failed' | 'not-configured';
+    check: boolean;
+    results: AppCollectionsArtifactConnectionResult[];
+}
+export declare function generateAppCollectionsArtifact(config: AppDatabaseConfig, options?: AppCollectionsArtifactOptions): Promise<AppCollectionsArtifactResult>;
+/** How one connection's Collection cache refresh went, after the migrations that made it stale. */
+export interface AppCollectionsRefreshResult {
+    connection: string;
+    status: 'completed' | 'failed';
+    written?: string[];
+    deleted?: string[];
+    error?: string;
+}
+export interface RefreshAppCollectionsArtifactOptions {
+    readonly paths?: AppPaths;
+    /** The manager the migrations ran on, so the cache reads the state they left behind. */
+    readonly database: DatabaseManager;
+}
+/**
+ * Regenerates the Collection cache of every connection whose schema a
+ * database run changed: migrations executed, rolled back, or rebuilt from
+ * empty. Seeds write rows, never structure, and a preview changes nothing, so
+ * neither triggers a refresh. Returns `undefined` when nothing changed.
+ *
+ * A failure is reported in the result, never raised: the migrations it
+ * follows are already committed, and the cache can always be rebuilt with
+ * `collections generate`.
+ */
+export declare function refreshAppCollectionsArtifact(config: AppDatabaseConfig, result: AppDatabaseTasksResult, options: RefreshAppCollectionsArtifactOptions): Promise<AppCollectionsRefreshResult[] | undefined>;
+//# sourceMappingURL=collections-artifact.d.ts.map

package/dist/database/collections-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections-artifact.d.ts","sourceRoot":"","sources":["../../src/database/collections-artifact.ts"],"names":[],"mappings":"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"}