@lowdefy/node-utils 5.6.0 → 6.1.0

package/dist/checkEnvironmentGuards.js

@@ -0,0 +1,34 @@
+/*
+  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 './collectEnvironmentGuards.js';
+// Checks the current environment's guards against this process's environment variables. The build
+// runs it before anything deploys, and the production server again at startup: an image built once
+// can be started with different variables. Values are never echoed: a failure names the variable,
+// not what it holds.
+function checkEnvironmentGuards({ name, guards, configKey }) {
+    const failures = collectEnvironmentGuards({
+        guards
+    }).filter(({ variable, pattern })=>{
+        const value = process.env[variable];
+        return !type.isString(value) || !new RegExp(pattern).test(value);
+    });
+    if (failures.length === 0) return;
+    throw new ConfigError(`Environment "${name}" guards failed: ${failures.map(({ label, variable })=>type.isString(process.env[variable]) ? `${label} does not match its guard` : `${label} is not set (${variable})`).join('; ')}. Update the guard in config.environments.${name}.guards together with the value, or fix the value.`, {
+        configKey
+    });
+}
+export default checkEnvironmentGuards;

package/dist/collectEnvironmentGuards.js

@@ -0,0 +1,45 @@
+/*
+  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.
+*/ // Guards pin an environment's secrets and environment variables to a pattern kept in code: the
+// value must match the regular expression, so changing a guarded value (the prod database URI,
+// say) takes a change to the deployment's variables AND a reviewed change to the app config — a
+// second factor for deploy-time configuration. Checked at build, before anything deploys.
+//
+//   guards:
+//     secrets: { MONGODB_URI: 'acme-prod\.a1b2c\.mongodb\.net' }   # LOWDEFY_SECRET_<NAME>
+//     env: { BETTER_AUTH_URL: '^https://app\.acme\.com$' }
+//
+// Values are never echoed: a failure names the variable, not what it holds.
+function collectEnvironmentGuards({ guards }) {
+    const checks = [];
+    Object.entries(guards?.secrets ?? {}).forEach(([name, pattern])=>{
+        if (name.startsWith('~')) return;
+        checks.push({
+            label: `secret "${name}"`,
+            variable: `LOWDEFY_SECRET_${name}`,
+            pattern
+        });
+    });
+    Object.entries(guards?.env ?? {}).forEach(([name, pattern])=>{
+        if (name.startsWith('~')) return;
+        checks.push({
+            label: `environment variable "${name}"`,
+            variable: name,
+            pattern
+        });
+    });
+    return checks;
+}
+export default collectEnvironmentGuards;

package/dist/createSecretScrubber.js

