@entrinsik/vite-plugin-informer 2.3.0 → 2.5.0

package/bin/deploy.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 
-import dotenv from 'dotenv';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { deploy } from '../src/deploy.js';
+import { loadEnv, parseModeArg } from '../src/env.js';
 
-dotenv.config();
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
 
 const baseUrl = process.env.INFORMER_URL;
 const apiKey = process.env.INFORMER_API_KEY;

package/bin/init.js

@@ -13,40 +13,66 @@ const cwd = process.cwd();
 function generateInformerYaml() {
     return `# Informer App Configuration
 # =========================
-# This file controls which Informer APIs your app can access and defines
-# custom roles for role-based UIs.
+# This file controls the data your app depends on and defines custom
+# roles for role-based UIs.
 #
-# Without an access section, all API access is blocked (secure by default).
+# Without dependencies: or access:, all API access is blocked (secure
+# by default).
 
 # ============================================================================
-# DATA ACCESS
+# DEPENDENCIES (preferred)
 # ============================================================================
-# The access section controls which APIs the app can call when shared.
+# Typed slots that the installer binds to actual resources at deploy
+# time. Each slot becomes a property on the handler context object —
+# call methods on it instead of building raw API URLs.
 #
-# access:
-#   datasets:
-#     - admin:sales-data             # Full dataset access
-#     - id: admin:orders             # With row-level security
-#       filter:
-#         region: $user.custom.region
+# Slot methods by target:
+#   dataset     → context.<slot>.search(esQuery)  /  context.<slot>.fields()
+#   query       → context.<slot>.execute(params)
+#   datasource  → context.<slot>.query(payload)
+#   integration → context.<slot>.request({ method, path, body })
 #
-#   queries:
-#     - admin:monthly-summary
+# defaultBinding must be a UUID (not a configId). Look up UUIDs via:
+#   GET /api/datasets-list      → for target: dataset
+#   GET /api/queries-list       → for target: query
+#   GET /api/datasources-list   → for target: datasource
+#   GET /api/integrations-list  → for target: integration
 #
-#   integrations:
-#     - salesforce
+# Example:
 #
-#   datasources:
-#     - postgres-main
+# dependencies:
+#   sales:
+#     target: dataset
+#     defaultBinding: 7d5a9b1e-0c83-4bde-9e2a-3a4b5c6d7e8f
+#   orders:
+#     target: dataset
+#     defaultBinding: 1f2e3d4c-5b6a-7980-1234-56789abcdef0
+#     options:
+#       filter:
+#         region: $user.custom.region    # Row-level security
+#   monthly_summary:
+#     target: query
+#     defaultBinding: 9a8b7c6d-5e4f-3a2b-1c0d-fedcba987654
+#   salesforce:
+#     target: integration                # No defaultBinding — installer picks
+#     options:
+#       headers:
+#         Authorization: Bearer $user.custom.sfToken
+
+dependencies: {}
+
+# ============================================================================
+# ACCESS (raw API allowlist — for paths that don't fit the typed-slot model)
+# ============================================================================
+# Use access.apis for endpoints not covered by dependencies: slots,
+# such as AI model routes or custom server endpoints.
 #
-#   apis:                            # Raw API paths (advanced)
+# access:
+#   apis:
+#     - POST /api/models/go_everyday/_object
+#     - POST /api/models/go_everyday/_chat
 #     - POST /api/custom/endpoint
 
-access:
-  datasets: []
-  queries: []
-  integrations: []
-
 # ============================================================================
 # ROLES (optional)
 # ============================================================================
@@ -111,7 +137,8 @@ async function init() {
     const pkgPath = resolve(cwd, 'package.json');
     if (!await exists(pkgPath)) {
         console.error('No package.json found. Run this in a Vite project directory.');
-        console.error('Create one first with: npm create vite@latest');
+        console.error('Create one first with: npm create vite@latest . -- --template react');
+        console.error('(Use --template react-ts for TypeScript, or vanilla/vue/svelte/etc.)');
         process.exit(1);
     }
 
@@ -121,7 +148,8 @@ async function init() {
     const hasVite = pkg.devDependencies?.vite || pkg.dependencies?.vite;
     if (!hasVite) {
         console.error('Vite not found in dependencies.');
-        console.error('Create a Vite project first: npm create vite@latest');
+        console.error('Create a Vite project first: npm create vite@latest . -- --template react');
+        console.error('(Use --template react-ts for TypeScript, or vanilla/vue/svelte/etc.)');
         process.exit(1);
     }
 
@@ -198,7 +226,7 @@ INFORMER_API_KEY=your-api-key
     const informerYamlPath = resolve(cwd, 'informer.yaml');
     if (!await exists(informerYamlPath)) {
         await writeFile(informerYamlPath, generateInformerYaml());
-        console.log('Created informer.yaml (configure API access and roles)');
+        console.log('Created informer.yaml (declare your data dependencies and roles)');
     }
 
     // 10. Add .env to .gitignore if not present
@@ -207,7 +235,7 @@ INFORMER_API_KEY=your-api-key
     console.log('\nSetup complete!\n');
     console.log('Next steps:');
     console.log('  1. Update .env with your Informer credentials');
-    console.log('  2. Update informer.yaml with the datasets/APIs your app needs');
+    console.log('  2. Declare your data dependencies in informer.yaml (see comments inside)');
     console.log('  3. Run: npm install');
     console.log('  4. Run: npm run dev');
     console.log('');

package/bin/workspace.js

@@ -1,22 +1,28 @@
 #!/usr/bin/env node
 
-import dotenv from 'dotenv';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from '../src/client.js';
+import { loadEnv, envWritePath, parseModeArg } from '../src/env.js';
 import { init, migrate, reset } from '../src/workspace.js';
 
-dotenv.config();
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
 
-const command = process.argv[2];
+// Strip --mode <value> from argv before parsing the command
+const args = process.argv.slice(2).filter((arg, i, arr) => arg !== '--mode' && arr[i - 1] !== '--mode');
+const command = args[0];
 
 if (!command || !['init', 'migrate', 'reset'].includes(command)) {
-    console.error('Usage: informer-workspace <init|migrate|reset>');
+    console.error('Usage: informer-workspace <init|migrate|reset> [--mode <name>]');
     console.error('');
     console.error('Commands:');
     console.error('  init      Create a dev workspace datasource and run migrations');
     console.error('  migrate   Run pending migrations against the dev workspace');
     console.error('  reset     Drop all tables and re-run all migrations');
+    console.error('');
+    console.error('Options:');
+    console.error('  --mode <name>  Load .env.<name> (e.g. --mode test, --mode production)');
     process.exit(1);
 }
 
@@ -33,7 +39,7 @@ if (!baseUrl || (!apiKey && (!user || !pass))) {
 
 const api = createClient({ baseUrl, apiKey, user, pass });
 const migrationsDir = resolve('migrations');
-const envPath = resolve('.env');
+const envPath = envWritePath({ mode });
 
 try {
     if (command === 'init') {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.3.0",
+    "version": "2.5.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "repository": {
         "type": "git",

package/src/agent-dev.js

@@ -2,6 +2,7 @@ import { readFile, readdir, stat, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parse as parseUrl } from 'node:url';
 import yaml from 'yaml';
+import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 const parseYaml = yaml.parse;
 
 const MAX_STEPS = 20;
@@ -170,7 +171,12 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
     // fetch() — proxies API calls to the Informer server (same as server-routes.js)
     async function apiFetch(path, opts = {}) {
         const method = (opts.method || 'GET').toUpperCase();
-        const url = `${serverOrigin}/api/${path.replace(/^\/?(?:api\/)?/, '')}`;
+        // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath).
+        const apiPath = normalizeFetchPath(path);
+        if (!apiPath) {
+            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` } };
+        }
+        const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
             method,
             headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
