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

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/publish.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import { readFile, access } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { collectAppFiles } from '../src/assemble.js';
+import { extractNotes } from '../src/changelog.js';
+import { publish } from '../src/publish.js';
+import { loadEnv, parseModeArg } from '../src/env.js';
+
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
+
+// --- Target + auth. You already have API keys sorted — just point these at the
+//     License Manager that fronts the marketplace cloud-api. ---
+const marketplaceUrl = process.env.INFORMER_MARKETPLACE_URL;
+const token = process.env.INFORMER_PUBLISH_TOKEN || process.env.INFORMER_API_KEY;
+
+if (!marketplaceUrl || !token) {
+    console.error('Missing required environment variables.');
+    console.error('  INFORMER_MARKETPLACE_URL=https://<license-manager-host>/cloud-api');
+    console.error('  INFORMER_PUBLISH_TOKEN=lmpub_<vendor publish key>');
+    process.exit(1);
+}
+
+// --- App + listing metadata from package.json "informer" block ---
+const projectRoot = resolve('.');
+let pkg;
+try {
+    pkg = JSON.parse(await readFile(join(projectRoot, 'package.json'), 'utf8'));
+} catch {
+    console.error('Could not read package.json in current directory.');
+    process.exit(1);
+}
+
+const inf = pkg.informer || {};
+const name = inf.name || pkg.name;
+const slug = inf.slug || defaultSlug(name);
+
+// Version: prefer the git tag (CI: GITHUB_REF_NAME=vX.Y.Z), then --version, then package.json.
+const version = argValue('--version') || tagVersion(process.env.GITHUB_REF_NAME) || pkg.version;
+
+if (!name || !slug || !version) {
+    console.error('Need a name, slug, and version. Set package.json "informer.name"/"informer.slug" and tag a release (vX.Y.Z) or pass --version.');
+    process.exit(1);
+}
+
+// Release notes: the section for this version, else the cumulative Unreleased block.
+const changeNotes = await extractNotes(join(projectRoot, 'CHANGELOG.md'), version);
+
+// Provenance (GitHub Actions). All optional — best-effort audit trail.
+const sourceRepo = process.env.GITHUB_REPOSITORY || undefined;
+const sourceCommit = process.env.GITHUB_SHA || undefined;
+const ciRun = process.env.GITHUB_RUN_ID
+    ? `${process.env.GITHUB_SERVER_URL || 'https://github.com'}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+    : undefined;
+
+// Assemble the same file set a deploy produces.
+let files;
+try {
+    files = await collectAppFiles({ distDir: join(projectRoot, 'dist'), projectRoot });
+} catch (err) {
+    console.error(err.message);
+    process.exit(1);
+}
+
+const icon = await resolveIcon(projectRoot, inf.icon);
+const channel = version.includes('-') ? 'beta' : 'stable';
+
+console.log(`Publishing ${name} v${version} (${channel}) — ${files.length} files${changeNotes ? '' : ' — no release notes found'}`);
+
+try {
+    const result = await publish({
+        marketplaceUrl,
+        token,
+        files,
+        icon,
+        fields: {
+            name,
+            slug,
+            version,
+            shortDescription: inf.shortDescription,
+            description: inf.description || pkg.description,
+            categories: inf.categories,
+            documentationUrl: inf.documentationUrl,
+            requires: inf.requires,
+            metadata: inf.metadata,
+            changeNotes,
+            sourceRepo,
+            sourceCommit,
+            ciRun
+        }
+    });
+    console.log(`Published ${slug} v${version} (${result.channel || channel}).`);
+} catch (err) {
+    console.error(err.message);
+    process.exit(1);
+}
+
+// --- helpers ---
+
+function argValue(flag) {
+    const i = process.argv.indexOf(flag);
+    return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : undefined;
+}
+
+function tagVersion(ref) {
+    return ref ? ref.replace(/^v/, '') : undefined;
+}
+
+function defaultSlug(value) {
+    if (!value) return undefined;
+    const base = value.startsWith('@') && value.includes('/') ? value.split('/')[1] : value;
+    return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+async function resolveIcon(root, configured) {
+    const candidates = [configured, 'favicon.svg', join('public', 'favicon.svg'), join('dist', 'favicon.svg')].filter(Boolean);
+    for (const rel of candidates) {
+        const abs = resolve(root, rel);
+        try {
+            await access(abs);
+            return { abs, filename: rel.split(/[/\\]/).pop() };
+        } catch {
+            // try next candidate
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.4.0",
+    "version": "2.5.0-beta.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "repository": {
         "type": "git",
@@ -24,10 +24,12 @@
             "default": "./src/index.js"
         },
         "./deploy": "./src/deploy.js",
+        "./publish": "./src/publish.js",
         "./workspace": "./src/workspace.js"
     },
     "bin": {
         "informer-deploy": "./bin/deploy.js",
+        "informer-publish": "./bin/publish.js",
         "informer-init": "./bin/init.js",
         "informer-workspace": "./bin/workspace.js",
         "create-magic-report": "./bin/init.js"

package/src/agent-dev.js

@@ -1,8 +1,8 @@
-import { createHmac } from 'node:crypto';
 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;
@@ -171,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' }
@@ -193,12 +198,12 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         return { ok: true };
     }
 
-    // crypto helper — mirrors the sandbox's crypto.hmac()
-    const cryptoHelper = {
-        hmac(algorithm, key, data, encoding) {
-            return createHmac(algorithm, key).update(data).digest(encoding || 'hex');
-        }
-    };
+    // 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) => {
@@ -277,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]));
@@ -394,7 +407,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler(tc.input, { query, fetch: apiFetch, emit, crypto: cryptoHelper, markdown, log, 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/assemble.js

@@ -0,0 +1,87 @@
+import { readdir, stat, access } from 'node:fs/promises';
+import { join, relative, posix } from 'node:path';
+
+/**
+ * The canonical set of files that make up a deployable Informer app library.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for what an app "is" on disk, shared by
+ * both `informer-deploy` (uploads each file to a live instance) and
+ * `informer-publish` (tars the same set for the marketplace). Keeping the
+ * enumeration in one place is what guarantees a published artifact is
+ * byte-identical to what a normal deploy produces.
+ *
+ * Layout rule: the Vite build output (`dist/`) lands at the library ROOT
+ * (index.html, assets/…), while the source trees keep their directory prefix
+ * (server/…, tools/…) — matching how an app's library is structured in Informer.
+ */
+const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
+const SOURCE_DIRS = ['migrations', 'tools', 'server', 'webhooks'];
+
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** Recursively walk a directory, returning absolute file paths (not dirs). */
+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;
+}
+
+/** Normalise a path to forward slashes for use as a library/tar entry name. */
+function toLibraryPath(p) {
+    return posix.normalize(p.split('\\').join('/'));
+}
+
+/**
+ * Collect every file that belongs in the app library, each as { abs, rel },
+ * where `rel` is the path it should occupy in the library (and in the tar).
+ *
+ * @param {{ distDir: string, projectRoot: string }} opts
+ * @returns {Promise<Array<{ abs: string, rel: string }>>}
+ */
+export async function collectAppFiles({ distDir, projectRoot }) {
+    if (!await exists(distDir)) {
+        throw new Error(`Build output not found at "${distDir}" — run the build first.`);
+    }
+
+    const files = [];
+
+    // dist/** -> library root
+    for (const abs of await walkDir(distDir)) {
+        files.push({ abs, rel: toLibraryPath(relative(distDir, abs)) });
+    }
+
+    // root config files -> library root
+    for (const name of ROOT_CONFIG_FILES) {
+        const abs = join(projectRoot, name);
+        if (await exists(abs)) files.push({ abs, rel: name });
+    }
+
+    // source trees -> keep their prefix (server/…, migrations/…, tools/…, webhooks/…)
+    for (const dir of SOURCE_DIRS) {
+        const root = join(projectRoot, dir);
+        if (!await exists(root)) continue;
+        for (const abs of await walkDir(root)) {
+            files.push({ abs, rel: toLibraryPath(relative(projectRoot, abs)) });
+        }
+    }
+
+    return files;
+}
+
+export { ROOT_CONFIG_FILES, SOURCE_DIRS };

package/src/changelog.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Extract release notes for a version from a Keep-a-Changelog style CHANGELOG.md.
+ *
+ * Looks for the section header whose name matches `version` (e.g. `## [1.4.0]`,
+ * `## 1.4.0`, `## v1.4.0`); if absent, falls back to `## [Unreleased]`. Returns
+ * the section body trimmed, or '' if nothing matches / the file is missing.
+ *
+ * This is what makes the dual notes flow work: betas ship the cumulative
+ * `Unreleased` block, while a stable release promotes `Unreleased` to a
+ * versioned heading before tagging so its exact section is matched.
+ *
+ * @param {string} changelogPath
+ * @param {string} version
+ * @returns {Promise<string>}
+ */
+export async function extractNotes(changelogPath, version) {
+    let text;
+    try {
+        text = await readFile(changelogPath, 'utf8');
+    } catch {
+        return '';
+    }
+    return sectionBody(text, version) ?? sectionBody(text, 'Unreleased') ?? '';
+}
+
+/** Body of the first `## [name]` / `## name` section, up to the next `## `. */
+function sectionBody(text, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const header = new RegExp(`^##\\s+\\[?v?${escaped}\\]?.*$`, 'im');
+    const match = header.exec(text);
+    if (!match) return null;
+
+    const after = text.slice(match.index + match[0].length);
+    const next = after.search(/^##\s/m);
+    const body = (next === -1 ? after : after.slice(0, next)).trim();
+    return body || null;
+}

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/index.js

@@ -2,6 +2,7 @@ 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';
@@ -119,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/publish.js

@@ -0,0 +1,97 @@
+import { mkdtemp, mkdir, copyFile, rm, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileP = promisify(execFile);
+
+class PublishError extends Error {
+    constructor(status, body, url) {
+        super(`Marketplace publish failed: ${status}${body ? ` — ${body}` : ''}${url ? ` (${url})` : ''}`);
+        this.name = 'PublishError';
+        this.status = status;
+        this.body = body;
+        this.url = url;
+    }
+}
+
+export { PublishError };
+
+/**
+ * Stage the assembled files into a temp dir (preserving their library-relative
+ * layout) and tar.gz them. System `tar` keeps the archive format exactly what
+ * the server's node-tar expects; COPYFILE_DISABLE suppresses macOS AppleDouble
+ * (`._*`) junk from leaking into the archive.
+ *
+ * @param {Array<{abs: string, rel: string}>} files
+ * @returns {Promise<Buffer>}
+ */
+async function buildArchive(files) {
+    const stage = await mkdtemp(join(tmpdir(), 'informer-publish-'));
+    const archivePath = `${stage}.tgz`;
+    try {
+        for (const { abs, rel } of files) {
+            const dest = join(stage, rel);
+            await mkdir(dirname(dest), { recursive: true });
+            await copyFile(abs, dest);
+        }
+        await execFileP('tar', ['-czf', archivePath, '-C', stage, '.'], {
+            env: { ...process.env, COPYFILE_DISABLE: '1' }
+        });
+        return await readFile(archivePath);
+    } finally {
+        await rm(stage, { recursive: true, force: true });
+        await rm(archivePath, { force: true });
+    }
+}
+
+/**
+ * Publish an assembled app to the marketplace (License Manager `/packs/publish`).
+ *
+ * @param {Object} opts
+ * @param {string} opts.marketplaceUrl - base URL fronting the cloud-api
+ * @param {string} opts.token - vendor publish token (sent as Bearer)
+ * @param {Array<{abs: string, rel: string}>} opts.files - assembled app files
+ * @param {Object} opts.fields - publish metadata; non-string values are JSON-encoded
+ *   (the endpoint parses categories/requires/metadata as JSON strings)
+ * @param {{abs: string, filename: string}} [opts.icon] - optional listing icon
+ * @returns {Promise<Object>} the publish response
+ */
+export async function publish({ marketplaceUrl, token, files, fields, icon }) {
+    const archive = await buildArchive(files);
+
+    const form = new FormData();
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === undefined || value === null || value === '') continue;
+        form.append(key, typeof value === 'string' ? value : JSON.stringify(value));
+    }
+    form.append(
+        'archive',
+        new Blob([archive], { type: 'application/gzip' }),
+        `${fields.slug}-${fields.version}.tgz`
+    );
+    if (icon) {
+        const iconBuffer = await readFile(icon.abs);
+        form.append('icon', new Blob([iconBuffer]), icon.filename);
+    }
+
+    const url = `${marketplaceUrl.replace(/\/+$/, '')}/packs/publish`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}` },
+        body: form
+    });
+
+    if (!res.ok) {
+        let body = '';
+        try {
+            body = await res.text();
+        } catch {
+            body = '';
+        }
+        throw new PublishError(res.status, body, url);
+    }
+
+    return await res.json();
+}

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,12 +240,8 @@ 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) => {
@@ -263,6 +269,11 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
                 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(),
@@ -291,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, emit, crypto: cryptoHelper, markdown, log, 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 || {};
@@ -321,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');