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

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