@@ -192,6 +198,33 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         return { ok: true };
     }
 
+    // notify/email — delivery is a console-logged no-op in dev, but required-field
+    // validation mirrors prod so a tool that passes here won't 500 in production.
+    const { notify, email } = buildDevMessaging('[agent-dev]');
+
+    // crypto helper — mirrors the prod sandbox crypto surface
+    const cryptoHelper = buildDevCrypto();
+
+    // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
+    const logCall = (level, message, data) => {
+        const msg = typeof message === 'string' ? message : JSON.stringify(message);
+        const args = [`[app-log] [${level}] ${msg}`];
+        if (data) args.push(data);
+        console.log(...args);
+    };
+    const log = Object.assign(
+        (message, data) => logCall('info', message, data),
+        {
+            debug: (message, data) => logCall('debug', message, data),
+            info: (message, data) => logCall('info', message, data),
+            warn: (message, data) => logCall('warn', message, data),
+            error: (message, data) => logCall('error', message, data)
+        }
+    );
+
+    // markdown helper — passthrough in dev (production uses `marked`)
+    const markdown = (text) => text;
+
     return async function agentDevMiddleware(req, res, next) {
         try {
             const parsed = parseUrl(req.url, true);
@@ -249,6 +282,14 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
                 const instructions = agentDef.instructions || '';
                 const agentToolNames = agentDef.tools || [];
 
+                // Build the typed dependency context + env the same way the
+                // server-routes dev middleware does, so tools using
+                // `context.<slot>.<method>(...)` and `env` work locally and match
+                // the prod sandbox bag.
+                const deps = await loadDependencies(projectRoot);
+                const context = buildDevContext({ deps, apiFetch });
+                const env = await loadAppEnv(projectRoot);
+
                 // Load tool handlers via ssrLoadModule
                 const localTools = await scanLocalTools(projectRoot);
                 const toolMap = new Map(localTools.map(t => [t.name, t]));
@@ -366,7 +407,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler(tc.input, { query, fetch: apiFetch, emit, context: triggerEvent });
+                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, notify, email, crypto: cryptoHelper, markdown, log, env });
                             } catch (err) {
                                 console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
                                 result = { error: err.message };

package/src/deploy.js

@@ -102,22 +102,9 @@ 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}...`);

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;
+}

package/src/index.js

@@ -1,8 +1,9 @@
-import dotenv from 'dotenv';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from './client.js';
+import { loadDependencies, validateDependencies } from './dev-dependencies.js';
+import { loadEnv, envWritePath } from './env.js';
 import { createMiddleware as createServerRoutes } from './server-routes.js';
 import { createAgentMiddleware } from './agent-dev.js';
 import { init, migrate } from './workspace.js';
@@ -23,12 +24,14 @@ export default function informer(options = {}) {
     let authHeader = null;
     let serverOrigin = null;
     let devWorkspaceId = null;
+    let activeMode = null;
 
     return {
         name: 'vite-plugin-informer',
 
-        config(_, { command }) {
-            dotenv.config();
+        config(_, { command, mode }) {
+            activeMode = mode;
+            loadEnv({ mode });
 
             isDev = command === 'serve';
 
@@ -57,7 +60,8 @@ export default function informer(options = {}) {
                                 changeOrigin: true,
                                 headers: {
                                     Authorization: authHeader
-                                }
+                                },
+                                ...options.proxy
                             }
                         }
                     };
@@ -106,7 +110,7 @@ export default function informer(options = {}) {
                             api,
                             slug,
                             migrationsDir,
-                            envPath: resolve(projectRoot, '.env')
+                            envPath: envWritePath({ mode: activeMode })
                         });
                         devWorkspaceId = result.workspaceId;
                     }
@@ -116,6 +120,19 @@ export default function informer(options = {}) {
                 }
             }
 
+            // Surface manifest-level dependency declaration errors at boot,
+            // not at `npx informer publish` time. Matches the deploy.js
+            // validation so devs see the same wording pre-deploy.
+            try {
+                const deps = await loadDependencies(projectRoot);
+                const errors = validateDependencies(deps);
+                for (const message of errors) {
+                    console.error(`[informer] informer.yaml: ${message}`);
+                }
+            } catch (err) {
+                console.warn(`[informer] Could not validate informer.yaml dependencies: ${err.message}`);
+            }
+
             // Mount server-side route handlers if a server/ directory exists
             const serverDir = resolve(projectRoot, 'server');
 

package/src/server-routes.js

@@ -1,10 +1,14 @@
-import { createHmac } from 'node:crypto';
 import { readdir, stat } from 'node:fs/promises';
 import { join, relative, posix } from 'node:path';
 import { parse as parseUrl } from 'node:url';
+import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 
 const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
+// Strict base64 — see view-api.js for the rationale. Mirror kept identical
+// to keep dev and prod behavior aligned.
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
 /**
  * Convert a file path under server/ to a route path.
  *
@@ -171,7 +175,13 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
     // fetch() implementation — proxies API calls to the Informer server
     async function apiFetch(path, opts = {}) {
         const method = (opts.method || 'GET').toUpperCase();
-        const url = `${serverOrigin}/api/${path.replace(/^\/?(?:api\/)?/, '')}`;
+        // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath);
+        // reject non-canonical shapes here instead of silently accepting them.
+        const apiPath = normalizeFetchPath(path);
+        if (!apiPath) {
+            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` } };
+        }
+        const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
             method,
             headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
