@entrinsik/vite-plugin-informer 2.6.0-beta.0 → 2.6.0-beta.1

package/index.d.ts

@@ -1,2 +1,26 @@
 import type { Plugin } from 'vite';
-export default function informer(): Plugin;
+
+/**
+ * Dev-only binding for a `target: app` dependency slot. Points `request()` at
+ * the target app in dev; overrides the manifest `defaultBinding` when both are
+ * present.
+ *
+ * - `app` — the target app (`owner:slug` or UUID). Powers `request()`.
+ *
+ * A bare string is shorthand for `{ app }`.
+ */
+export interface AppDevBinding {
+    app?: string;
+}
+
+export interface InformerPluginOptions {
+    mock?: {
+        report?: { id?: string; name?: string };
+        theme?: 'light' | 'dark';
+        roles?: string[];
+    };
+    devBindings?: Record<string, string | AppDevBinding>;
+    proxy?: Record<string, unknown>;
+}
+
+export default function informer(options?: InformerPluginOptions): Plugin;

package/package.json

@@ -1,7 +1,10 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.6.0-beta.0",
+    "version": "2.6.0-beta.1",
     "description": "Vite plugin and deploy tool for Informer App development",
+    "scripts": {
+        "test": "node --test"
+    },
     "repository": {
         "type": "git",
         "url": "https://github.com/entrinsik-org/i5.git",

package/src/agent-dev.js

@@ -7,6 +7,10 @@ const parseYaml = yaml.parse;
 
 const MAX_STEPS = 20;
 
+// Cap dev proxy calls at 30s so a hung upstream fails loudly. (The AI _chat
+// stream below uses its own fetch.)
+const FETCH_TIMEOUT_MS = 30000;
+
 /**
  * Read and parse informer.yaml from the project root.
  *
@@ -145,7 +149,7 @@ async function readSSE(response) {
  * @param {Object} opts - Configuration
  * @returns {Function} Connect middleware
  */
-export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot }) {
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken }) {
 
     // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
     async function query(sql, params) {
@@ -169,29 +173,57 @@ 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 = {}) {
+    async function fetchAs(auth, path, opts = {}) {
         const method = (opts.method || 'GET').toUpperCase();
         // 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)}` } };
+            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` }, contentType: 'application/json' };
         }
         const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
             method,
-            headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
+            headers: { Authorization: auth, 'Content-Type': 'application/json', ...(opts.headers || {}) }
         };
 
-        if (opts.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+        if (opts.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
             fetchOpts.body = JSON.stringify(opts.body);
         }
 
-        const resp = await globalThis.fetch(url, fetchOpts);
+        // Read the stream once — `.json()` consumes it, so a `.text()` fallback
+        // would throw "Body is unusable" on any non-JSON response. Transport
+        // failure/timeout → synthetic 502 so the dep layer names it. See server-routes.js.
+        let status, contentType, text;
+        try {
+            const resp = await globalThis.fetch(url, { ...fetchOpts, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            status = resp.status;
+            contentType = resp.headers.get('content-type') || '';
+            text = await resp.text();
+        } catch (err) {
+            const reason = (err.cause && err.cause.message) || err.message;
+            return { status: 502, body: { message: `fetch to ${url} failed: ${reason}` }, contentType: 'application/json' };
+        }
         let body;
-        try { body = await resp.json(); } catch { body = await resp.text(); }
-        return { status: resp.status, body };
+        try { body = JSON.parse(text); } catch { body = text; }
+        return { status, body, contentType };
     }
 
+    async function apiFetch(path, opts = {}) {
+        return await fetchAs(authHeader, path, opts);
+    }
+
+    // Cross-app request() hits the target's /view/_/ dispatch, which accepts only
+    // the token/session strategies — not basic auth. In API-key mode the
+    // INFORMER_API_KEY Bearer is reused; under basic auth INFORMER_APP_TOKEN is
+    // required. appFetch stamps x-informer-app-depth:1 for the one-hop guard.
+    // See server-routes.js.
+    const appAuth = appToken
+        ? `Bearer ${appToken}`
+        : (authHeader && authHeader.startsWith('Bearer ') ? authHeader : null);
+    const appFetch = appAuth
+        ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
+        : null;
+
     // emit() — no-op in dev mode (logs to console)
     function emit(event, payload) {
         console.log(`[agent-dev] emit("${event}",`, JSON.stringify(payload), ')');
@@ -287,7 +319,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
                 // `context.<slot>.<method>(...)` and `env` work locally and match
                 // the prod sandbox bag.
                 const deps = await loadDependencies(projectRoot);
-                const context = buildDevContext({ deps, apiFetch });
+                const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
                 const env = await loadAppEnv(projectRoot);
 
                 // Load tool handlers via ssrLoadModule

package/src/assemble.js

@@ -15,7 +15,15 @@ import { join, relative, posix } from 'node:path';
  * (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'];
+const SOURCE_DIRS = ['migrations', 'tools', 'server', 'webhooks', 'lib', 'shared'];
+
+// Entries never worth shipping in an app's server-side library: OS/editor
+// dotfiles (.DS_Store, .env), nested dependency trees, and test files. Applied
+// only to the source-tree dirs (lib/, shared/, etc.) — which use generic names
+// and are walked raw from the project root — not to the Vite dist/ output,
+// where a dot-directory (e.g. .well-known/) can be a real asset.
+const isExcludedSourceEntry = (name) =>
+    name === 'node_modules' || name.startsWith('.') || name.endsWith('.test.js');
 
 async function exists(path) {
     try {
@@ -27,14 +35,15 @@ async function exists(path) {
 }
 
 /** Recursively walk a directory, returning absolute file paths (not dirs). */
-async function walkDir(dir) {
+async function walkDir(dir, exclude) {
     const results = [];
     const items = await readdir(dir);
     for (const item of items) {
+        if (exclude && exclude(item)) continue;
         const full = join(dir, item);
         const s = await stat(full);
         if (s.isDirectory()) {
-            results.push(...await walkDir(full));
+            results.push(...await walkDir(full, exclude));
         } else {
             results.push(full);
         }
@@ -72,11 +81,11 @@ export async function collectAppFiles({ distDir, projectRoot }) {
         if (await exists(abs)) files.push({ abs, rel: name });
     }
 
-    // source trees -> keep their prefix (server/…, migrations/…, tools/…, webhooks/…)
+    // source trees -> keep their prefix (server/…, migrations/…, lib/…, shared/…)
     for (const dir of SOURCE_DIRS) {
         const root = join(projectRoot, dir);
         if (!await exists(root)) continue;
-        for (const abs of await walkDir(root)) {
+        for (const abs of await walkDir(root, isExcludedSourceEntry)) {
             files.push({ abs, rel: toLibraryPath(relative(projectRoot, abs)) });
         }
     }

package/src/dev-dependencies.js

@@ -150,16 +150,25 @@ export function buildDevMessaging(logPrefix = '[app]') {
 // 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_TARGETS = new Set(['dataset', 'query', 'datasource', 'integration', 'app']);
 const VALID_RUN_AS = new Set(['user', 'owner']);
 
+// Targets that accept `defaultBinding:` in the manifest — mirrors
+// DEFAULT_BINDING_LOOKUP in deploy.js. All resolve the target under read_access.
+const DEFAULT_BINDABLE_TARGETS = new Set(['dataset', 'query', 'datasource', 'integration', 'app']);
+
 const METHOD_SURFACE = {
     dataset: ['search', 'fields'],
     query: ['execute'],
     datasource: ['query'],
-    integration: ['request']
+    integration: ['request'],
+    app: ['request']
 };
 
+// Cross-app request() method allow-list — mirrors REQUEST_METHODS in
+// entity-type/app.js so dev rejects the same shapes prod 400s.
+const REQUEST_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
 /**
  * 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
@@ -238,7 +247,11 @@ export function validateDependencies(deps) {
             errors.push(`dependency "${name}": runAs must be 'user' or 'owner' (got "${runAs}")`);
         }
         if (decl.defaultBinding != null) {
-            if (typeof decl.defaultBinding !== 'string') {
+            if (!DEFAULT_BINDABLE_TARGETS.has(decl.target)) {
+                // Same rejection the deploy performs — surface it at dev boot
+                // rather than letting the deploy be the first to say no.
+                errors.push(`dependency "${name}": target "${decl.target}" does not support defaultBinding (bind it via PUT /api/apps/<id>/dependencies/${name})`);
+            } else 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}")`);
@@ -248,6 +261,68 @@ export function validateDependencies(deps) {
     return errors;
 }
 
+/**
+ * Validate the plugin's `devBindings` option against the declared dependencies.
+ * Returns human-readable error strings (empty when valid). Runs at dev boot so a
+ * typo'd slot ("kanbann") is caught loudly rather than silently ignored until
+ * the first call reports the slot as unbound — telling the developer to add the
+ * thing they think they already added.
+ *
+ * A binding key must name a declared `target: app` dependency; its value must be
+ * a non-empty `owner:slug` string (shorthand for `{ app }`) or an object with a
+ * non-empty `app` (the target app, for request()).
+ *
+ * @param {Object} deps - The raw `dependencies:` object from informer.yaml
+ * @param {Object} devBindings - The plugin's `devBindings` option
+ * @returns {string[]} Error messages, one per problem
+ */
+export function validateDevBindings(deps, devBindings) {
+    const errors = [];
+    const declared = (deps && typeof deps === 'object') ? deps : {};
+    for (const [name, binding] of Object.entries(devBindings || {})) {
+        const decl = declared[name];
+        if (!decl || typeof decl !== 'object') {
+            errors.push(`devBindings."${name}": no dependency "${name}" is declared in informer.yaml`);
+            continue;
+        }
+        if (decl.target !== 'app') {
+            errors.push(`devBindings."${name}": only "target: app" dependencies take a devBinding (got "${decl.target}")`);
+            continue;
+        }
+        if (typeof binding === 'string') {
+            if (!binding.trim()) {
+                errors.push(`devBindings."${name}": binding string must be a non-empty "owner:slug"`);
+            }
+            continue;
+        }
+        if (!binding || typeof binding !== 'object') {
+            errors.push(`devBindings."${name}": must be an "owner:slug" string or an object { app }`);
+            continue;
+        }
+        if (binding.app == null) {
+            errors.push(`devBindings."${name}": needs "app" (the target app, for request())`);
+        } else if (typeof binding.app !== 'string' || !binding.app.trim()) {
+            errors.push(`devBindings."${name}".app: must be a non-empty string`);
+        }
+    }
+    return errors;
+}
+
+/**
+ * Normalize a devBindings entry to `{ app }`. A bare string is shorthand for
+ * `{ app }`. Every consumer of a binding — the `.d.ts` generator and the dev
+ * proxy alike — resolves `.app` from this result, never from the raw entry, so
+ * the string and object forms behave identically: a shorthand binding gets both
+ * generated types and a working request().
+ *
+ * @param {string|{app?: string}|null|undefined} binding
+ * @returns {{ app: string|null }}
+ */
+export function resolveAppBinding(binding) {
+    if (typeof binding === 'string') return { app: binding };
+    return { app: (binding && binding.app) || null };
+}
+
 /**
  * Build the dev-mode `context` object passed to server route handlers, so
  * `await context.myDep.method(...)` works the same locally as it does after
@@ -274,13 +349,28 @@ export function validateDependencies(deps) {
  * @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 }) {
+export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null }) {
     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;
 
+        // App slots bind from the plugin's `devBindings` (a human `owner:slug`
+        // pointing request() at the target app), falling back to the manifest
+        // `defaultBinding` UUID like every other target. request() is the only
+        // surface.
+        if (target === 'app') {
+            const fallback = (typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
+                ? decl.defaultBinding
+                : null;
+            const binding = devBindings[name] != null ? devBindings[name] : fallback;
+            context[name] = binding
+                ? makeAppDevProxy({ name, binding, appFetch })
+                : makeUnboundDevProxy({ name, target });
+            continue;
+        }
+
         const targetId = (typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
             ? decl.defaultBinding
             : null;
@@ -292,6 +382,94 @@ export function buildDevContext({ deps, apiFetch }) {
     return context;
 }
 
+/**
+ * Dev proxy for a `target: app` slot. `request()` is the only surface.
+ *
+ * Production runs `request()` through the target's own /view/_/ dispatch, and
+ * dev injects into the same route:
+ *
+ *   request(payload) -> /api/apps/<app>/view/_/<url>
+ *       The same route prod injects into, so the target's own handlers, authz
+ *       and roles run. This dispatch accepts only the token/session auth
+ *       strategies (not basic auth), so it uses `appFetch`: an INFORMER_APP_TOKEN
+ *       Bearer, or the INFORMER_API_KEY Bearer reused when the plugin already
+ *       runs in API-key mode. `appFetch` stamps `x-informer-app-depth: 1`, so the
+ *       target runs one hop deep and enforces the same one-hop guard as prod.
+ *       Non-JSON success responses follow the prod envelope contract: text/HTML
+ *       returns a text envelope; binary is rejected (dev can't emulate it yet).
+ *
+ * @param {Object} args
+ * @param {string} args.name - dependency slot name
+ * @param {string|{app?: string}} args.binding - devBindings entry (or the
+ *   manifest defaultBinding UUID). A bare string is shorthand for `{ app }`.
+ * @param {Function|null} args.appFetch - token-authed fetch, or null when
+ *   INFORMER_APP_TOKEN is unset.
+ */
+function makeAppDevProxy({ name, binding, appFetch }) {
+    const { app } = resolveAppBinding(binding);
+
+    return {
+        async request(payload) {
+            if (!app) {
+                throw new Error(
+                    `Dependency "${name}" (app): dev request() needs the target app — set devBindings.${name}.app (e.g. 'admin:kanban')`
+                );
+            }
+            if (!appFetch) {
+                throw new Error(
+                    `Dependency "${name}" (app): dev request() needs a Bearer credential — the target's /view/_/ dispatch does not accept basic auth. Run in API-key mode (INFORMER_API_KEY), or create a token (Admin → Tokens, or POST /api/tokens) and set INFORMER_APP_TOKEN in .env`
+                );
+            }
+            const { method = 'GET', url, params, data } = payload || {};
+            const httpMethod = String(method).toUpperCase();
+            if (!REQUEST_METHODS.includes(httpMethod)) {
+                throw new Error(`Dependency "${name}" (app): unsupported method "${method}"`);
+            }
+            if (!url || typeof url !== 'string') {
+                throw new Error(`Dependency "${name}" (app): request({ url }) requires the target route path`);
+            }
+            const path = url.replace(/^\/+/, '');
+            const search = params ? `?${new URLSearchParams(params).toString()}` : '';
+            // Path-traversal guard (mirrors entity-type/app.js): the path is
+            // interpolated into the target's /view/_/ dispatch and fetch resolves
+            // dot segments before the request lands, so `../../x` would escape the
+            // dispatch and reach arbitrary /api routes. Resolve it the way fetch
+            // will and confirm it still lives under the dispatch prefix.
+            const targetPrefix = `/api/apps/${encodeURIComponent(app)}/view/_/`;
+            let resolvedPath;
+            try {
+                resolvedPath = new URL(`${targetPrefix}${path}${search}`, 'http://localhost').pathname;
+            } catch {
+                throw new Error(`Dependency "${name}" (app): request({ url }) is malformed`);
+            }
+            if (!resolvedPath.startsWith(targetPrefix)) {
+                throw new Error(`Dependency "${name}" (app): request({ url }) must not escape the target app with ".." path segments`);
+            }
+            const { status, body, contentType } = await appFetch(
+                `apps/${encodeURIComponent(app)}/view/_/${path}${search}`,
+                { method: httpMethod, body: data }
+            );
+            if (status >= 400) {
+                throw dependencyCallError(name, 'app', status, body);
+            }
+            // Success-envelope contract mirrors entity-type/app.js: JSON → parsed
+            // body; non-JSON text/HTML → text envelope; binary → not emulatable
+            // via resp.text() without corruption, so fail loudly rather than
+            // silently hand back mangled bytes.
+            if (isBinaryContentType(contentType)) {
+                throw new Error(
+                    `Dependency "${name}" (app): the dev proxy can't return binary responses yet (upstream content-type "${contentType}"). Test binary endpoints against a deployed build.`
+                );
+            }
+            // (An empty content-type gets the text envelope too, matching prod.)
+            if (!(contentType || '').includes('json')) {
+                return { status, body, contentType: contentType || '', headers: { 'content-type': contentType || '' } };
+            }
+            return body;
+        }
+    };
+}
+
 function makeDevProxy({ name, target, targetId, apiFetch }) {
     switch (target) {
         case 'dataset':
@@ -335,29 +513,81 @@ function makeDevProxy({ name, target, targetId, apiFetch }) {
  */
 function makeUnboundDevProxy({ name, target }) {
     const methods = METHOD_SURFACE[target] || [];
+    // App slots bind via devBindings (a dev-local owner:slug) or a manifest
+    // defaultBinding UUID, so point at whichever the reader is likelier to want.
+    const hint = target === 'app'
+        ? `add \`devBindings: { ${name}: { app: '<owner:slug>' } }\` to the informer() plugin options in vite.config.js, or \`defaultBinding: <uuid>\` to its entry in informer.yaml`
+        : 'add `defaultBinding: <uuid>` to its entry in informer.yaml';
     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`
+            // Mirror the prod unbound-proxy contract (unbound-proxy.js): a 422
+            // with data.errorCode 'dependency_unbound', so guest code doing
+            // `catch (err) { if (err.data?.errorCode === 'dependency_unbound') }`
+            // fires in dev exactly as it does in production.
+            throw dependencyError(
+                `Dependency "${name}" is not bound in dev — ${hint}`,
+                422,
+                { errorCode: 'dependency_unbound', dependencyName: name, resourceType: target }
             );
         };
     }
     return proxy;
 }
 
+/**
+ * Build an Error carrying the same shape production reconstructs across the V8
+ * isolate boundary (see the invoke-script wrapper in app-sandbox.js): a numeric
+ * `statusCode`, a structured `data` (with `errorCode`), and the boom-style
+ * `output.payload.data` mirror. Guest code branches on `err.statusCode` and
+ * `err.data.errorCode`, so dev must attach the same fields or those branches
+ * silently never fire locally — the exact dev/prod drift this feature removes.
+ */
+function dependencyError(message, statusCode, data) {
+    const err = new Error(message);
+    err.statusCode = statusCode;
+    err.data = data;
+    err.output = { statusCode, payload: { statusCode, message, data } };
+    return err;
+}
+
+/**
+ * Shape a >=400 dev-proxy response into the prod boundary-error contract
+ * (unwrapInject in inject-helpers.js): the dependency name is baked into the
+ * message and `data` carries { errorCode, dependencyName, resourceType,
+ * upstreamStatus } — propagating any structured `errorCode` the upstream boom
+ * body already carried (e.g. a target app's own `dependency_unbound`).
+ */
+function dependencyCallError(depName, resourceType, status, responseBody) {
+    const isObj = responseBody && typeof responseBody === 'object';
+    const message = isObj && responseBody.message ? responseBody.message : String(status);
+    const data = {
+        errorCode: (isObj && responseBody.data && responseBody.data.errorCode) || null,
+        dependencyName: depName,
+        resourceType,
+        upstreamStatus: status
+    };
+    const err = dependencyError(`Dependency "${depName}" (${resourceType}): ${message}`, status, data);
+    err.body = responseBody;
+    return err;
+}
+
+/**
+ * Local mirror of inject-helpers.js isBinaryContentType (can't import across the
+ * package boundary). Text, JSON and SSE are safe to carry as strings; anything
+ * else is bytes that `resp.text()` would corrupt.
+ */
+function isBinaryContentType(contentType) {
+    const ct = (contentType || '').toLowerCase();
+    return Boolean(ct) && !ct.startsWith('text/') && !ct.includes('json') && !ct.includes('event-stream');
+}
+
 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;
+        throw dependencyCallError(depName, resourceType, status, responseBody);
     }
     return responseBody;
 }

package/src/index.js

@@ -1,13 +1,39 @@
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from './client.js';
-import { loadDependencies, validateDependencies } from './dev-dependencies.js';
+import { loadDependencies, validateDependencies, validateDevBindings, resolveAppBinding } from './dev-dependencies.js';
+import { buildDeclarations } from './openapi-to-dts.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';
 
+/**
+ * Write generated app-dependency type declarations under .informer/ and keep the
+ * directory out of git (idempotent).
+ */
+async function writeAppDepTypes (projectRoot, dts) {
+    const dir = resolve(projectRoot, '.informer');
+    await mkdir(dir, { recursive: true });
+    await writeFile(resolve(dir, 'app-deps.d.ts'), dts, 'utf8');
+
+    const giPath = resolve(projectRoot, '.gitignore');
+    let gi = '';
+    try {
+        gi = await readFile(giPath, 'utf8');
+    } catch (err) {
+        // Only a missing file is benign; a real read error (EACCES…) must not be
+        // swallowed, or we'd clobber the user's .gitignore with a single line.
+        if (err.code !== 'ENOENT') throw err;
+    }
+    const ignored = gi.split(/\r?\n/).some((l) => l.trim() === '.informer/' || l.trim() === '.informer');
+    if (!ignored) {
+        const sep = gi && !gi.endsWith('\n') ? '\n' : '';
+        await writeFile(giPath, `${gi}${sep}.informer/\n`, 'utf8');
+    }
+}
+
 /**
  * Vite plugin for local Informer App development.
  *
@@ -16,7 +42,12 @@ import { init, migrate } from './workspace.js';
  * - Injects window.__INFORMER__ context mock in dev mode
  * - Sets base to './' so built assets use relative paths
  *
- * @param {{ mock?: object }} options
+ * @param {Object} [options]
+ * @param {{ report?: object, theme?: 'light'|'dark', roles?: string[] }} [options.mock]
+ *   window.__INFORMER__ mock injected in dev.
+ * @param {Object} [options.devBindings] - dev bindings for `target: app` deps,
+ *   which can't be defaultBound in the manifest. See AppDevBinding in index.d.ts.
+ * @param {Object} [options.proxy] - extra Vite proxy options merged onto /api.
  * @returns {import('vite').Plugin}
  */
 export default function informer(options = {}) {
@@ -24,6 +55,11 @@ export default function informer(options = {}) {
     let authHeader = null;
     let serverOrigin = null;
     let devWorkspaceId = null;
+    // Optional separate credential for cross-app request() — the target's
+    // /view/_/ dispatch accepts only the token/session strategies, not basic
+    // auth. In API-key mode the INFORMER_API_KEY Bearer is reused instead, so
+    // this is only needed under basic auth (INFORMER_USER/PASS).
+    let appToken = null;
     let activeMode = null;
 
     return {
@@ -46,6 +82,7 @@ export default function informer(options = {}) {
                 const pass = process.env.INFORMER_PASS;
 
                 devWorkspaceId = process.env.INFORMER_DEV_WORKSPACE || null;
+                appToken = process.env.INFORMER_APP_TOKEN || null;
 
                 if (baseUrl) {
                     serverOrigin = baseUrl.replace(/\/+$/, '');
@@ -77,15 +114,18 @@ export default function informer(options = {}) {
             const projectRoot = process.cwd();
             const migrationsDir = resolve(projectRoot, 'migrations');
 
+            // One API client for the whole dev-server setup — createClient just
+            // builds an auth header (no I/O), so it's hoisted out of the two
+            // branches that each used to rebuild an identical one.
+            const api = createClient({
+                baseUrl: serverOrigin,
+                apiKey: process.env.INFORMER_API_KEY,
+                user: process.env.INFORMER_USER,
+                pass: process.env.INFORMER_PASS
+            });
+
             // Auto-provision workspace if migrations/ exists
             if (existsSync(migrationsDir)) {
-                const api = createClient({
-                    baseUrl: serverOrigin,
-                    apiKey: process.env.INFORMER_API_KEY,
-                    user: process.env.INFORMER_USER,
-                    pass: process.env.INFORMER_PASS
-                });
-
                 try {
                     // Verify existing workspace or create a new one
                     let needsInit = !devWorkspaceId;
@@ -120,17 +160,91 @@ export default function informer(options = {}) {
                 }
             }
 
+            // Read the manifest dependencies once for both consumers below —
+            // boot-time validation and app-dependency type generation (this
+            // used to parse informer.yaml twice). loadDependencies returns {}
+            // when there's no manifest and only throws on a malformed/unreadable
+            // one; the validators null-guard, so {} is a safe fallback.
+            let deps = {};
+            try {
+                deps = await loadDependencies(projectRoot);
+            } catch (err) {
+                console.warn(`[informer] Could not read informer.yaml dependencies: ${err.message}`);
+            }
+
             // 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.
+            for (const message of validateDependencies(deps)) {
+                console.error(`[informer] informer.yaml: ${message}`);
+            }
+            // Catch a typo'd or mis-targeted devBinding at boot rather than
+            // letting the first call report the slot as unbound.
+            for (const message of validateDevBindings(deps, options.devBindings || {})) {
+                console.error(`[informer] vite.config.js: ${message}`);
+            }
+
+            // Generate .d.ts types for bound `target: app` deps from their
+            // published OpenAPI docs, so server/ handlers get typed
+            // context.<slot>.request()/query() autocomplete.
             try {
-                const deps = await loadDependencies(projectRoot);
-                const errors = validateDependencies(deps);
-                for (const message of errors) {
-                    console.error(`[informer] informer.yaml: ${message}`);
+                // A bare string devBinding is shorthand for { app } — request()
+                // works under it, so its types must generate too, not just for
+                // the object form.
+                const boundAppRef = (name) =>
+                    resolveAppBinding(options.devBindings && options.devBindings[name]).app;
+                const appSlots = Object.entries(deps).filter(
+                    ([name, decl]) => decl && decl.target === 'app' && boundAppRef(name)
+                );
+                if (appSlots.length) {
+                    const specs = {};
+                    let transientFailure = false; // a slot we couldn't reach (vs. a definitive "no doc")
+                    for (const [name] of appSlots) {
+                        const appRef = boundAppRef(name);
+                        let spec;
+                        try {
+                            spec = await api.get(`apps/${appRef}/openapi.json`);
+                        } catch (err) {
+                            // 401/403 are as definitive as a 404 — the binding is
+                            // wrong or unshared, and retrying changes nothing, so
+                            // don't imply otherwise or mark the run transient.
+                            if (err.status === 401 || err.status === 403) {
+                                console.warn(`[informer] ${name}: ${appRef} returned ${err.status} — your credentials can't read that app; check the app ref and that it's shared with you`);
+                                continue;
+                            }
+                            // Network blip or a server-side failure: don't drop the
+                            // slot — preserve its last-good types below.
+                            transientFailure = true;
+                            console.warn(`[informer] ${name}: could not reach ${appRef} OpenAPI (${err.message}) — keeping existing types if present`);
+                            continue;
+                        }
+                        if (spec === null) {
+                            // 404: app ref not found, not shared with you, or a server older
+                            // than the openapi endpoint. A deploy doesn't fix any of these.
+                            console.warn(`[informer] ${name}: ${appRef} returned 404 — check the app ref exists and is shared with you (or the server predates /openapi.json)`);
+                            continue;
+                        }
+                        if (!spec.paths) {
+                            console.warn(`[informer] ${name}: ${appRef} has no server routes to type yet — deploy its server/ handlers`);
+                            continue;
+                        }
+                        specs[name] = spec;
+                    }
+                    const slotNames = Object.keys(specs);
+                    if (slotNames.length) {
+                        // A transient failure would otherwise rewrite the file without the
+                        // unreachable slot, making its types vanish on a network blip. If we
+                        // already have a generated file, keep it intact instead.
+                        if (transientFailure && existsSync(resolve(projectRoot, '.informer', 'app-deps.d.ts'))) {
+                            console.warn('[informer] some app dependencies were unreachable — keeping the last-good .informer/app-deps.d.ts');
+                        } else {
+                            await writeAppDepTypes(projectRoot, buildDeclarations(specs));
+                            console.log(`[informer] wrote app-dependency types → .informer/app-deps.d.ts (${slotNames.join(', ')})`);
+                        }
+                    }
                 }
             } catch (err) {
-                console.warn(`[informer] Could not validate informer.yaml dependencies: ${err.message}`);
+                console.warn(`[informer] app-dependency type generation skipped: ${err.message}`);
             }
 
             // Mount server-side route handlers if a server/ directory exists
@@ -142,7 +256,12 @@ export default function informer(options = {}) {
                     authHeader,
                     devWorkspaceId,
                     projectRoot,
-                    roles: (options.mock && options.mock.roles) || []
+                    roles: (options.mock && options.mock.roles) || [],
+                    // Dev-only bindings for `target: app` slots (override the
+                    // manifest defaultBinding for local dev). Shape:
+                    //   devBindings: { kanban: { app: 'admin:kanban' } }
+                    devBindings: options.devBindings || {},
+                    appToken
                 });
                 server.middlewares.use('/api/_server', serverRoutes);
             }
@@ -156,7 +275,9 @@ export default function informer(options = {}) {
                     serverOrigin,
                     authHeader,
                     devWorkspaceId,
-                    projectRoot
+                    projectRoot,
+                    devBindings: options.devBindings || {},
+                    appToken
                 });
                 server.middlewares.use('/api/_agent', agentDev);
             }

package/src/openapi-to-dts.js

@@ -0,0 +1,168 @@
+/**
+ * Generate TypeScript declarations for bound `target: app` dependencies from
+ * their published OpenAPI docs (GET /api/apps/<app>/openapi.json), so a
+ * consumer's server/ handlers get typed `context.<slot>.request()`
+ * autocomplete on the target app's routes, params, and response shapes.
+ *
+ * Pure — no I/O. `buildDeclarations({ slot: openapiDoc })` returns a `.d.ts` string.
+ */
+
+// A slot name → a PascalCase fragment safe to use in a TS identifier. Splits on
+// any non-alphanumeric run (so `a-b` and `a_b` both normalize the same way — the
+// caller disambiguates collisions), and guarantees the result starts with a
+// letter/underscore so a digit-leading slot (`2fa`) can't emit invalid TS.
+function pascalCase (s) {
+    const parts = String(s).split(/[^A-Za-z0-9]+/).filter(Boolean);
+    let id = parts.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+    if (!id) id = 'Slot';
+    if (!/^[A-Za-z_$]/.test(id)) id = '_' + id;
+    return id;
+}
+
+// A safe TS property key: bare identifier, or a quoted string otherwise.
+function tsKey (k) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+}
+
+// The JSON Schema subset an app declares → a TS type string.
+function jsonSchemaToTs (schema) {
+    if (!schema || typeof schema !== 'object') return 'any';
+    if (Array.isArray(schema.enum) && schema.enum.length) {
+        return schema.enum.map((v) => JSON.stringify(v)).join(' | ');
+    }
+    switch (schema.type) {
+        case 'string': return 'string';
+        case 'integer':
+        case 'number': return 'number';
+        case 'boolean': return 'boolean';
+        case 'null': return 'null';
+        case 'array': return `${jsonSchemaToTs(schema.items || {})}[]`;
+        default:
+            if (schema.properties) return objectType(schema);
+            return schema.type === 'object' ? 'Record<string, any>' : 'any';
+    }
+}
+
+function objectType (schema) {
+    const props = schema.properties || {};
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const keys = Object.keys(props);
+    if (!keys.length) return 'Record<string, any>';
+    const fields = keys.map((k) => `${tsKey(k)}${required.has(k) ? '' : '?'}: ${jsonSchemaToTs(props[k])}`);
+    return `{ ${fields.join('; ')} }`;
+}
+
+// OpenAPI path (/issues/{key}) → the `url` literal used in request({ url }).
+// The consumer passes a leading-slash-free path; `{param}` segments become
+// `${string}` template holes so an interpolated url still type-checks.
+function urlType (path) {
+    const rel = path.replace(/^\//, '');
+    if (!rel.includes('{')) return JSON.stringify(rel);
+    return '`' + rel.replace(/\{[^}]+\}/g, '${string}') + '`';
+}
+
+function queryParamsType (op) {
+    const params = (op.parameters || []).filter((p) => p.in === 'query');
+    if (!params.length) return null;
+    const fields = params.map((p) => `${tsKey(p.name)}${p.required ? '' : '?'}: ${jsonSchemaToTs(p.schema || {})}`);
+    return { type: `{ ${fields.join('; ')} }`, required: params.some((p) => p.required) };
+}
+
+function jsonSchemaOf (container) {
+    return container && container.content && container.content['application/json']
+        ? container.content['application/json'].schema
+        : undefined;
+}
+
+function requestOverload (method, path, op) {
+    const parts = [`method: ${JSON.stringify(method.toUpperCase())}`, `url: ${urlType(path)}`];
+
+    const q = queryParamsType(op);
+    if (q) parts.push(`params${q.required ? '' : '?'}: ${q.type}`);
+
+    const bodySchema = jsonSchemaOf(op.requestBody);
+    if (bodySchema) parts.push(`data: ${jsonSchemaToTs(bodySchema)}`);
+
+    const respSchema = op.responses && op.responses['200'] ? jsonSchemaOf(op.responses['200']) : undefined;
+    const ret = respSchema ? jsonSchemaToTs(respSchema) : 'any';
+
+    const summary = op.summary || op.description;
+    const doc = summary ? `    /** ${String(summary).replace(/\*\//g, '*\\/')} */\n` : '';
+    return `${doc}    request(opts: { ${parts.join('; ')} }): Promise<${ret}>;`;
+}
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+function slotInterface (iface, spec) {
+    const overloads = [];
+    for (const [path, item] of Object.entries(spec.paths || {})) {
+        for (const method of HTTP_METHODS) {
+            if (item[method]) overloads.push(requestOverload(method, path, item[method]));
+        }
+    }
+    // Escape hatch, listed last so the typed overloads win when they match. The
+    // shape mirrors what the runtime driver actually reads — { method, url,
+    // params, data } — no `headers`, which the driver ignores (entity-type/app.js).
+    overloads.push('    /** Escape hatch — any method/url (bypasses the typed contract). */');
+    overloads.push('    request(opts: { method?: string; url: string; params?: Record<string, unknown>; data?: unknown }): Promise<any>;');
+
+    return [
+        `export interface ${iface} {`,
+        overloads.join('\n'),
+        '}'
+    ].join('\n');
+}
+
+/**
+ * @param {Record<string, object>} specsBySlot - { slotName: openapiDoc }
+ * @returns {string} a `.d.ts` document
+ */
+export function buildDeclarations (specsBySlot) {
+    const interfaces = [];
+    const slotFields = [];
+    const usedIfaces = new Set();
+    for (const [slot, spec] of Object.entries(specsBySlot)) {
+        // Distinct slots can normalize to the same PascalCase (e.g. `a-b`/`a_b`);
+        // suffix on collision so TS doesn't silently merge the two interfaces.
+        const base = pascalCase(slot) + 'Api';
+        let iface = base;
+        for (let n = 2; usedIfaces.has(iface); n++) iface = `${base}_${n}`;
+        usedIfaces.add(iface);
+
+        interfaces.push(slotInterface(iface, spec));
+        slotFields.push(`    ${tsKey(slot)}: ${iface};`);
+    }
+
+    return `// AUTO-GENERATED by vite-plugin-informer — do not edit.
+// Typed from bound \`target: app\` dependencies' OpenAPI docs; regenerated on \`npm run dev\`.
+//
+// Use in a server/ handler. The import path is relative to the handler file —
+// add one ../ per directory below server/ (e.g. server/issues/index.js → ../../):
+//   /** @param {import('../../.informer/app-deps').HandlerBag} bag */
+//   export async function GET(bag) { const { context } = bag; /* context.<slot>.request(...) */ }
+
+${interfaces.join('\n\n')}
+
+export interface AppDependencies {
+${slotFields.join('\n')}
+}
+
+export interface HandlerBag {
+    context: AppDependencies & Record<string, any>;
+    request: {
+        method: string;
+        path: string;
+        query: Record<string, string>;
+        body: any;
+        params: Record<string, string>;
+        roles: string[];
+        user: any;
+        headers: Record<string, string>;
+    };
+    query(sql: string, params?: unknown[]): Promise<any[]>;
+    [key: string]: any;
+}
+`;
+}
+
+export const _internal = { jsonSchemaToTs, urlType, queryParamsType, pascalCase };

package/src/server-routes.js

@@ -5,6 +5,10 @@ import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDev
 
 const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
+// Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
+// hanging the handler.
+const FETCH_TIMEOUT_MS = 30000;
+
 // 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}$/;
@@ -144,10 +148,17 @@ async function walkJsFiles(dir, basePath) {
  * Create Connect middleware for dev-mode server route execution.
  *
  * @param {Object} viteServer - Vite dev server instance
- * @param {{ serverOrigin: string, authHeader: string, devWorkspaceId: string|null, projectRoot: string }} opts
+ * @param {Object} opts
+ * @param {string} opts.serverOrigin - Informer server origin
+ * @param {string} opts.authHeader - Basic or Bearer auth header for /api calls
+ * @param {string|null} opts.devWorkspaceId - workspace datasource id for query()
+ * @param {string} opts.projectRoot - app project root
+ * @param {string[]} [opts.roles] - dev user roles surfaced on request.roles
+ * @param {Object} [opts.devBindings] - dev bindings for `target: app` deps
+ * @param {string|null} [opts.appToken] - INFORMER_APP_TOKEN for cross-app request()
  * @returns {Function} Connect middleware
  */
-export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles }) {
+export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles, devBindings, appToken }) {
     const serverDir = join(projectRoot, 'server');
 
     // query() implementation — proxies to the workspace _sql endpoint
@@ -173,30 +184,65 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
     }
 
     // fetch() implementation — proxies API calls to the Informer server
-    async function apiFetch(path, opts = {}) {
+    async function fetchAs(auth, path, opts = {}) {
         const method = (opts.method || 'GET').toUpperCase();
         // 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)}` } };
+            return { status: 400, body: { error: `Invalid fetch path: ${String(path).slice(0, 80)}` }, contentType: 'application/json' };
         }
         const url = `${serverOrigin}${apiPath}`;
         const fetchOpts = {
             method,
-            headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
+            headers: { Authorization: auth, 'Content-Type': 'application/json', ...(opts.headers || {}) }
         };
 
-        if (opts.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+        if (opts.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
             fetchOpts.body = JSON.stringify(opts.body);
         }
 
-        const resp = await globalThis.fetch(url, fetchOpts);
+        // Read the stream exactly once — `.json()` consumes/locks the body, so a
+        // `.text()` fallback would throw "Body is unusable" on any non-JSON
+        // response (auth-bounce HTML, proxy error page). Parse in memory
+        // instead — same as prod's unwrapInject.
+        let status, contentType, text;
+        try {
+            const resp = await globalThis.fetch(url, { ...fetchOpts, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            status = resp.status;
+            contentType = resp.headers.get('content-type') || '';
+            text = await resp.text();
+        } catch (err) {
+            // Transport failure or timeout — fetch throws (TypeError 'fetch failed'
+            // with the real reason on err.cause, or a TimeoutError). Return a
+            // synthetic 502 so the dependency layer names it (dep + url + cause)
+            // rather than a bare unhandled "fetch failed".
+            const reason = (err.cause && err.cause.message) || err.message;
+            return { status: 502, body: { message: `fetch to ${url} failed: ${reason}` }, contentType: 'application/json' };
+        }
         let body;
-        try { body = await resp.json(); } catch { body = await resp.text(); }
-        return { status: resp.status, body };
+        try { body = JSON.parse(text); } catch { body = text; }
+        return { status, body, contentType };
     }
 
+    async function apiFetch(path, opts = {}) {
+        return await fetchAs(authHeader, path, opts);
+    }
+
+    // Cross-app request() targets /api/apps/<id>/view/_/<path>, whose auth accepts
+    // only the token/session strategies — NOT basic auth. In API-key mode the
+    // INFORMER_API_KEY Bearer already satisfies that, so reuse it; under basic
+    // auth a separate API token (INFORMER_APP_TOKEN) is required, and without one
+    // the app proxy's request() throws a pointed error instead of a bare 401.
+    // appFetch also stamps x-informer-app-depth:1 so the target runs one hop deep
+    // and enforces the same one-hop guard it does in production.
+    const appAuth = appToken
+        ? `Bearer ${appToken}`
+        : (authHeader && authHeader.startsWith('Bearer ') ? authHeader : null);
+    const appFetch = appAuth
+        ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
+        : null;
+
     return async function serverRoutesMiddleware(req, res, next) {
         try {
             // The URL has already had /api/_server stripped by Vite's middleware.use()
@@ -307,7 +353,7 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
             // 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 context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
             const env = await loadAppEnv(projectRoot);
 
             // Call handler — bag mirrors the prod sandbox (see app-sandbox.js).