@@ -0,0 +1,114 @@
+/*
+  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';
+const REDACTED = '[REDACTED]';
+// Shorter values, like `true` or a port number, would shred unrelated text.
+const MIN_SECRET_LENGTH = 8;
+function collectStringLeaves(value, leaves) {
+    if (type.isString(value)) {
+        leaves.push(value);
+        return leaves;
+    }
+    if (type.isArray(value)) {
+        value.forEach((item)=>collectStringLeaves(item, leaves));
+        return leaves;
+    }
+    if (type.isObject(value)) {
+        Object.values(value).forEach((item)=>collectStringLeaves(item, leaves));
+    }
+    return leaves;
+}
+// Authors JSON-encode structured secrets and pick a leaf with `_json.parse`, so the leaf, not
+// the whole encoded string, is what ends up in an error message.
+function parseJsonLeaves(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    } catch  {
+        return [];
+    }
+    if (!type.isObject(parsed) && !type.isArray(parsed)) {
+        return [];
+    }
+    return collectStringLeaves(parsed, []);
+}
+// A secret embedded in a larger base64 payload (a Basic auth header built from
+// `user:password`) only matches the secret's own base64 when both start on the same 3-byte
+// boundary. Encoding at each offset and keeping only the characters whose 6 bits fall wholly
+// inside the secret's bytes gives a fragment that matches whatever surrounds it.
+function base64Fragments(value) {
+    const bytes = Buffer.from(value, 'utf8');
+    const fragments = [];
+    [
+        0,
+        1,
+        2
+    ].forEach((offset)=>{
+        const padded = Buffer.concat([
+            Buffer.alloc(offset),
+            bytes
+        ]);
+        const start = Math.ceil(8 * offset / 6);
+        const end = Math.floor(8 * (offset + bytes.length) / 6);
+        [
+            'base64',
+            'base64url'
+        ].forEach((encoding)=>{
+            fragments.push(padded.toString(encoding).replace(/=+$/, '').slice(start, end));
+        });
+    });
+    return fragments;
+}
+function secretForms(value) {
+    return [
+        value,
+        encodeURIComponent(value),
+        JSON.stringify(value).slice(1, -1),
+        ...base64Fragments(value)
+    ];
+}
+function createSecretScrubber({ secrets, env = process.env }) {
+    const values = collectStringLeaves(secrets, []);
+    if (!type.isNone(env.CRON_SECRET)) values.push(env.CRON_SECRET);
+    if (!type.isNone(env.AUTH_SECRET)) values.push(env.AUTH_SECRET);
+    const expanded = values.flatMap((value)=>[
+            value,
+            ...parseJsonLeaves(value)
+        ]);
+    const secretValues = new Set(expanded.filter((value)=>value.length >= MIN_SECRET_LENGTH));
+    const forms = new Set();
+    secretValues.forEach((value)=>{
+        secretForms(value).forEach((form)=>{
+            if (form.length > 0) forms.add(form);
+        });
+    });
+    // No secrets means no pattern: an empty alternation would match at every position.
+    if (forms.size === 0) {
+        return function scrub(value) {
+            return value;
+        };
+    }
+    // One alternation, so every log line and Sentry string takes a single pass however many
+    // secrets there are. Longest first, so a form is replaced whole before a shorter form it
+    // contains can match at the same position.
+    const pattern = new RegExp([
+        ...forms
+    ].sort((a, b)=>b.length - a.length).map((form)=>form.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
+    return function scrub(value) {
+        if (!type.isString(value)) return value;
+        return value.replace(pattern, REDACTED);
+    };
+}
+export default createSecretScrubber;

package/dist/findAvailablePort.js

@@ -0,0 +1,27 @@
+/*
+  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 isPortAvailable from './isPortAvailable.js';
+async function findAvailablePort({ port, maxAttempts = 100 }) {
+    const startPort = Number(port);
+    for(let candidate = startPort; candidate < startPort + maxAttempts; candidate += 1){
+        if (await isPortAvailable({
+            port: candidate
+        })) {
+            return candidate;
+        }
+    }
+    throw new Error(`[Server Error] No available port found in range ${startPort}-${startPort + maxAttempts - 1}.`);
+}
+export default findAvailablePort;

package/dist/index.js

@@ -12,11 +12,18 @@
   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 cleanDirectory from './cleanDirectory.js';
+*/ import checkEnvironmentGuards from './checkEnvironmentGuards.js';
+import cleanDirectory from './cleanDirectory.js';
+import collectEnvironmentGuards from './collectEnvironmentGuards.js';
 import copyFileOrDirectory from './copyFileOrDirectory.js';
+import createSecretScrubber from './createSecretScrubber.js';
+import findAvailablePort from './findAvailablePort.js';
 import getFileExtension, { getFileSubExtension } from './getFileExtension.js';
 import getSecretsFromEnv from './getSecretsFromEnv.js';
+import installIfPackageJsonChanged from './installIfPackageJsonChanged.js';
+import isPortAvailable from './isPortAvailable.js';
 import spawnProcess from './spawnProcess.js';
 import readFile from './readFile.js';
 import writeFile from './writeFile.js';
-export { cleanDirectory, copyFileOrDirectory, getFileExtension, getFileSubExtension, getSecretsFromEnv, spawnProcess, readFile, writeFile };
+import writeFileIfChanged from './writeFileIfChanged.js';
+export { checkEnvironmentGuards, cleanDirectory, collectEnvironmentGuards, copyFileOrDirectory, createSecretScrubber, findAvailablePort, getFileExtension, getFileSubExtension, getSecretsFromEnv, installIfPackageJsonChanged, isPortAvailable, spawnProcess, readFile, writeFile, writeFileIfChanged };

