@lowdefy/build 6.0.0 → 6.1.0

package/dist/build/buildApi/buildApi.js

@@ -27,7 +27,7 @@ function buildApi({ components, context }) {
         message: 'Duplicate endpointId "{{ id }}".'
     });
     // Validated by validateConfig, which runs before buildApi.
-    const cronEnvironments = components.config?.cron?.environments;
+    const environments = components.config?.environments;
     // Wrap each endpoint build to collect errors instead of stopping on first error
     api.forEach((endpoint, index)=>{
         try {
@@ -36,7 +36,7 @@ function buildApi({ components, context }) {
                 index,
                 context,
                 checkDuplicateEndpointId,
-                cronEnvironments
+                environments
             });
         } catch (error) {
             // Skip suppressed ConfigErrors (via ~ignoreBuildChecks)

package/dist/build/buildApi/buildEndpoint.js

@@ -16,17 +16,17 @@
 import resolveEndpointSchedules from './resolveEndpointSchedules.js';
 import validateEndpoint from './validateEndpoint.js';
 import validateStepReferences from './validateStepReferences.js';
-function buildEndpoint({ endpoint, index, context, checkDuplicateEndpointId, cronEnvironments }) {
+function buildEndpoint({ endpoint, index, context, checkDuplicateEndpointId, environments }) {
     validateEndpoint({
         endpoint,
         index,
         checkDuplicateEndpointId,
-        cronEnvironments
+        environments
     });
     endpoint.endpointId = endpoint.id;
     resolveEndpointSchedules({
         endpoint,
-        cronEnvironments
+        environments
     });
     buildRoutine(endpoint.routine, {
         endpointId: endpoint.endpointId,

package/dist/build/buildApi/resolveEndpointSchedules.js

@@ -13,24 +13,27 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { type } from '@lowdefy/helpers';
-import getCronEnvironmentNames from '../../utils/getCronEnvironmentNames.js';
-// With config.cron.environments declared, the artifact carries `schedules` as an object with one
+import getEnvironmentNames from '../../utils/getEnvironmentNames.js';
+// With config.environments declared, the artifact carries `schedules` as an object with one
 // explicit list per declared environment: the environment's own entry when the author keyed the
 // schedules by environment, else the `default` entry, else nothing (`[]` turns the crons off). An
-// array applies as-is to every environment. The runtime and the schedules manifest then read
-// `schedules.<environment>` without repeating the inheritance. Without config.cron the endpoint
-// keeps its array.
-function resolveEndpointSchedules({ endpoint, cronEnvironments }) {
-    const names = getCronEnvironmentNames(cronEnvironments);
+// array applies as-is to every environment. `default` is kept too, for a build with no current
+// environment. The runtime and the schedules manifest then read `schedules.<environment>` without
+// repeating the inheritance. Without config.environments the endpoint keeps its array.
+function resolveEndpointSchedules({ endpoint, environments }) {
+    const names = getEnvironmentNames(environments);
     if (names.length === 0 || type.isUndefined(endpoint.schedules)) return;
     const authored = endpoint.schedules;
-    const resolved = {};
+    const inherited = type.isArray(authored) ? authored : authored.default ?? [];
+    const resolved = {
+        default: inherited
+    };
     names.forEach((name)=>{
         if (type.isArray(authored)) {
             resolved[name] = authored;
             return;
         }
-        resolved[name] = authored[name] ?? authored.default ?? [];
+        resolved[name] = authored[name] ?? inherited;
     });
     endpoint.schedules = resolved;
 }

package/dist/build/buildApi/validateEndpoint.js

@@ -16,7 +16,7 @@
 import { ConfigError } from '@lowdefy/errors';
 import validateId from '../../utils/validateId.js';
 import validateCronExpression from '../../utils/validateCronExpression.js';
-import getCronEnvironmentNames from '../../utils/getCronEnvironmentNames.js';
+import getEnvironmentNames from '../../utils/getEnvironmentNames.js';
 // `where` names the schedules list in messages: "" for the endpoint's own schedules, or
 // ` for environment "staging"` for an override.
 function validateSchedules({ schedules, endpoint, configKey, where = '' }) {
@@ -66,18 +66,18 @@ function validateSchedules({ schedules, endpoint, configKey, where = '' }) {
     });
 }
 // The object form of `schedules`: lists keyed by environment name plus an optional `default` the
-// other environments inherit. Every key must be declared in config.cron.environments, so a typo
+// other environments inherit. Every key must be declared in config.environments, so a typo
 // cannot silently leave an environment on the defaults.
-function validateEnvironmentSchedules({ endpoint, configKey, cronEnvironments }) {
-    const declared = getCronEnvironmentNames(cronEnvironments);
+function validateEnvironmentSchedules({ endpoint, configKey, environments }) {
+    const declared = getEnvironmentNames(environments);
     if (declared.length === 0) {
-        throw new ConfigError(`Endpoint "${endpoint.id}" keys schedules by environment but lowdefy.config.cron.environments is not defined.`, {
+        throw new ConfigError(`Endpoint "${endpoint.id}" keys schedules by environment but config.environments is not defined.`, {
             configKey
         });
     }
-    getCronEnvironmentNames(endpoint.schedules).forEach((name)=>{
+    getEnvironmentNames(endpoint.schedules).forEach((name)=>{
         if (name !== 'default' && !declared.includes(name)) {
-            throw new ConfigError(`Endpoint schedules environment "${name}" at "${endpoint.id}" is not declared in lowdefy.config.cron.environments. Declared environments: ${declared.join(', ')}.`, {
+            throw new ConfigError(`Endpoint schedules environment "${name}" at "${endpoint.id}" is not declared in config.environments. Declared environments: ${declared.join(', ')}.`, {
                 configKey
             });
         }
@@ -97,7 +97,7 @@ function validateEnvironmentSchedules({ endpoint, configKey, cronEnvironments })
         });
     });
 }
-function validateEndpoint({ endpoint, index, checkDuplicateEndpointId, cronEnvironments }) {
+function validateEndpoint({ endpoint, index, checkDuplicateEndpointId, environments }) {
     const configKey = endpoint['~k'];
     if (type.isUndefined(endpoint.id)) {
         throw new ConfigError(`Endpoint id missing at endpoint ${index}.`, {
@@ -144,7 +144,7 @@ function validateEndpoint({ endpoint, index, checkDuplicateEndpointId, cronEnvir
         validateEnvironmentSchedules({
             endpoint,
             configKey,
-            cronEnvironments
+            environments
         });
     } else {
         validateSchedules({

package/dist/build/buildAppMeta.js

@@ -13,6 +13,7 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { execSync } from 'child_process';
+import { randomUUID } from 'crypto';
 import { ConfigError } from '@lowdefy/errors';
 import { type } from '@lowdefy/helpers';
 import { evaluateOperators } from '@lowdefy/operators';
@@ -123,7 +124,14 @@ async function buildAppMeta({ context }) {
             field: 'lowdefy',
             value: content.lowdefy
         }),
-        gitSha: computeGitSha()
+        gitSha: computeGitSha(),
+        // Identity of this build, unique per run. The client bundle and the server
+        // both read it from appMeta.json, so an open tab can tell after a deploy
+        // that the page config it just fetched came from a newer build than the
+        // bundle it is running, and reload instead of failing on missing _js
+        // functions. gitSha is not enough: it is null on most deploy platforms and
+        // the same commit can be rebuilt with different config.
+        buildId: randomUUID()
     };
     return context.appMeta;
 }

package/dist/build/buildEnvironments.js

@@ -0,0 +1,261 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+import { ConfigError, ConfigWarning } from '@lowdefy/errors';
+import checkEnvironmentGuards from '@lowdefy/node-utils/checkEnvironmentGuards.js';
+import getEnvironmentNames from '../utils/getEnvironmentNames.js';
+import validateEnvironmentGuards from './validateEnvironmentGuards.js';
+// Environment names become a path segment (/api/cron-forward/<environment>/<endpointId>).
+const environmentNamePattern = /^[A-Za-z0-9\-_]+$/;
+// Features an environment can switch off with `<feature>.enabled: false`. Logging has no switch.
+const switchableFeatures = [
+    'cron',
+    'email',
+    'sentry'
+];
+function isAbsoluteHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    } catch  {
+        return false;
+    }
+}
+function validateEmailFilter({ name, filter, configKey }) {
+    const where = `config.environments.${name}.email.filter`;
+    if (!type.isObject(filter)) {
+        throw new ConfigError(`App "${where}" should be an object.`, {
+            received: filter,
+            configKey
+        });
+    }
+    const { replaceAddress, allowlist, regex } = filter;
+    if (!type.isNone(replaceAddress) && (!type.isString(replaceAddress) || replaceAddress === '')) {
+        throw new ConfigError(`App "${where}.replaceAddress" should be a non-empty string.`, {
+            received: replaceAddress,
+            configKey
+        });
+    }
+    if (!type.isNone(allowlist) && (!type.isArray(allowlist) || !allowlist.every((domain)=>type.isString(domain)))) {
+        throw new ConfigError(`App "${where}.allowlist" should be an array of strings.`, {
+            received: allowlist,
+            configKey
+        });
+    }
+    if (!type.isNone(regex)) {
+        if (!type.isString(regex)) {
+            throw new ConfigError(`App "${where}.regex" should be a string.`, {
+                received: regex,
+                configKey
+            });
+        }
+        // Compiled here so a broken pattern fails the build, not every mail request in the environment.
+        try {
+            new RegExp(regex);
+        } catch (error) {
+            throw new ConfigError(`App "${where}.regex" is not a valid regular expression: ${error.message}`, {
+                configKey
+            });
+        }
+    }
+}
+function validateEnvironment({ name, environment, configKey }) {
+    if (name === 'default') {
+        throw new ConfigError('Environment name "default" is reserved: it names the value every other environment inherits.', {
+            configKey
+        });
+    }
+    if (!environmentNamePattern.test(name)) {
+        throw new ConfigError(`Environment name "${name}" is invalid. Environment names must only contain A-Z, a-z, 0-9, "-" and "_".`, {
+            configKey
+        });
+    }
+    if (!type.isObject(environment)) {
+        throw new ConfigError(`App "config.environments.${name}" should be an object.`, {
+            received: environment,
+            configKey
+        });
+    }
+    const key = environment['~k'] ?? configKey;
+    const { url, cron, email, sentry } = environment;
+    if (!type.isUndefined(url) && (!type.isString(url) || !isAbsoluteHttpUrl(url))) {
+        throw new ConfigError(`App "config.environments.${name}.url" should be an absolute http(s) URL, e.g. "https://staging.example.com".`, {
+            received: url,
+            configKey: key
+        });
+    }
+    if (!type.isUndefined(cron)) {
+        if (!type.isObject(cron)) {
+            throw new ConfigError(`App "config.environments.${name}.cron" should be an object.`, {
+                received: cron,
+                configKey: key
+            });
+        }
+        if (!type.isUndefined(cron.secret)) {
+            if (!type.isString(cron.secret) || cron.secret === '') {
+                throw new ConfigError(`App "config.environments.${name}.cron.secret" should be the name of the Lowdefy secret holding the environment's CRON_SECRET.`, {
+                    received: cron.secret,
+                    configKey: cron['~k'] ?? key
+                });
+            }
+            if (type.isUndefined(url)) {
+                throw new ConfigError(`Environment "${name}" has a cron.secret but no url. Crons are forwarded to an environment's url, so set the environment's deployment origin.`, {
+                    configKey: key
+                });
+            }
+        }
+    }
+    if (!type.isUndefined(sentry) && !type.isObject(sentry)) {
+        throw new ConfigError(`App "config.environments.${name}.sentry" should be an object.`, {
+            received: sentry,
+            configKey: key
+        });
+    }
+    switchableFeatures.forEach((feature)=>{
+        const enabled = environment[feature]?.enabled;
+        if (!type.isUndefined(enabled) && !type.isBoolean(enabled)) {
+            throw new ConfigError(`App "config.environments.${name}.${feature}.enabled" should be a boolean.`, {
+                received: enabled,
+                configKey: environment[feature]['~k'] ?? key
+            });
+        }
+    });
+    validateEnvironmentGuards({
+        name,
+        guards: environment.guards,
+        configKey: key
+    });
+    if (!type.isUndefined(email)) {
+        if (!type.isObject(email)) {
+            throw new ConfigError(`App "config.environments.${name}.email" should be an object.`, {
+                received: email,
+                configKey: key
+            });
+        }
+        if (!type.isUndefined(email.filter)) {
+            validateEmailFilter({
+                name,
+                filter: email.filter,
+                configKey: email['~k'] ?? key
+            });
+        }
+    }
+}
+// LOWDEFY_ENVIRONMENT wins over config.environment: the variable is set per deployment, while a
+// literal in config is shared by every deployment and would force them all into one environment.
+function getCurrentEnvironmentName({ config }) {
+    if (!type.isNone(config.environment)) {
+        if (!type.isString(config.environment) || config.environment === '') {
+            throw new ConfigError('App "config.environment" should be a non-empty string.', {
+                received: config.environment,
+                configKey: config['~k']
+            });
+        }
+    }
+    const fromEnv = process.env.LOWDEFY_ENVIRONMENT?.trim();
+    if (!type.isNone(fromEnv) && fromEnv !== '') return fromEnv;
+    return config.environment ?? undefined;
+}
+// Resolves the deployment environments once for the whole build. After this step:
+//   - config.environments holds every declared environment ({ url, cron, email }), validated;
+//   - config.environment names the environment this build is for (the LOWDEFY_ENVIRONMENT
+//     variable, else config.environment), and must be declared when environments are.
+// Everything environment-specific (cron registration and forwarding, notification links, the auth
+// base URL, the email delivery filter, the Sentry environment) reads the current environment from
+// there instead of from its own environment variable. buildLogger, which runs next, applies the
+// Sentry settings.
+function buildEnvironments({ components, context }) {
+    const config = components.config;
+    const configKey = config['~k'];
+    const current = getCurrentEnvironmentName({
+        config
+    });
+    // config.cron.environments (6.0) is replaced by config.environments. Fail with the migration
+    // rather than run two shapes side by side.
+    if (!type.isUndefined(config.cron)) {
+        throw new ConfigError('App "config.cron" is replaced by "config.environments". Declare the deployment environments under "config.environments": give every environment its "url", move each "secret" to "cron.secret" and "enabled" to "cron.enabled", and set LOWDEFY_ENVIRONMENT on each deployment.', {
+            configKey: config.cron?.['~k'] ?? configKey
+        });
+    }
+    const environments = config.environments;
+    if (!type.isUndefined(environments)) {
+        if (!type.isObject(environments)) {
+            throw new ConfigError('App "config.environments" should be an object.', {
+                received: environments,
+                configKey
+            });
+        }
+        const envKey = environments['~k'] ?? configKey;
+        const names = getEnvironmentNames(environments);
+        if (names.length === 0) {
+            throw new ConfigError('App "config.environments" declares no environments.', {
+                configKey: envKey
+            });
+        }
+        names.forEach((name)=>validateEnvironment({
+                name,
+                environment: environments[name],
+                configKey: envKey
+            }));
+        if (!type.isUndefined(current) && !names.includes(current)) {
+            throw new ConfigError(`The current environment "${current}" (LOWDEFY_ENVIRONMENT) is not declared in "config.environments". Declared environments: ${names.join(', ')}.`, {
+                configKey: envKey
+            });
+        }
+        // Without a current environment every environment setting fails open: no email filter, no
+        // forwarded crons, no guards. That is an error in a prod build, and a warning on the dev server.
+        if (type.isUndefined(current)) {
+            context.handleWarning(new ConfigWarning(`App "config.environments" is declared but no current environment is set. Set LOWDEFY_ENVIRONMENT to the environment this deployment is (${names.join(', ')}): until then no environment setting (url, cron, email filter, guards) applies and only the "default" schedules are registered.`, {
+                configKey: envKey,
+                prodError: true
+            }));
+        }
+    }
+    // The current environment's guards are checked against this build's variables and kept for the
+    // production server, which checks them again at startup; other environments' guards are dropped.
+    if (!type.isUndefined(environments)) {
+        if (!type.isUndefined(current)) {
+            checkEnvironmentGuards({
+                name: current,
+                guards: environments[current].guards,
+                configKey: environments[current]['~k'] ?? configKey
+            });
+        }
+        getEnvironmentNames(environments).filter((name)=>name !== current).forEach((name)=>{
+            delete environments[name].guards;
+        });
+    }
+    if (type.isUndefined(current)) {
+        delete config.environment;
+        return;
+    }
+    config.environment = current;
+    const settings = config.environments?.[current] ?? {};
+    // The dev server is the local app, not the deployment the environment's url names, so the url is
+    // dropped: auth and notification links stay on the request origin even when a local .env names a
+    // deployed environment.
+    if (context.stage === 'dev') {
+        delete settings.url;
+    }
+    const disabled = switchableFeatures.filter((feature)=>settings[feature]?.enabled === false);
+    // App metadata is the deploy identity the server stamps on every log line and the client reads
+    // with _app, so the environment and the features it switches off travel with it — the browser
+    // has no other view of config.environments.
+    if (type.isObject(components.appMeta)) {
+        components.appMeta.environment = current;
+        components.appMeta.disabled = disabled;
+    }
+}
+export default buildEnvironments;

package/dist/build/buildLogger.js

@@ -25,17 +25,33 @@ const sentryDefaults = {
         '_id'
     ]
 };
+// Runs after validateConfig, so config.environment and config.environments are resolved.
 function buildLogger({ components }) {
     if (type.isNone(components.logger)) {
         components.logger = {};
     }
-    // Only apply defaults if sentry is explicitly configured
-    if (!type.isNone(components.logger.sentry)) {
-        components.logger.sentry = {
-            ...sentryDefaults,
-            ...components.logger.sentry
-        };
+    const current = components.config.environment;
+    // Sentry is enabled by SENTRY_DSN, not by the config being present, so a current environment
+    // creates the Sentry config to carry its name. Without either, the runtime defaults apply.
+    if (type.isNone(components.logger.sentry) && type.isNone(current)) {
+        return components;
     }
+    const sentry = {
+        ...sentryDefaults,
+        ...components.logger.sentry ?? {}
+    };
+    if (!type.isNone(current)) {
+        // Sentry reports under the environment name unless the app names one itself, and is off on
+        // both sides when the environment switches it off.
+        if (type.isNone(sentry.environment)) {
+            sentry.environment = current;
+        }
+        if (components.config.environments?.[current]?.sentry?.enabled === false) {
+            sentry.client = false;
+            sentry.server = false;
+        }
+    }
+    components.logger.sentry = sentry;
     return components;
 }
 export default buildLogger;

package/dist/build/jit/shallowBuild.js

@@ -157,11 +157,12 @@ async function shallowBuild(options) {
         // appMeta is computed in Phase 0; attach it here (where buildApp used to
         // create it) so the following addKeys pass keys it identically.
         components.appMeta = context.appMeta;
-        tryBuildStep(buildLogger, 'buildLogger', {
+        // validateConfig resolves the current environment, which buildLogger reads for Sentry.
+        tryBuildStep(validateConfig, 'validateConfig', {
             components,
             context
         });
-        tryBuildStep(validateConfig, 'validateConfig', {
+        tryBuildStep(buildLogger, 'buildLogger', {
             components,
             context
         });

package/dist/build/validateConfig.js

@@ -13,8 +13,8 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { type } from '@lowdefy/helpers';
-import validateCronConfig from './validateCronConfig.js';
-function validateConfig({ components }) {
+import buildEnvironments from './buildEnvironments.js';
+function validateConfig({ components, context }) {
     if (type.isNone(components.config)) {
         components.config = {};
     }
@@ -26,8 +26,9 @@ function validateConfig({ components }) {
             throw new Error('Base path must start with "/".');
         }
     }
-    validateCronConfig({
-        components
+    buildEnvironments({
+        components,
+        context
     });
     return components;
 }

package/dist/build/validateEnvironmentGuards.js

@@ -0,0 +1,69 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+import collectEnvironmentGuards from '@lowdefy/node-utils/collectEnvironmentGuards.js';
+const guardKinds = [
+    'secrets',
+    'env'
+];
+// Guard shape and patterns are validated for every environment, not only the current one, so a
+// broken guard fails the build that introduces it.
+function validateEnvironmentGuards({ name, guards, configKey }) {
+    if (type.isUndefined(guards)) return;
+    const where = `config.environments.${name}.guards`;
+    if (!type.isObject(guards)) {
+        throw new ConfigError(`App "${where}" should be an object.`, {
+            received: guards,
+            configKey
+        });
+    }
+    // An unknown key (a `secret:` typo for `secrets:`) would otherwise check nothing and let the
+    // value it was meant to pin through, so it fails the build.
+    Object.keys(guards).forEach((kind)=>{
+        if (kind.startsWith('~') || guardKinds.includes(kind)) return;
+        throw new ConfigError(`App "${where}.${kind}" is not a guard kind. Guards are "secrets" (Lowdefy secret names) and "env" (environment variable names).`, {
+            configKey
+        });
+    });
+    guardKinds.forEach((kind)=>{
+        const map = guards[kind];
+        if (type.isUndefined(map)) return;
+        if (!type.isObject(map)) {
+            throw new ConfigError(`App "${where}.${kind}" should be an object.`, {
+                received: map,
+                configKey
+            });
+        }
+    });
+    collectEnvironmentGuards({
+        guards
+    }).forEach(({ label, pattern })=>{
+        if (!type.isString(pattern) || pattern === '') {
+            throw new ConfigError(`App "${where}" ${label} should be a regular expression string.`, {
+                received: pattern,
+                configKey
+            });
+        }
+        try {
+            new RegExp(pattern);
+        } catch (error) {
+            throw new ConfigError(`App "${where}" ${label} is not a valid regular expression: ${error.message}`, {
+                configKey
+            });
+        }
+    });
+}
+export default validateEnvironmentGuards;