@entrinsik/vite-plugin-informer 2.1.0 → 2.3.0

package/bin/init.js

@@ -8,141 +8,59 @@ import { randomUUID } from 'node:crypto';
 const cwd = process.cwd();
 
 /**
- * Generate the default data-access.yaml content with helpful comments
+ * Generate the default informer.yaml content with helpful comments
  */
-function generateDataAccessYaml() {
-    return `# Data Access Configuration
-# ========================
-# This file controls which Informer APIs your report can access.
-# Without this file, all API access is blocked (secure by default).
+function generateInformerYaml() {
+    return `# Informer App Configuration
+# =========================
+# This file controls which Informer APIs your app can access and defines
+# custom roles for role-based UIs.
 #
-# Documentation: https://docs.entrinsik.com/informer/magic-reports/data-access
+# Without an access section, all API access is blocked (secure by default).
 
 # ============================================================================
-# DATASETS
+# DATA ACCESS
 # ============================================================================
-# Grant access to dataset search and field metadata.
-# Each entry generates:
-#   - POST /api/datasets/{id}/_search
-#   - GET /api/datasets/{id}/fields
+# The access section controls which APIs the app can call when shared.
 #
-# Simple access (full dataset):
+# access:
 #   datasets:
-#     - admin:sales-data
-#     - admin:customers
-#
-# With row-level security (filter injected server-side):
-#   datasets:
-#     - id: admin:orders
+#     - admin:sales-data             # Full dataset access
+#     - id: admin:orders             # With row-level security
 #       filter:
-#         region: $user.custom.region      # User only sees their region
-#         sales_rep: $user.username        # User only sees their own records
-#
-datasets: []
-
-# ============================================================================
-# QUERIES
-# ============================================================================
-# Grant access to execute saved queries.
-# Each entry generates:
-#   - POST /api/queries/{id}/_execute
+#         region: $user.custom.region
 #
-# Example:
 #   queries:
-#     - admin:daily-summary
-#     - admin:monthly-report
-#
-queries: []
-
-# ============================================================================
-# INTEGRATIONS
-# ============================================================================
-# Grant access to make requests through integrations (Salesforce, REST APIs, etc.)
-# Each entry generates:
-#   - POST /api/integrations/{id}/request
+#     - admin:monthly-summary
 #
-# Simple access:
 #   integrations:
 #     - salesforce
-#     - quickbooks
-#
-# With credential injection (headers/params expanded server-side, never exposed to JS):
-#   integrations:
-#     - id: partner-api
-#       headers:
-#         Authorization: Bearer $user.custom.partnerToken
-#         X-Client-ID: $tenant.id
-#       params:
-#         user_id: $user.custom.externalId
-#
-# With path restrictions (only allow specific endpoints):
-#   integrations:
-#     - id: salesforce
-#       paths:
-#         - /data/*/query
-#         - /data/*/sobjects/*
-#
-integrations: []
-
-# ============================================================================
-# DATASOURCES
-# ============================================================================
-# Grant access to run SQL queries against datasources.
-# Each entry generates:
-#   - POST /api/datasources/{id}/_query
 #
-# Example:
 #   datasources:
 #     - postgres-main
-#     - mysql-analytics
-#
-datasources: []
-
-# ============================================================================
-# LIBRARIES
-# ============================================================================
-# Grant access to read files from other libraries.
-# Each entry generates:
-#   - GET /api/libraries/{id}/contents/*
-#
-# Example:
-#   libraries:
-#     - admin:shared-assets
-#     - admin:common-templates
-#
-libraries: []
-
-# ============================================================================
-# RAW API ACCESS (Advanced)
-# ============================================================================
-# For edge cases not covered by resource types above.
-# Specify exact method and path.
 #
-# Example:
-#   apis:
+#   apis:                            # Raw API paths (advanced)
 #     - POST /api/custom/endpoint
-#     - GET /api/special/resource
-#
-apis: []
+
+access:
+  datasets: []
+  queries: []
+  integrations: []
 
 # ============================================================================
-# VARIABLE REFERENCE
+# ROLES (optional)
 # ============================================================================
-# Variables are expanded server-side, keeping sensitive values secure.
-#
-# User variables:
-#   $user.username      - Login name
-#   $user.email         - Email address
-#   $user.displayName   - Full name (e.g., "John Smith")
-#   $user.custom.xxx    - Custom user field value
-#
-# Tenant variables:
-#   $tenant.id          - Tenant identifier
-#
-# Report variables:
-#   $report.id          - Report UUID
-#   $report.name        - Report display name
+# Define custom roles that publishers assign when sharing the app.
+# Roles are available in client code via window.__INFORMER__.roles
+# and in server handlers via request.roles.
 #
+# roles:
+#   - id: viewer
+#     name: Viewer
+#     description: Can view reports but not take actions
+#   - id: approver
+#     name: Approver
+#     description: Can approve or reject requests
 `;
 }
 
@@ -187,7 +105,7 @@ function packageNameToDisplayName(name) {
 }
 
 async function init() {
-    console.log('Initializing Informer Magic Report project...\n');
+    console.log('Initializing Informer App project...\n');
 
     // 1. Check for package.json
     const pkgPath = resolve(cwd, 'package.json');
@@ -210,9 +128,9 @@ async function init() {
     // 3. Get report info from user
     const defaultName = pkg.informer?.name || packageNameToDisplayName(pkg.name || basename(cwd));
 
-    console.log('Configure your Magic Report:\n');
+    console.log('Configure your app:\n');
 
-    const reportName = await prompt('Report name', defaultName);
+    const reportName = await prompt('App name', defaultName);
 
     console.log('');
 
@@ -276,11 +194,11 @@ INFORMER_API_KEY=your-api-key
         console.log('Created .env (update with your credentials)');
     }
 
-    // 9. Create data-access.yaml if it doesn't exist
-    const dataAccessPath = resolve(cwd, 'data-access.yaml');
-    if (!await exists(dataAccessPath)) {
-        await writeFile(dataAccessPath, generateDataAccessYaml());
-        console.log('Created data-access.yaml (configure API access for your report)');
+    // 9. Create informer.yaml if it doesn't exist
+    const informerYamlPath = resolve(cwd, 'informer.yaml');
+    if (!await exists(informerYamlPath)) {
+        await writeFile(informerYamlPath, generateInformerYaml());
+        console.log('Created informer.yaml (configure API access and roles)');
     }
 
     // 10. Add .env to .gitignore if not present
@@ -289,11 +207,9 @@ 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 data-access.yaml with the datasets/APIs your report needs');
+    console.log('  2. Update informer.yaml with the datasets/APIs your app needs');
     console.log('  3. Run: npm install');
     console.log('  4. Run: npm run dev');
-    console.log('  5. Install the Claude skill: /plugin marketplace add entrinsik-org/claude-plugins');
-    console.log('  6. Then: /plugin install magic-reports@entrinsik-plugins');
     console.log('');
 }
 

package/package.json

@@ -1,46 +1,47 @@
 {
-  "name": "@entrinsik/vite-plugin-informer",
-  "version": "2.1.0",
-  "description": "Vite plugin and publish tool for local Magic Report development",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/entrinsik-org/i5.git",
-    "directory": "packages/vite-plugin-informer"
-  },
-  "publishConfig": {
-    "registry": "https://docker.entrinsik.com/repository/entNPM/"
-  },
-  "author": "Entrinsik Inc.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "types": "index.d.ts",
-  "main": "./src/index.js",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./src/index.js"
+    "name": "@entrinsik/vite-plugin-informer",
+    "version": "2.3.0",
+    "description": "Vite plugin and deploy tool for Informer App development",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/entrinsik-org/i5.git",
+        "directory": "packages/vite-plugin-informer"
     },
-    "./deploy": "./src/deploy.js",
-    "./workspace": "./src/workspace.js"
-  },
-  "bin": {
-    "informer-deploy": "./bin/deploy.js",
-    "informer-init": "./bin/init.js",
-    "informer-workspace": "./bin/workspace.js",
-    "create-magic-report": "./bin/init.js"
-  },
-  "files": [
-    "src",
-    "bin",
-    "index.d.ts"
-  ],
-  "peerDependencies": {
-    "vite": ">=5.0.0"
-  },
-  "dependencies": {
-    "dotenv": "16.6.1"
-  }
+    "publishConfig": {
+        "registry": "https://docker.entrinsik.com/repository/entNPM/"
+    },
+    "author": "Entrinsik Inc.",
+    "license": "UNLICENSED",
+    "type": "module",
+    "types": "index.d.ts",
+    "main": "./src/index.js",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./src/index.js"
+        },
+        "./deploy": "./src/deploy.js",
+        "./workspace": "./src/workspace.js"
+    },
+    "bin": {
+        "informer-deploy": "./bin/deploy.js",
+        "informer-init": "./bin/init.js",
+        "informer-workspace": "./bin/workspace.js",
+        "create-magic-report": "./bin/init.js"
+    },
+    "files": [
+        "src",
+        "bin",
+        "index.d.ts"
+    ],
+    "peerDependencies": {
+        "vite": ">=5.0.0"
+    },
+    "dependencies": {
+        "dotenv": "16.6.1",
+        "yaml": "^2.7.0"
+    }
 }

package/src/agent-dev.js

@@ -0,0 +1,422 @@
+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';
+const parseYaml = yaml.parse;
+
+const MAX_STEPS = 20;
+
+/**
+ * Read and parse informer.yaml from the project root.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Object|null>} Parsed YAML or null
+ */
+async function loadInformerYaml(projectRoot) {
+    const yamlPath = join(projectRoot, 'informer.yaml');
+    try {
+        await access(yamlPath);
+        const content = await readFile(yamlPath, 'utf8');
+        return parseYaml(content);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Scan the tools/ directory for .js files that export a handler.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{ name: string, filePath: string }>>}
+ */
+async function scanLocalTools(projectRoot) {
+    const toolsDir = join(projectRoot, 'tools');
+    try {
+        await access(toolsDir);
+    } catch {
+        return [];
+    }
+
+    const tools = [];
+    await walkToolFiles(toolsDir, 'tools', tools);
+    return tools;
+}
+
+async function walkToolFiles(dir, basePath, results) {
+    let items;
+    try {
+        items = await readdir(dir);
+    } catch {
+        return;
+    }
+
+    for (const item of items) {
+        const full = join(dir, item);
+        const childPath = `${basePath}/${item}`;
+        const s = await stat(full);
+
+        if (s.isDirectory()) {
+            await walkToolFiles(full, childPath, results);
+        } else if (item.endsWith('.js')) {
+            const name = childPath
+                .replace(/^tools\//, '')
+                .replace(/\.js$/, '')
+                .replace(/\//g, '_');
+            results.push({ name, filePath: full });
+        }
+    }
+}
+
+/**
+ * Read an SSE stream from a fetch response, collecting text and tool calls.
+ *
+ * @param {Response} response - Fetch response with SSE body
+ * @returns {Promise<{ text: string, toolCalls: Array<{ id: string, name: string, input: Object }>, usage: Object }>}
+ */
+async function readSSE(response) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let text = '';
+    const toolCalls = [];
+    const pendingInputs = new Map(); // toolCallId -> partial JSON string
+    let usage = {};
+
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+
+        for (const line of lines) {
+            if (!line.startsWith('data: ')) continue;
+            const payload = line.slice(6);
+            if (payload === '[DONE]') break;
+
+            try {
+                const event = JSON.parse(payload);
+                switch (event.type) {
+                    case 'text-delta':
+                        text += event.delta;
+                        break;
+                    case 'tool-input-start':
+                        pendingInputs.set(event.toolCallId, '');
+                        break;
+                    case 'tool-input-delta':
+                        if (pendingInputs.has(event.toolCallId)) {
+                            pendingInputs.set(
+                                event.toolCallId,
+                                pendingInputs.get(event.toolCallId) + event.inputTextDelta
+                            );
+                        }
+                        break;
+                    case 'tool-input-available':
+                        toolCalls.push({
+                            id: event.toolCallId,
+                            name: event.toolName,
+                            input: event.input || {}
+                        });
+                        pendingInputs.delete(event.toolCallId);
+                        break;
+                    case 'finish-step':
+                        if (event.usage) usage = event.usage;
+                        break;
+                }
+            } catch {
+                // Skip malformed SSE events
+            }
+        }
+    }
+
+    return { text, toolCalls, usage };
+}
+
+/**
+ * Create Connect middleware for local agent development.
+ *
+ * Provides:
+ *   GET  /api/_agent          → list agents from informer.yaml
+ *   POST /api/_agent/:name/_trigger → run agent locally with tool dispatch
+ *
+ * @param {Object} viteServer - Vite dev server instance
+ * @param {Object} opts - Configuration
+ * @returns {Function} Connect middleware
+ */
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot }) {
+
+    // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
+    async function query(sql, params) {
+        if (!devWorkspaceId) {
+            throw new Error('query() requires INFORMER_DEV_WORKSPACE. Run: npx informer-workspace init');
+        }
+
+        const resp = await globalThis.fetch(`${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: authHeader },
+            body: JSON.stringify({ sql, params: params || [] })
+        });
+
+        if (!resp.ok) {
+            const err = await resp.json().catch(() => ({}));
+            throw new Error(`query() failed: ${resp.status} ${err.message || resp.statusText}`);
+        }
+
+        const data = await resp.json();
+        return data.rows;
+    }
+
+    // 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\/)?/, '')}`;
+        const fetchOpts = {
+            method,
+            headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
+        };
+
+        if (opts.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            fetchOpts.body = JSON.stringify(opts.body);
+        }
+
+        const resp = await globalThis.fetch(url, fetchOpts);
+        let body;
+        try { body = await resp.json(); } catch { body = await resp.text(); }
+        return { status: resp.status, body };
+    }
+
+    // emit() — no-op in dev mode (logs to console)
+    function emit(event, payload) {
+        console.log(`[agent-dev] emit("${event}",`, JSON.stringify(payload), ')');
+        return { ok: true };
+    }
+
+    return async function agentDevMiddleware(req, res, next) {
+        try {
+            const parsed = parseUrl(req.url, true);
+            const routePath = parsed.pathname || '/';
+
+            // GET / → list agents
+            if (req.method === 'GET' && (routePath === '/' || routePath === '')) {
+                const yaml = await loadInformerYaml(projectRoot);
+                const agents = yaml && yaml.agents ? Object.entries(yaml.agents).map(([name, def]) => ({
+                    name,
+                    description: def.description || null,
+                    model: def.model || 'go_everyday',
+                    tools: def.tools || [],
+                    on: def.on || []
+                })) : [];
+
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify(agents));
+                return;
+            }
+
+            // POST /:name/_trigger → run agent
+            const triggerMatch = routePath.match(/^\/([^/]+)\/_trigger$/);
+            if (req.method === 'POST' && triggerMatch) {
+                const agentName = decodeURIComponent(triggerMatch[1]);
+
+                // Read request body
+                const chunks = [];
+                for await (const chunk of req) {
+                    chunks.push(chunk);
+                }
+                const rawBody = Buffer.concat(chunks).toString('utf8');
+                let body = {};
+                if (rawBody) {
+                    try { body = JSON.parse(rawBody); } catch { body = {}; }
+                }
+
+                const triggerEvent = {
+                    event: body.event || '_manual',
+                    payload: body.payload || {}
+                };
+
+                // Load agent definition
+                const yaml = await loadInformerYaml(projectRoot);
+                if (!yaml || !yaml.agents || !yaml.agents[agentName]) {
+                    res.statusCode = 404;
+                    res.setHeader('Content-Type', 'application/json');
+                    res.end(JSON.stringify({ error: `Agent "${agentName}" not found in informer.yaml` }));
+                    return;
+                }
+
+                const agentDef = yaml.agents[agentName];
+                const model = agentDef.model || 'go_everyday';
+                const instructions = agentDef.instructions || '';
+                const agentToolNames = agentDef.tools || [];
+
+                // Load tool handlers via ssrLoadModule
+                const localTools = await scanLocalTools(projectRoot);
+                const toolMap = new Map(localTools.map(t => [t.name, t]));
+
+                const loadedTools = {};
+                for (const toolName of agentToolNames) {
+                    const tool = toolMap.get(toolName);
+                    if (!tool) {
+                        console.warn(`[agent-dev] Tool "${toolName}" not found in tools/`);
+                        continue;
+                    }
+
+                    const mod = await viteServer.ssrLoadModule(tool.filePath);
+                    if (typeof mod.handler !== 'function') {
+                        console.warn(`[agent-dev] Tool "${toolName}" has no handler export`);
+                        continue;
+                    }
+
+                    loadedTools[toolName] = {
+                        handler: mod.handler,
+                        description: mod.description || `Tool: ${toolName}`,
+                        schema: mod.schema || { type: 'object', properties: {} }
+                    };
+                }
+
+                // Build AI SDK tool definitions for _chat
+                const chatTools = {};
+                for (const [name, tool] of Object.entries(loadedTools)) {
+                    // Ensure schema always has type: 'object' at top level (Anthropic API requires it)
+                    const schema = tool.schema || {};
+                    chatTools[name] = {
+                        description: tool.description,
+                        inputSchema: {
+                            type: 'object',
+                            ...schema
+                        }
+                    };
+                }
+
+                // Run the AI loop
+                console.log(`[agent-dev] Triggering "${agentName}" (model: ${model}, tools: ${Object.keys(loadedTools).join(', ')})`);
+                for (const [name, def] of Object.entries(chatTools)) {
+                    console.log(`[agent-dev] Tool "${name}" schema:`, JSON.stringify(def.inputSchema));
+                }
+
+                const messages = [
+                    {
+                        role: 'user',
+                        parts: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                event: triggerEvent.event,
+                                payload: triggerEvent.payload,
+                                timestamp: new Date().toISOString()
+                            })
+                        }]
+                    }
+                ];
+
+                const steps = [];
+                let totalTokens = 0;
+
+                for (let step = 0; step < MAX_STEPS; step++) {
+                    // Call the AI model
+                    const chatResp = await globalThis.fetch(`${serverOrigin}/api/models/${model}/_chat`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json', Authorization: authHeader },
+                        body: JSON.stringify({
+                            messages,
+                            system: instructions,
+                            tools: Object.keys(chatTools).length > 0 ? chatTools : undefined,
+                            webSearch: !!agentDef.webSearch,
+                            maxSteps: 1
+                        })
+                    });
+
+                    if (!chatResp.ok) {
+                        const err = await chatResp.json().catch(() => ({}));
+                        throw new Error(`Model call failed: ${chatResp.status} ${err.message || chatResp.statusText}`);
+                    }
+
+                    const { text, toolCalls, usage } = await readSSE(chatResp);
+                    totalTokens += (usage.promptTokens || 0) + (usage.completionTokens || 0);
+
+                    // No tool calls — model is done
+                    if (toolCalls.length === 0) {
+                        if (text) {
+                            steps.push({ type: 'text', text });
+                            console.log(`[agent-dev] Step ${step}: text response (${text.length} chars)`);
+                        }
+                        break;
+                    }
+
+                    // Execute tool calls locally
+                    const assistantParts = [];
+                    if (text) {
+                        assistantParts.push({ type: 'text', text });
+                    }
+
+                    const toolResultParts = [];
+
+                    for (const tc of toolCalls) {
+                        console.log(`[agent-dev] Step ${step}: calling tool "${tc.name}"`, JSON.stringify(tc.input));
+
+                        assistantParts.push({
+                            type: 'tool-invocation',
+                            toolCallId: tc.id,
+                            toolName: tc.name,
+                            args: tc.input,
+                            state: 'result'
+                        });
+
+                        const tool = loadedTools[tc.name];
+                        let result;
+
+                        if (tool) {
+                            try {
+                                result = await tool.handler(tc.input, { query, fetch: apiFetch, emit, context: triggerEvent });
+                            } catch (err) {
+                                console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
+                                result = { error: err.message };
+                            }
+                        } else {
+                            result = { error: `Unknown tool: ${tc.name}` };
+                        }
+
+                        console.log(`[agent-dev]   → result:`, JSON.stringify(result).slice(0, 200));
+
+                        toolResultParts.push({
+                            type: 'tool-result',
+                            toolCallId: tc.id,
+                            toolName: tc.name,
+                            result: JSON.stringify(result)
+                        });
+
+                        steps.push({
+                            type: 'tool_call',
+                            toolCalls: [{ name: tc.name, args: tc.input, result }]
+                        });
+                    }
+
+                    // Append assistant message with tool invocations + tool results
+                    messages.push({ role: 'assistant', parts: assistantParts });
+                    messages.push({ role: 'tool', parts: toolResultParts });
+                }
+
+                const runResult = {
+                    agent: agentName,
+                    trigger: triggerEvent.event,
+                    status: 'completed',
+                    tokens: totalTokens,
+                    steps
+                };
+
+                console.log(`[agent-dev] Agent "${agentName}" completed: ${steps.length} steps, ${totalTokens} tokens`);
+
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify(runResult));
+                return;
+            }
+
+            next();
+        } catch (err) {
+            console.error('[agent-dev]', err);
+            res.statusCode = 500;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ error: err.message }));
+        }
+    };
+}