package/dist/installIfPackageJsonChanged.js

@@ -0,0 +1,43 @@
+/*
+  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 crypto from 'crypto';
+import path from 'path';
+import { type } from '@lowdefy/helpers';
+import readFile from './readFile.js';
+import writeFile from './writeFile.js';
+async function installIfPackageJsonChanged({ directory, install }) {
+    if (!type.isString(directory)) {
+        throw new Error(`installIfPackageJsonChanged requires a directory string. Received ${JSON.stringify(directory)}.`);
+    }
+    if (!type.isFunction(install)) {
+        throw new Error('installIfPackageJsonChanged requires an install function.');
+    }
+    const packageJsonContent = await readFile(path.join(directory, 'package.json'));
+    if (packageJsonContent === null) {
+        throw new Error(`Could not read package.json in ${directory}.`);
+    }
+    const hash = crypto.createHash('sha1').update(packageJsonContent).digest('base64');
+    // Stored inside node_modules so deleting node_modules also clears the hash,
+    // forcing the next run to install.
+    const hashPath = path.join(directory, 'node_modules', '.lowdefy-install-hash');
+    const previousHash = await readFile(hashPath);
+    if (previousHash === hash) {
+        return false;
+    }
+    await install();
+    await writeFile(hashPath, hash);
+    return true;
+}
+export default installIfPackageJsonChanged;

package/dist/isPortAvailable.js

@@ -0,0 +1,62 @@
+/*
+  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 net from 'net';
+// libuv sets SO_REUSEADDR on listening sockets, so on macOS a wildcard bind
+// succeeds while another process holds a specific loopback address (and vice
+// versa) — only an exact address match fails with EADDRINUSE. A single
+// anonymous bind therefore reports ports busy on 127.0.0.1 (how Vite binds
+// `localhost`) as available. Probe the wildcard and both loopback addresses
+// so each common binding pattern is detected by its exact match.
+const HOSTS = [
+    undefined,
+    '127.0.0.1',
+    '::1'
+];
+function checkHost({ port, host }) {
+    return new Promise((resolve, reject)=>{
+        const server = net.createServer();
+        server.on('error', (error)=>{
+            if (error.code === 'EADDRINUSE') {
+                resolve(false);
+                return;
+            }
+            // Host has no IPv6 loopback — nothing can occupy that address.
+            if ([
+                'EADDRNOTAVAIL',
+                'EAFNOSUPPORT',
+                'EINVAL'
+            ].includes(error.code)) {
+                resolve(true);
+                return;
+            }
+            reject(error);
+        });
+        server.listen(port, host, ()=>{
+            server.close(()=>resolve(true));
+        });
+    });
+}
+async function isPortAvailable({ port }) {
+    for (const host of HOSTS){
+        if (!await checkHost({
+            port,
+            host
+        })) {
+            return false;
+        }
+    }
+    return true;
+}
+export default isPortAvailable;

package/dist/writeFileIfChanged.js

@@ -0,0 +1,27 @@
+/*
+  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 readFile from './readFile.js';
+import writeFile from './writeFile.js';
+// Skipping byte-identical writes keeps file mtimes stable so watchers (Vite
+// module graph, chokidar) do not react to rebuilds that changed nothing.
+async function writeFileIfChanged(filePath, content) {
+    const existing = await readFile(filePath);
+    if (existing === content) {
+        return false;
+    }
+    await writeFile(filePath, content);
+    return true;
+}
+export default writeFileIfChanged;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/node-utils",
-  "version": "5.6.0",
+  "version": "6.1.0",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -34,13 +34,13 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/errors": "5.6.0",
-    "@lowdefy/helpers": "5.6.0",
-    "fs-extra": "11.1.1"
+    "@lowdefy/errors": "6.1.0",
+    "@lowdefy/helpers": "6.1.0",
+    "fs-extra": "11.3.4"
   },
   "devDependencies": {
-    "@swc/cli": "0.8.0",
-    "@swc/core": "1.15.18",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.32",
     "@swc/jest": "0.2.39",
     "copyfiles": "2.4.1",
     "jest": "28.1.3"