@entrinsik/vite-plugin-informer 2.3.0 → 2.5.0-beta.0

package/src/deploy.js

@@ -1,6 +1,7 @@
 import { createClient } from './client.js';
-import { readdir, readFile, stat, access } from 'node:fs/promises';
-import { join, relative, posix, basename, dirname } from 'node:path';
+import { collectAppFiles } from './assemble.js';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
 
 const TEXT_EXTENSIONS = new Set([
     '.html', '.css', '.js', '.mjs', '.json', '.svg',
@@ -10,9 +11,6 @@ const TEXT_EXTENSIONS = new Set([
 // Files above this size use chunked upload via Flow.js protocol
 const CHUNK_THRESHOLD = 512 * 1024; // 512KB
 
-// Config files to upload from project root (if they exist)
-const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
-
 /**
  * Deploy a built Vite project to Informer as an App.
  *
@@ -102,159 +100,40 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         limit: 10
     });
 
-    // 5. Clear existing files
+    // 5. Clear existing files in one server-side transaction
     console.log('Clearing existing files...');
-    const files = await api.get(`${entityPath}/files?start=0&end=10000`);
-    if (files && Array.isArray(files)) {
-        // Delete non-directories first
-        const nonDirs = files.filter(f => !f.directory);
-        await Promise.all(nonDirs.map(f => api.del(`${entityPath}/files/${f.id}`)));
-
-        // Then delete directories in reverse order (deepest first by path length)
-        const dirs = files
-            .filter(f => f.directory)
-            .sort((a, b) => (b.path || '').length - (a.path || '').length);
-        for (const d of dirs) {
-            await api.del(`${entityPath}/files/${d.id}`);
-        }
-    }
+    await api.post(`${entityPath}/files/_clear`);
 
-    // 6. Upload dist/ contents
-    console.log(`Uploading files from ${distDir}...`);
-    const entries = await walkDir(distDir);
+    // 6. Upload the app-library file set: dist output at the library root, plus
+    //    informer.yaml / data-access.yaml and the server/tools/migrations/webhooks
+    //    source trees. Sourced from the shared collectAppFiles() so a deploy and a
+    //    marketplace publish package byte-identical contents.
+    console.log('Uploading files...');
+    const files = await collectAppFiles({ distDir, projectRoot: dirname(distDir) });
 
-    for (const filePath of entries) {
-        const relPath = posix.normalize(relative(distDir, filePath).split('\\').join('/'));
-        const content = await readFile(filePath);
+    for (const { abs, rel } of files) {
+        const content = await readFile(abs);
 
         if (content.length > CHUNK_THRESHOLD) {
             // Large file: chunked upload via Flow.js protocol
             await api.uploadChunked({
                 entityPath,
-                path: relPath,
+                path: rel,
                 buffer: content,
-                filename: basename(filePath)
+                filename: basename(abs)
             });
-            console.log(`  ${relPath} (${formatSize(content.length)}, chunked)`);
+            console.log(`  ${rel} (${formatSize(content.length)}, chunked)`);
         } else {
             // Small file: direct JSON upload
-            const ext = '.' + relPath.split('.').pop();
-            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
-            const payload = isText
-                ? { content: content.toString('utf8'), encoding: 'utf8' }
-                : { content: content.toString('base64'), encoding: 'base64' };
-
-            await api.put(`${entityPath}/contents/${relPath}`, payload);
-            console.log(`  ${relPath}`);
-        }
-    }
-
-    // 7. Upload config files from project root (informer.yaml, data-access.yaml)
-    const projectRoot = dirname(distDir);
-    let configCount = 0;
-    for (const configFile of ROOT_CONFIG_FILES) {
-        const configPath = join(projectRoot, configFile);
-        try {
-            await access(configPath);
-            const content = await readFile(configPath, 'utf8');
-            await api.put(`${entityPath}/contents/${configFile}`, {
-                content,
-                encoding: 'utf8'
-            });
-            console.log(`  ${configFile} (from project root)`);
-            configCount++;
-        } catch {
-            // File doesn't exist, skip
-        }
-    }
-
-    // 8. Upload migrations/ directory from project root (if it exists)
-    const migrationsDir = join(projectRoot, 'migrations');
-    let migrationsCount = 0;
-    try {
-        await access(migrationsDir);
-        const migrationFiles = await walkDir(migrationsDir);
-        for (const filePath of migrationFiles) {
-            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
-            const content = await readFile(filePath, 'utf8');
-            await api.put(`${entityPath}/contents/${relPath}`, {
-                content,
-                encoding: 'utf8'
-            });
-            console.log(`  ${relPath} (from project root)`);
-            migrationsCount++;
-        }
-    } catch {
-        // No migrations directory, skip
-    }
-
-    // 9. Upload tools/ directory from project root (if it exists)
-    const toolsDir = join(projectRoot, 'tools');
-    let toolsCount = 0;
-    try {
-        await access(toolsDir);
-        const toolFiles = await walkDir(toolsDir);
-        for (const filePath of toolFiles) {
-            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
-            const content = await readFile(filePath);
-            const ext = '.' + relPath.split('.').pop();
-            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
-            const payload = isText
-                ? { content: content.toString('utf8'), encoding: 'utf8' }
-                : { content: content.toString('base64'), encoding: 'base64' };
-
-            await api.put(`${entityPath}/contents/${relPath}`, payload);
-            console.log(`  ${relPath} (from project root)`);
-            toolsCount++;
-        }
-    } catch {
-        // No tools directory, skip
-    }
-
-    // 10. Upload server/ directory from project root (if it exists)
-    const serverDir = join(projectRoot, 'server');
-    let serverCount = 0;
-    try {
-        await access(serverDir);
-        const serverFiles = await walkDir(serverDir);
-        for (const filePath of serverFiles) {
-            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
-            const content = await readFile(filePath);
-            const ext = '.' + relPath.split('.').pop();
-            const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
-            const payload = isText
-                ? { content: content.toString('utf8'), encoding: 'utf8' }
-                : { content: content.toString('base64'), encoding: 'base64' };
-
-            await api.put(`${entityPath}/contents/${relPath}`, payload);
-            console.log(`  ${relPath} (from project root)`);
-            serverCount++;
-        }
-    } catch {
-        // No server directory, skip
-    }
-
-    // 11. Upload webhooks/ directory from project root (if it exists)
-    const webhooksDir = join(projectRoot, 'webhooks');
-    let webhooksCount = 0;
-    try {
-        await access(webhooksDir);
-        const webhookFiles = await walkDir(webhooksDir);
-        for (const filePath of webhookFiles) {
-            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
-            const content = await readFile(filePath);
-            const ext = '.' + relPath.split('.').pop();
+            const ext = '.' + rel.split('.').pop();
             const isText = TEXT_EXTENSIONS.has(ext.toLowerCase());
             const payload = isText
                 ? { content: content.toString('utf8'), encoding: 'utf8' }
                 : { content: content.toString('base64'), encoding: 'base64' };
 
-            await api.put(`${entityPath}/contents/${relPath}`, payload);
-            console.log(`  ${relPath} (from project root)`);
-            webhooksCount++;
+            await api.put(`${entityPath}/contents/${rel}`, payload);
+            console.log(`  ${rel}`);
         }
-    } catch {
-        // No webhooks directory, skip
     }
 
     // 12. Deploy: run migrations + scan/bundle server routes + webhooks + tools + agents
@@ -296,7 +175,7 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     }
 
     // 13. Print URL and return UUID for saving
-    const totalFiles = entries.length + configCount + migrationsCount + toolsCount + serverCount + webhooksCount;
+    const totalFiles = files.length;
     const base = baseUrl.replace(/\/+$/, '');
     const entityUrl = apiPrefix === 'apps'
         ? `${base}/api/apps/${naturalId}/view`
@@ -306,24 +185,6 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     return { id: entity.id, url: entityUrl };
 }
 
-/**
- * Recursively walk a directory, returning file paths (not directories).
- */
-async function walkDir(dir) {
-    const results = [];
-    const items = await readdir(dir);
-    for (const item of items) {
-        const full = join(dir, item);
-        const s = await stat(full);
-        if (s.isDirectory()) {
-            results.push(...await walkDir(full));
-        } else {
-            results.push(full);
-        }
-    }
-    return results;
-}
-
 function formatSize(bytes) {
     if (bytes < 1024) return `${bytes} B`;
     if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;

package/src/dev-dependencies.js

@@ -0,0 +1,363 @@
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import crypto from 'node:crypto';
+import yaml from 'yaml';
+
+const parseYaml = yaml.parse;
+
+const RANDOM_BYTES_MAX = 1024;
+
+/**
+ * Build the dev-mode `crypto` helper. Mirrors the production host dispatcher in
+ * app-sandbox.js (cryptoRef) so handlers/tools see the same crypto surface
+ * locally. Methods are synchronous in dev (prod returns promises across the
+ * isolate boundary); `await` works either way.
+ *
+ * @returns {Object} crypto helper { hmac, hash, randomUUID, randomBytes, timingSafeEqual, verifyHmac, encrypt, decrypt, verify }
+ */
+export function buildDevCrypto() {
+    return {
+        hmac: (algorithm, key, data, encoding) => crypto.createHmac(algorithm, key).update(data).digest(encoding || 'hex'),
+        hash: (algorithm, data, encoding) => crypto.createHash(algorithm).update(data).digest(encoding || 'hex'),
+        randomUUID: () => crypto.randomUUID(),
+        randomBytes: (length, encoding) => {
+            const n = Math.min(Math.max(parseInt(length, 10) || 0, 1), RANDOM_BYTES_MAX);
+            return crypto.randomBytes(n).toString(encoding || 'hex');
+        },
+        timingSafeEqual: (a, b) => {
+            if (a == null || b == null) {
+                throw new Error('crypto.timingSafeEqual requires two non-null values to compare');
+            }
+            const ba = Buffer.from(String(a));
+            const bb = Buffer.from(String(b));
+            if (ba.length !== bb.length) return false;
+            return crypto.timingSafeEqual(ba, bb);
+        },
+        verifyHmac: (algorithm, key, data, signature, encoding) => {
+            if (signature == null) {
+                throw new Error('crypto.verifyHmac requires a signature to compare against (got null/undefined)');
+            }
+            const expected = crypto.createHmac(algorithm, key).update(data).digest(encoding || 'hex');
+            const a = Buffer.from(String(signature));
+            const b = Buffer.from(expected);
+            if (a.length !== b.length) return false;
+            return crypto.timingSafeEqual(a, b);
+        },
+        encrypt: (plaintext, key) => {
+            const dk = crypto.createHash('sha256').update(String(key)).digest();
+            const iv = crypto.randomBytes(12);
+            const cipher = crypto.createCipheriv('aes-256-gcm', dk, iv);
+            const ct = Buffer.concat([cipher.update(String(plaintext), 'utf8'), cipher.final()]);
+            const tag = cipher.getAuthTag();
+            return `${iv.toString('base64')}:${tag.toString('base64')}:${ct.toString('base64')}`;
+        },
+        decrypt: (payload, key) => {
+            const parts = String(payload).split(':');
+            if (parts.length !== 3) {
+                throw new Error('crypto.decrypt: malformed payload (expected iv:tag:ciphertext)');
+            }
+            const dk = crypto.createHash('sha256').update(String(key)).digest();
+            const iv = Buffer.from(parts[0], 'base64');
+            const tag = Buffer.from(parts[1], 'base64');
+            const ct = Buffer.from(parts[2], 'base64');
+            const decipher = crypto.createDecipheriv('aes-256-gcm', dk, iv);
+            decipher.setAuthTag(tag);
+            return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+        },
+        verify: (algorithm, data, signature, publicKey, signatureEncoding) => {
+            if (data == null || signature == null || publicKey == null) {
+                throw new Error('crypto.verify requires data, signature, and publicKey');
+            }
+            return crypto.verify(algorithm, Buffer.from(String(data)), publicKey, Buffer.from(String(signature), signatureEncoding || 'base64'));
+        }
+    };
+}
+
+/**
+ * Canonicalize a guest-code fetch() path the same way the prod sandbox does
+ * (see normalizeFetchPath in app-sandbox.js). Returns the normalized `/api/...`
+ * path, or null for any non-canonical input — so dev rejects the same shapes
+ * prod 400s instead of silently accepting `//api/foo` / `\api\foo`.
+ *
+ * @param {string} urlPath
+ * @returns {string|null}
+ */
+export function normalizeFetchPath(urlPath) {
+    if (typeof urlPath !== 'string' || !urlPath) return null;
+    // eslint-disable-next-line no-control-regex
+    if (/[\\\x00-\x1f\s]/.test(urlPath)) return null;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(urlPath)) return null;
+    let p = urlPath;
+    if (p.startsWith('/')) p = p.slice(1);
+    if (p.startsWith('api/')) p = p.slice('api/'.length);
+    if (!p || p.startsWith('/') || p.startsWith('api/')) return null;
+    if (p.includes('//')) return null;
+    return `/api/${p}`;
+}
+
+/**
+ * Build dev-mode notify/email shims that mirror the PROD required-field
+ * validation (app-message-utils.js) so an app that passes locally also passes in
+ * production. Delivery is still a console-logged no-op in dev.
+ *
+ * @param {string} logPrefix - console log prefix (e.g. '[app]' or '[agent-dev]')
+ * @returns {{ notify: Function, email: Function }}
+ */
+export function buildDevMessaging(logPrefix = '[app]') {
+    const notify = (usernameOrArray, message) => {
+        if (Array.isArray(usernameOrArray)) {
+            for (const item of usernameOrArray) {
+                if (!item || typeof item.username !== 'string') throw new Error('notify() bulk items require a username');
+                if (!item.title) throw new Error('notify() bulk items require a title');
+            }
+            console.log(`${logPrefix} notify (bulk)`, JSON.stringify(usernameOrArray));
+            return { ids: usernameOrArray.map(() => 'dev-message'), queued: usernameOrArray.length };
+        }
+        if (!usernameOrArray || typeof usernameOrArray !== 'string') {
+            throw new Error('notify() requires a username as the first argument');
+        }
+        if (!message || !message.title) {
+            throw new Error('notify() requires a message with at least a title');
+        }
+        console.log(`${logPrefix} notify`, usernameOrArray, JSON.stringify(message));
+        return { id: 'dev-message' };
+    };
+
+    const email = (toOrArray, message) => {
+        if (Array.isArray(toOrArray)) {
+            for (const item of toOrArray) {
+                if (!item || typeof item.to !== 'string') throw new Error('email() bulk items require a to address');
+                if (!item.subject) throw new Error('email() bulk items require a subject');
+            }
+            console.log(`${logPrefix} email (bulk)`, JSON.stringify(toOrArray));
+            return { ids: toOrArray.map(() => 'dev-message'), queued: toOrArray.length };
+        }
+        if (!toOrArray || typeof toOrArray !== 'string') {
+            throw new Error('email() requires an email address as the first argument');
+        }
+        if (!message || !message.subject) {
+            throw new Error('email() requires a message with at least a subject');
+        }
+        console.log(`${logPrefix} email`, toOrArray, JSON.stringify(message));
+        return { id: 'dev-message' };
+    };
+
+    return { notify, email };
+}
+
+// Mirrors the server-side patterns in
+// packages/informer-server/modules/app/routes/deploy.js so dev and deploy
+// reject the same shapes with the same wording. Keep these in lockstep.
+const DEPENDENCY_NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VALID_TARGETS = new Set(['dataset', 'query', 'datasource', 'integration']);
+const VALID_RUN_AS = new Set(['user', 'owner']);
+
+const METHOD_SURFACE = {
+    dataset: ['search', 'fields'],
+    query: ['execute'],
+    datasource: ['query'],
+    integration: ['request']
+};
+
+/**
+ * Load the `dependencies:` map from informer.yaml. Returns `{}` if the file
+ * is missing or the section is absent — both are valid (an app may have no
+ * declared dependencies).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Object>} The raw dependencies object as authored
+ */
+export async function loadDependencies(projectRoot) {
+    const yamlPath = join(projectRoot, 'informer.yaml');
+    try {
+        await access(yamlPath);
+    } catch {
+        return {};
+    }
+    const content = await readFile(yamlPath, 'utf8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') return {};
+    return (parsed.dependencies && typeof parsed.dependencies === 'object') ? parsed.dependencies : {};
+}
+
+/**
+ * Load the app `env:` map from informer.yaml. In production the sandbox injects
+ * `app.defn.env`; dev has no app model, so the YAML's top-level `env:` block is
+ * the closest stand-in. Returns `{}` when missing so handlers/tools see the same
+ * empty object rather than undefined.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Object>} The raw env object as authored
+ */
+export async function loadAppEnv(projectRoot) {
+    const yamlPath = join(projectRoot, 'informer.yaml');
+    try {
+        await access(yamlPath);
+    } catch {
+        return {};
+    }
+    const content = await readFile(yamlPath, 'utf8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') return {};
+    return (parsed.env && typeof parsed.env === 'object') ? parsed.env : {};
+}
+
+/**
+ * Validate the shape of a parsed `dependencies:` block. Returns an array of
+ * human-readable error strings (empty when valid). Wording mirrors deploy.js
+ * so devs see the same message at boot and at deploy.
+ *
+ * Skips "is the resource actually readable?" — that requires a network call
+ * against the configured server and would slow startup. Shape validation is
+ * the cheap win; the deploy path still does the read check.
+ *
+ * @param {Object} deps - The raw `dependencies:` object
+ * @returns {string[]} Error messages, one per problem
+ */
+export function validateDependencies(deps) {
+    const errors = [];
+    for (const [name, decl] of Object.entries(deps || {})) {
+        if (!DEPENDENCY_NAME_PATTERN.test(name)) {
+            errors.push(`dependency "${name}": invalid name (must be lowercase dot-segmented, eg. "orders.list")`);
+            continue;
+        }
+        if (!decl || typeof decl !== 'object') {
+            errors.push(`dependency "${name}": must be an object`);
+            continue;
+        }
+        if (!decl.target || typeof decl.target !== 'string') {
+            errors.push(`dependency "${name}": missing required "target" field`);
+            continue;
+        }
+        if (!VALID_TARGETS.has(decl.target)) {
+            errors.push(`dependency "${name}": unknown target "${decl.target}" (expected one of: ${[...VALID_TARGETS].join(', ')})`);
+        }
+        const runAs = decl.runAs || 'user';
+        if (!VALID_RUN_AS.has(runAs)) {
+            errors.push(`dependency "${name}": runAs must be 'user' or 'owner' (got "${runAs}")`);
+        }
+        if (decl.defaultBinding != null) {
+            if (typeof decl.defaultBinding !== 'string') {
+                errors.push(`dependency "${name}": defaultBinding must be a string UUID`);
+            } else if (!UUID_PATTERN.test(decl.defaultBinding)) {
+                errors.push(`dependency "${name}": defaultBinding must be a UUID (got "${decl.defaultBinding}")`);
+            }
+        }
+    }
+    return errors;
+}
+
+/**
+ * Build the dev-mode `context` object passed to server route handlers, so
+ * `await context.myDep.method(...)` works the same locally as it does after
+ * deploy. Mirrors the production sandbox's typed-proxy DI context built in
+ * `app-sandbox.js`.
+ *
+ * Dev-mode differences from production:
+ *   - There is no installer step locally, so each dep is auto-bound to its
+ *     manifest `defaultBinding` UUID. Deps without one return an unbound
+ *     proxy whose methods throw a pointed message — same shape as the
+ *     prod `makeUnboundProxy` behavior, just with a dev-flavored hint.
+ *   - `runAs` is informational only. Every dev call goes through the
+ *     vite plugin's auth header (the same identity that handles /api proxy
+ *     requests), regardless of whether the manifest declares user or owner.
+ *   - Driver option-merging (dataset filters, query default parameters,
+ *     integration paths/headers) is not replicated here. Dev is a thin
+ *     pass-through — exotic prod semantics surface as integration-test work,
+ *     not as silent dev parity.
+ *
+ * @param {Object} args
+ * @param {Object} args.deps - The raw `dependencies:` object
+ * @param {Function} args.apiFetch - The dev-server fetch helper
+ *   (path, { method, body }) => { status, body }
+ * @returns {Object} An object keyed by dependency name, values are typed
+ *   proxies with methods matching the target's production method surface.
+ */
+export function buildDevContext({ deps, apiFetch }) {
+    const context = {};
+    for (const [name, decl] of Object.entries(deps || {})) {
+        if (!decl || typeof decl !== 'object') continue;
+        const target = decl.target;
+        if (!VALID_TARGETS.has(target)) continue;
+
+        const targetId = (typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
+            ? decl.defaultBinding
+            : null;
+
+        context[name] = targetId
+            ? makeDevProxy({ name, target, targetId, apiFetch })
+            : makeUnboundDevProxy({ name, target });
+    }
+    return context;
+}
+
+function makeDevProxy({ name, target, targetId, apiFetch }) {
+    switch (target) {
+        case 'dataset':
+            return {
+                async search(payload) {
+                    return await devCall(apiFetch, 'POST', `datasets/${targetId}/_search`, payload || {}, name, 'dataset');
+                },
+                async fields() {
+                    return await devCall(apiFetch, 'GET', `datasets/${targetId}/fields`, null, name, 'dataset');
+                }
+            };
+        case 'query':
+            return {
+                async execute(payload) {
+                    return await devCall(apiFetch, 'POST', `queries/${targetId}/_execute`, payload || {}, name, 'query');
+                }
+            };
+        case 'datasource':
+            return {
+                async query(payload) {
+                    return await devCall(apiFetch, 'POST', `datasources/${targetId}/_query`, payload || {}, name, 'datasource');
+                }
+            };
+        case 'integration':
+            return {
+                async request(payload) {
+                    return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                }
+            };
+        default:
+            return {};
+    }
+}
+
+/**
+ * Build an unbound dev proxy whose every method throws a clear error pointing
+ * at the missing `defaultBinding`. The method-surface keys are populated so
+ * a typo on the method name throws TypeError immediately, not a silent
+ * `undefined is not a function` later — matching the prod unbound-proxy
+ * contract.
+ */
+function makeUnboundDevProxy({ name, target }) {
+    const methods = METHOD_SURFACE[target] || [];
+    const proxy = {};
+    for (const method of methods) {
+        proxy[method] = async () => {
+            throw new Error(
+                `Dependency "${name}" is not bound in dev — add \`defaultBinding: <uuid>\` to its entry in informer.yaml`
+            );
+        };
+    }
+    return proxy;
+}
+
+async function devCall(apiFetch, method, path, body, depName, resourceType) {
+    const opts = { method };
+    if (body !== null && body !== undefined) opts.body = body;
+    const { status, body: responseBody } = await apiFetch(path, opts);
+    if (status >= 400) {
+        const message = responseBody && typeof responseBody === 'object' && responseBody.message
+            ? responseBody.message
+            : String(status);
+        const err = new Error(`Dependency "${depName}" (${resourceType}) call failed: ${message}`);
+        err.status = status;
+        err.body = responseBody;
+        throw err;
+    }
+    return responseBody;
+}

package/src/env.js

@@ -0,0 +1,86 @@
+import dotenv from 'dotenv';
+import { existsSync } from 'node:fs';
+import { resolve, dirname, parse as parsePath } from 'node:path';
+
+/**
+ * Build an ordered list of .env file paths for dotenv to load.
+ *
+ * Priority (first match wins in dotenv):
+ *   1. <cwd>/.env.<mode>   (mode-specific, e.g. .env.test)
+ *   2. <cwd>/.env          (local defaults)
+ *   3. <parent>/.env.<mode> (walk up for monorepo shared config)
+ *   4. <parent>/.env
+ *   ... continues up to first parent that contains a .env file
+ *
+ * When mode is 'development' (Vite default), mode-specific files are skipped
+ * since .env already serves that purpose.
+ *
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string[]} Ordered file paths (may include non-existent files — dotenv ignores those)
+ */
+export function buildEnvPaths({ mode, cwd } = {}) {
+    const dir = cwd || process.cwd();
+    const useMode = mode && mode !== 'development';
+
+    // Local project .env files (highest priority)
+    const paths = [];
+    if (useMode) paths.push(resolve(dir, `.env.${mode}`));
+    paths.push(resolve(dir, '.env'));
+
+    // Walk up to parent directories for monorepo fallback
+    let current = dirname(dir);
+    const { root } = parsePath(dir);
+
+    while (current !== root) {
+        if (useMode) paths.push(resolve(current, `.env.${mode}`));
+        paths.push(resolve(current, '.env'));
+
+        // Stop at the first ancestor that has any .env file
+        const hasEnv = useMode
+            ? existsSync(resolve(current, `.env.${mode}`)) || existsSync(resolve(current, '.env'))
+            : existsSync(resolve(current, '.env'));
+
+        if (hasEnv) break;
+
+        current = dirname(current);
+    }
+
+    return paths;
+}
+
+/**
+ * Load environment variables using mode-aware, parent-walking dotenv paths.
+ *
+ * @param {{ mode?: string, cwd?: string }} options
+ */
+export function loadEnv({ mode, cwd } = {}) {
+    const paths = buildEnvPaths({ mode, cwd });
+    dotenv.config({ path: paths });
+}
+
+/**
+ * Determine the .env file path to write workspace IDs into.
+ * Writes to .env.<mode> when a non-default mode is active, otherwise .env.
+ *
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string}
+ */
+export function envWritePath({ mode, cwd } = {}) {
+    const dir = cwd || process.cwd();
+    const useMode = mode && mode !== 'development';
+    return resolve(dir, useMode ? `.env.${mode}` : '.env');
+}
+
+/**
+ * Parse --mode <name> from a process.argv array.
+ *
+ * @param {string[]} argv
+ * @returns {string|null}
+ */
+export function parseModeArg(argv) {
+    const idx = argv.indexOf('--mode');
+    if (idx !== -1 && idx + 1 < argv.length) {
+        return argv[idx + 1];
+    }
+    return null;
+}