package/src/deploy.js

@@ -14,7 +14,7 @@ const CHUNK_THRESHOLD = 512 * 1024; // 512KB
 const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
 
 /**
- * Deploy a built Vite project to Informer as an App (or legacy Magic Report).
+ * Deploy a built Vite project to Informer as an App.
  *
  * Tries the new /api/apps endpoint first. If the server doesn't support it,
  * falls back to the legacy /api/reports endpoint transparently.
@@ -149,7 +149,7 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         }
     }
 
-    // 7. Upload config files from project root (e.g., data-access.yaml)
+    // 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) {
@@ -188,20 +188,115 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         // No migrations directory, skip
     }
 
-    // 9. Run migrations (if the server supports it)
+    // 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 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++;
+        }
+    } catch {
+        // No webhooks directory, skip
+    }
+
+    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + tools + agents
     if (apiPrefix === 'apps') {
         try {
-            const result = await api.post(`${entityPath}/_migrate`);
-            if (result && result.migrated && result.migrated.length > 0) {
-                console.log(`Ran ${result.migrated.length} migration(s): ${result.migrated.join(', ')}`);
+            console.log('Deploying...');
+            const result = await api.post(`${entityPath}/_deploy`);
+            if (result) {
+                if (result.migrated && result.migrated.length > 0) {
+                    console.log(`  Ran ${result.migrated.length} migration(s): ${result.migrated.join(', ')}`);
+                }
+                if (result.routes && result.routes.length > 0) {
+                    console.log(`  Registered ${result.routes.length} server route(s):`);
+                    for (const r of result.routes) {
+                        console.log(`    ${r}`);
+                    }
+                }
+                if (result.webhooks && result.webhooks.length > 0) {
+                    console.log(`  Registered ${result.webhooks.length} webhook(s):`);
+                    for (const r of result.webhooks) {
+                        console.log(`    ${r}`);
+                    }
+                }
+                if (result.tools && result.tools.length > 0) {
+                    console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
+                }
+                if (result.agents && result.agents.length > 0) {
+                    console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
+                }
+            }
+        } catch (err) {
+            if (err.status === 404) {
+                // Server may not support _deploy yet — ignore
+            } else {
+                const detail = err.body || err.message;
+                console.error(`  Deploy failed: ${detail}`);
             }
-        } catch {
-            // Server may not support _migrate yet — ignore
         }
     }
 
-    // 9. Print URL and return UUID for saving
-    const totalFiles = entries.length + configCount + migrationsCount;
+    // 13. Print URL and return UUID for saving
+    const totalFiles = entries.length + configCount + migrationsCount + toolsCount + serverCount + webhooksCount;
     const base = baseUrl.replace(/\/+$/, '');
     const entityUrl = apiPrefix === 'apps'
         ? `${base}/api/apps/${naturalId}/view`

package/src/index.js

@@ -1,10 +1,17 @@
 import dotenv from 'dotenv';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createClient } from './client.js';
+import { createMiddleware as createServerRoutes } from './server-routes.js';
+import { createAgentMiddleware } from './agent-dev.js';
+import { init, migrate } from './workspace.js';
 
 /**
- * Vite plugin for local Magic Report development.
+ * Vite plugin for local Informer App development.
  *
  * - Proxies /api requests to the Informer server with Basic auth
- * - Rewrites /api/_query to the dev workspace's _sql route (if configured)
+ * - Runs server/ route handlers locally via ssrLoadModule (if server/ dir exists)
  * - Injects window.__INFORMER__ context mock in dev mode
  * - Sets base to './' so built assets use relative paths
  *
@@ -60,43 +67,83 @@ export default function informer(options = {}) {
             return cfg;
         },
 
-        configureServer(server) {
-            if (!isDev || !devWorkspaceId || !serverOrigin) return;
+        async configureServer(server) {
+            if (!isDev || !serverOrigin) return;
 
-            // Intercept POST /api/_query and proxy to the dev workspace's _sql route.
-            // This middleware runs before the generic /api proxy, so the rewrite takes effect.
-            server.middlewares.use('/api/_query', async (req, res, next) => {
-                if (req.method !== 'POST') return next();
+            const projectRoot = process.cwd();
+            const migrationsDir = resolve(projectRoot, 'migrations');
 
-                // Read request body
-                const chunks = [];
-                for await (const chunk of req) {
-                    chunks.push(chunk);
-                }
-                const body = Buffer.concat(chunks).toString('utf8');
+            // 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
+                });
 
-                // Forward to workspace _sql endpoint
-                const url = `${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`;
                 try {
-                    const upstream = await fetch(url, {
-                        method: 'POST',
-                        headers: {
-                            'Content-Type': 'application/json',
-                            Authorization: authHeader
-                        },
-                        body
-                    });
-
-                    res.statusCode = upstream.status;
-                    res.setHeader('Content-Type', 'application/json');
-                    const text = await upstream.text();
-                    res.end(text);
+                    // Verify existing workspace or create a new one
+                    let needsInit = !devWorkspaceId;
+                    if (devWorkspaceId) {
+                        const ds = await api.get(`datasources/${devWorkspaceId}`);
+                        if (ds) {
+                            await migrate({ api, workspaceId: devWorkspaceId, migrationsDir });
+                        } else {
+                            console.warn(`[informer] Workspace ${devWorkspaceId} not found on server. Re-creating...`);
+                            needsInit = true;
+                        }
+                    }
+
+                    if (needsInit) {
+                        const pkg = JSON.parse(await readFile(resolve(projectRoot, 'package.json'), 'utf8'));
+                        let slug = pkg.name;
+                        if (slug && slug.startsWith('@') && slug.includes('/')) {
+                            slug = slug.split('/')[1];
+                        }
+
+                        const result = await init({
+                            api,
+                            slug,
+                            migrationsDir,
+                            envPath: resolve(projectRoot, '.env')
+                        });
+                        devWorkspaceId = result.workspaceId;
+                    }
                 } catch (err) {
-                    res.statusCode = 502;
-                    res.setHeader('Content-Type', 'application/json');
-                    res.end(JSON.stringify({ error: err.message }));
+                    console.warn(`[informer] Workspace setup failed: ${err.message}`);
+                    console.warn('[informer] query() will not work. Run: npx informer-workspace init');
                 }
-            });
+            }
+
+            // Mount server-side route handlers if a server/ directory exists
+            const serverDir = resolve(projectRoot, 'server');
+
+            if (existsSync(serverDir)) {
+                const serverRoutes = createServerRoutes(server, {
+                    serverOrigin,
+                    authHeader,
+                    devWorkspaceId,
+                    projectRoot,
+                    roles: (options.mock && options.mock.roles) || []
+                });
+                server.middlewares.use('/api/_server', serverRoutes);
+            }
+
+            // Mount agent dev middleware if tools/ or informer.yaml agents exist
+            const toolsDir = resolve(projectRoot, 'tools');
+            const yamlPath = resolve(projectRoot, 'informer.yaml');
+
+            if (existsSync(toolsDir) || existsSync(yamlPath)) {
+                const agentDev = createAgentMiddleware(server, {
+                    serverOrigin,
+                    authHeader,
+                    devWorkspaceId,
+                    projectRoot
+                });
+                server.middlewares.use('/api/_agent', agentDev);
+            }
+
         },
 
         transformIndexHtml: {

package/src/server-routes.js

@@ -0,0 +1,312 @@
+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';
+
+const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * Convert a file path under server/ to a route path.
+ *
+ * Examples:
+ *   server/orders/index.js     -> /orders
+ *   server/orders/[id].js      -> /orders/:id
+ *   server/orders/[id]/approve.js -> /orders/:id/approve
+ *   server/index.js            -> /
+ */
+function filePathToRoute(filePath) {
+    let route = filePath
+        .replace(/^server\//, '')
+        .replace(/\.js$/, '');
+
+    route = route.replace(/\[([^\]]+)\]/g, ':$1');
+
+    route = route.replace(/\/index$/, '');
+
+    if (route === 'index' || route === '') {
+        return '/';
+    }
+
+    if (!route.startsWith('/')) {
+        route = '/' + route;
+    }
+
+    if (route.length > 1 && route.endsWith('/')) {
+        route = route.slice(0, -1);
+    }
+
+    return route;
+}
+
+/**
+ * Match an incoming request against a route table.
+ *
+ * @param {Array<{ method: string, path: string }>} routes
+ * @param {string} method - HTTP method
+ * @param {string} requestPath - e.g. "/orders/123"
+ * @returns {{ route: Object, params: Object }|null}
+ */
+function matchRoute(routes, method, requestPath) {
+    const upperMethod = method.toUpperCase();
+    const candidates = routes.filter(r => r.method === upperMethod);
+
+    const normalizedPath = requestPath.length > 1 && requestPath.endsWith('/')
+        ? requestPath.slice(0, -1)
+        : requestPath;
+
+    const requestSegments = normalizedPath.split('/').filter(Boolean);
+
+    let bestMatch = null;
+    let bestScore = -1;
+
+    for (const route of candidates) {
+        const routeSegments = route.path.split('/').filter(Boolean);
+
+        if (routeSegments.length !== requestSegments.length) continue;
+
+        const params = {};
+        let score = 0;
+        let matched = true;
+
+        for (let i = 0; i < routeSegments.length; i++) {
+            const routeSeg = routeSegments[i];
+            const reqSeg = requestSegments[i];
+
+            if (routeSeg.startsWith(':')) {
+                params[routeSeg.slice(1)] = decodeURIComponent(reqSeg);
+            } else if (routeSeg === reqSeg) {
+                score++;
+            } else {
+                matched = false;
+                break;
+            }
+        }
+
+        if (matched && score > bestScore) {
+            bestMatch = { route, params };
+            bestScore = score;
+        }
+    }
+
+    if (requestSegments.length === 0) {
+        const rootRoute = candidates.find(r => r.path === '/');
+        if (rootRoute) {
+            return { route: rootRoute, params: {} };
+        }
+    }
+
+    return bestMatch;
+}
+
+/**
+ * Recursively scan the server/ directory for .js handler files.
+ *
+ * @param {string} serverDir - Absolute path to server/ directory
+ * @returns {Promise<Array<{ path: string, filePath: string }>>}
+ */
+async function scanRoutes(serverDir) {
+    const files = await walkJsFiles(serverDir, 'server');
+    return files.map(({ relPath, absPath }) => ({
+        path: filePathToRoute(relPath),
+        filePath: absPath
+    }));
+}
+
+async function walkJsFiles(dir, basePath) {
+    const results = [];
+    let items;
+    try {
+        items = await readdir(dir);
+    } catch {
+        return results;
+    }
+
+    for (const item of items) {
+        const full = join(dir, item);
+        const childPath = `${basePath}/${item}`;
+        const s = await stat(full);
+
+        if (s.isDirectory()) {
+            results.push(...await walkJsFiles(full, childPath));
+        } else if (item.endsWith('.js')) {
+            results.push({ relPath: childPath, absPath: full });
+        }
+    }
+
+    return results;
+}
+
+/**
+ * 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
+ * @returns {Function} Connect middleware
+ */
+export function createMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, roles }) {
+    const serverDir = join(projectRoot, 'server');
+
+    // query() implementation — proxies to the workspace _sql endpoint
+    async function query(sql, params) {
+        if (!devWorkspaceId) {
+            throw new Error('query() requires INFORMER_DEV_WORKSPACE. Run: npx informer-workspace init');
+        }
+
+        const resp = await globalThis.fetch(`${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: authHeader },
+            body: JSON.stringify({ sql, params: params || [] })
+        });
+
+        if (!resp.ok) {
+            const err = await resp.json().catch(() => ({}));
+            const detail = err.message || resp.statusText;
+            throw new Error(`query() failed: ${resp.status} ${detail} (${serverOrigin}/api/datasources/${devWorkspaceId}/_sql)`);
+        }
+
+        const data = await resp.json();
+        return data.rows;
+    }
+
+    // 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\/)?/, '')}`;
+        const fetchOpts = {
+            method,
+            headers: { Authorization: authHeader, 'Content-Type': 'application/json' }
+        };
+
+        if (opts.body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+            fetchOpts.body = JSON.stringify(opts.body);
+        }
+
+        const resp = await globalThis.fetch(url, fetchOpts);
+        let body;
+        try { body = await resp.json(); } catch { body = await resp.text(); }
+        return { status: resp.status, body };
+    }
+
+    return async function serverRoutesMiddleware(req, res, next) {
+        try {
+            // The URL has already had /api/_server stripped by Vite's middleware.use()
+            const parsed = parseUrl(req.url, true);
+            const routePath = parsed.pathname || '/';
+
+            // Scan server/ directory for handler files
+            const scannedRoutes = await scanRoutes(serverDir);
+
+            // Build route table with all valid methods per file
+            const routeTable = [];
+            for (const scanned of scannedRoutes) {
+                for (const method of VALID_METHODS) {
+                    routeTable.push({ method, path: scanned.path, filePath: scanned.filePath });
+                }
+            }
+
+            // Match request against route table
+            const match = matchRoute(routeTable, req.method, routePath);
+            if (!match) return next();
+
+            // Load handler via Vite's ssrLoadModule (ESM + HMR)
+            const mod = await viteServer.ssrLoadModule(match.route.filePath);
+            const handler = mod[req.method.toUpperCase()];
+
+            if (typeof handler !== 'function') {
+                res.statusCode = 404;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify({ error: 'Method not found' }));
+                return;
+            }
+
+            // Read request body — preserve raw bytes for HMAC verification
+            const chunks = [];
+            for await (const chunk of req) {
+                chunks.push(chunk);
+            }
+            const rawBody = Buffer.concat(chunks).toString('utf8') || null;
+            let body = null;
+            if (rawBody) {
+                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');
+                }
+            };
+
+            // Build request context
+            const request = {
+                method: req.method.toUpperCase(),
+                path: routePath,
+                params: match.params,
+                query: parsed.query || {},
+                body,
+                rawBody,
+                headers: req.headers,
+                roles: roles || [],
+                user: {
+                    username: 'dev-user',
+                    displayName: 'Dev User',
+                    email: null,
+                    timezone: null
+                }
+            };
+
+            // respond() — sends early response, handler continues in background
+            let responded = false;
+            function respond(earlyBody) {
+                if (responded) return;
+                responded = true;
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'application/json');
+                res.end(JSON.stringify(earlyBody));
+            }
+
+            // Call handler
+            const result = await handler({ query, fetch: apiFetch, respond, crypto: cryptoHelper, env: {}, request });
+
+            // 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;
+
+            if (result === undefined || result === null) {
+                status = 204;
+                responseBody = null;
+                responseHeaders = {};
+            } else if (typeof result === 'object' && typeof result.status === 'number') {
+                status = result.status || 200;
+                responseBody = result.body !== undefined ? result.body : null;
+                responseHeaders = result.headers || {};
+            } else {
+                status = 200;
+                responseBody = result;
+                responseHeaders = { 'content-type': 'application/json' };
+            }
+
+            res.statusCode = status;
+            for (const [key, value] of Object.entries(responseHeaders)) {
+                res.setHeader(key, value);
+            }
+
+            if (responseBody === null) {
+                res.end();
+            } else {
+                if (!res.getHeader('content-type')) {
+                    res.setHeader('Content-Type', 'application/json');
+                }
+                res.end(JSON.stringify(responseBody));
+            }
+        } catch (err) {
+            viteServer.ssrFixStacktrace(err);
+            console.error('[server-routes]', err);
+            res.statusCode = 500;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({ error: err.message }));
+        }
+    };
+}