@@ -230,13 +240,40 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 try { body = JSON.parse(rawBody); } catch { body = rawBody; }
             }
 
-            // crypto helper — mirrors the sandbox's crypto.hmac()
-            const cryptoHelper = {
-                hmac(algorithm, key, data, encoding) {
-                    return createHmac(algorithm, key).update(data).digest(encoding || 'hex');
+            // crypto helper — mirrors the prod sandbox crypto surface
+            const cryptoHelper = buildDevCrypto();
+
+            // log helper — mirrors sandbox log(message, data) + log.info/warn/error/debug
+            const logCall = (level, message, data) => {
+                const msg = typeof message === 'string' ? message : JSON.stringify(message);
+                const args = [`[app-log] [${level}] ${msg}`];
+                if (data) args.push(data);
+                console.log(...args);
+            };
+            const log = Object.assign(
+                (message, data) => logCall('info', message, data),
+                {
+                    debug: (message, data) => logCall('debug', message, data),
+                    info: (message, data) => logCall('info', message, data),
+                    warn: (message, data) => logCall('warn', message, data),
+                    error: (message, data) => logCall('error', message, data)
                 }
+            );
+
+            // markdown helper — passthrough in dev (production uses `marked`)
+            const markdown = (text) => text;
+
+            // emit helper — no-op in dev (logs to console)
+            const emit = (event, payload) => {
+                console.log(`[app-event] emit("${event}",`, JSON.stringify(payload), ')');
+                return { ok: true };
             };
 
+            // notify/email — delivery is a console-logged no-op in dev, but the
+            // required-field validation mirrors prod so an app that passes here
+            // won't 500 in production.
+            const { notify, email } = buildDevMessaging('[app]');
+
             // Build request context
             const request = {
                 method: req.method.toUpperCase(),
@@ -265,20 +302,39 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 res.end(JSON.stringify(earlyBody));
             }
 
-            // Call handler
-            const result = await handler({ query, fetch: apiFetch, respond, crypto: cryptoHelper, env: {}, request });
+            // Build the dependency-injection context the same way the prod
+            // sandbox does, so handlers using `await context.myDep.method(...)`
+            // work locally. Loaded per request so edits to informer.yaml take
+            // effect without a dev-server restart.
+            const deps = await loadDependencies(projectRoot);
+            const context = buildDevContext({ deps, apiFetch });
+            const env = await loadAppEnv(projectRoot);
+
+            // Call handler — bag mirrors the prod sandbox (see app-sandbox.js).
+            const result = await handler({ request, context, query, fetch: apiFetch, respond, emit, notify, email, crypto: cryptoHelper, markdown, log, env });
 
             // If respond() was already called, the response is already sent
             if (responded) return;
 
-            // Normalize response (mirrors app-sandbox.js buildInvokeScript logic)
-            let status, responseBody, responseHeaders;
+            // Normalize response (mirrors app-sandbox.js buildInvokeScript logic).
+            // The encoding allow-list and contract checks are enforced inside the
+            // ivm in production; replicate them here so handlers see the same
+            // errors in dev (where there's no isolate to attribute the throw to).
+            // If you change this, mirror it in modules/app/routes/view-api.js.
+            let status, responseBody, responseHeaders, encoding;
 
             if (result === undefined || result === null) {
                 status = 204;
                 responseBody = null;
                 responseHeaders = {};
             } else if (typeof result === 'object' && typeof result.status === 'number') {
+                encoding = typeof result.encoding === 'string' ? result.encoding : null;
+                if (encoding !== null && encoding !== 'base64') {
+                    throw new Error(`Unknown response encoding: ${JSON.stringify(encoding)} (expected 'base64' or omitted)`);
+                }
+                if (encoding === 'base64' && typeof result.body !== 'string') {
+                    throw new Error(`encoding: 'base64' requires body to be a base64-encoded string, got ${typeof result.body}`);
+                }
                 status = result.status || 200;
                 responseBody = result.body !== undefined ? result.body : null;
                 responseHeaders = result.headers || {};
@@ -295,6 +351,20 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
 
             if (responseBody === null) {
                 res.end();
+            } else if (encoding === 'base64' && typeof responseBody === 'string') {
+                if (!BASE64_RE.test(responseBody)) {
+                    throw new Error('Handler returned malformed base64 body');
+                }
+                res.end(Buffer.from(responseBody, 'base64'));
+            } else if (typeof responseBody === 'string') {
+                // Pre-PR the dev middleware always JSON.stringify'd the body, so
+                // a handler returning { body: 'hello' } emitted "hello" (with
+                // quotes) — diverging from prod which passed strings verbatim.
+                // This branch fixes that parity.
+                if (!res.getHeader('content-type')) {
+                    res.setHeader('Content-Type', 'application/json');
+                }
+                res.end(responseBody);
             } else {
                 if (!res.getHeader('content-type')) {
                     res.setHeader('Content-Type', 'application/json');

package/src/workspace.js

@@ -1,5 +1,5 @@
 import { readdir, readFile, writeFile, access } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 
 /**
  * Execute raw SQL against a workspace datasource via the _sql route.
@@ -122,7 +122,7 @@ export async function init({ api, slug, migrationsDir, envPath }) {
     }
 
     await writeFile(envPath, envContent);
-    console.log(`Saved INFORMER_DEV_WORKSPACE=${workspaceId} to .env`);
+    console.log(`Saved INFORMER_DEV_WORKSPACE=${workspaceId} to ${basename(envPath)}`);
 
     return { workspaceId, ...result };
 }