@entrinsik/vite-plugin-informer 2.0.0 → 2.2.0

package/bin/init.js

@@ -232,12 +232,18 @@ async function init() {
         console.log('Added @entrinsik/vite-plugin-informer to devDependencies');
     }
 
-    // 6. Add deploy script if not present
+    // 6. Add scripts if not present
     if (!pkg.scripts) pkg.scripts = {};
     if (!pkg.scripts.deploy) {
         pkg.scripts.deploy = 'npm run build && informer-deploy';
         console.log('Added "deploy" script to package.json');
     }
+    if (!pkg.scripts['workspace:init']) {
+        pkg.scripts['workspace:init'] = 'informer-workspace init';
+        pkg.scripts['workspace:migrate'] = 'informer-workspace migrate';
+        pkg.scripts['workspace:reset'] = 'informer-workspace reset';
+        console.log('Added workspace scripts to package.json');
+    }
 
     await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
     console.log(`Updated package.json with informer.name="${reportName}"`);

package/bin/workspace.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import dotenv from 'dotenv';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createClient } from '../src/client.js';
+import { init, migrate, reset } from '../src/workspace.js';
+
+dotenv.config();
+
+const command = process.argv[2];
+
+if (!command || !['init', 'migrate', 'reset'].includes(command)) {
+    console.error('Usage: informer-workspace <init|migrate|reset>');
+    console.error('');
+    console.error('Commands:');
+    console.error('  init      Create a dev workspace datasource and run migrations');
+    console.error('  migrate   Run pending migrations against the dev workspace');
+    console.error('  reset     Drop all tables and re-run all migrations');
+    process.exit(1);
+}
+
+const baseUrl = process.env.INFORMER_URL;
+const apiKey = process.env.INFORMER_API_KEY;
+const user = process.env.INFORMER_USER;
+const pass = process.env.INFORMER_PASS;
+
+if (!baseUrl || (!apiKey && (!user || !pass))) {
+    console.error('Missing required environment variables.');
+    console.error('Set INFORMER_URL and either INFORMER_API_KEY or INFORMER_USER/INFORMER_PASS in .env');
+    process.exit(1);
+}
+
+const api = createClient({ baseUrl, apiKey, user, pass });
+const migrationsDir = resolve('migrations');
+const envPath = resolve('.env');
+
+try {
+    if (command === 'init') {
+        // Check if already initialized
+        if (process.env.INFORMER_DEV_WORKSPACE) {
+            console.error(`Workspace already initialized: ${process.env.INFORMER_DEV_WORKSPACE}`);
+            console.error('Run workspace:reset to start fresh, or remove INFORMER_DEV_WORKSPACE from .env to re-initialize.');
+            process.exit(1);
+        }
+
+        // Read slug from package.json
+        const pkgPath = resolve('package.json');
+        let pkg;
+        try {
+            pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+        } catch {
+            console.error('Could not read package.json in current directory.');
+            process.exit(1);
+        }
+
+        let slug = pkg.name;
+        if (slug && slug.startsWith('@') && slug.includes('/')) {
+            slug = slug.split('/')[1];
+        }
+        if (!slug) {
+            console.error('package.json must have a "name" field.');
+            process.exit(1);
+        }
+
+        await init({ api, slug, migrationsDir, envPath });
+
+    } else if (command === 'migrate') {
+        const workspaceId = process.env.INFORMER_DEV_WORKSPACE;
+        if (!workspaceId) {
+            console.error('No dev workspace found. Run workspace:init first.');
+            process.exit(1);
+        }
+        await migrate({ api, workspaceId, migrationsDir });
+
+    } else if (command === 'reset') {
+        const workspaceId = process.env.INFORMER_DEV_WORKSPACE;
+        if (!workspaceId) {
+            console.error('No dev workspace found. Run workspace:init first.');
+            process.exit(1);
+        }
+        await reset({ api, workspaceId, migrationsDir });
+    }
+} catch (err) {
+    console.error(`workspace:${command} failed:`, err.message);
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entrinsik/vite-plugin-informer",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Vite plugin and publish tool for local Magic Report development",
   "repository": {
     "type": "git",
@@ -23,11 +23,13 @@
       "types": "./index.d.ts",
       "default": "./src/index.js"
     },
-    "./deploy": "./src/deploy.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": [

package/src/deploy.js

@@ -11,7 +11,7 @@ const TEXT_EXTENSIONS = new Set([
 const CHUNK_THRESHOLD = 512 * 1024; // 512KB
 
 // Config files to upload from project root (if they exist)
-const ROOT_CONFIG_FILES = ['data-access.yaml'];
+const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
 
 /**
  * Deploy a built Vite project to Informer as an App (or legacy Magic Report).
@@ -59,7 +59,7 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
 
         try {
             console.log(`Creating new app "${name}"...`);
-            entity = await api.post('apps', { ...payload, type: 'report' });
+            entity = await api.post('apps', { ...payload, type: 'app' });
             apiPrefix = 'apps';
         } catch (e) {
             // If apps endpoint doesn't exist (404), fall back to legacy reports
@@ -168,8 +168,72 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         }
     }
 
-    // 8. Print URL and return UUID for saving
-    const totalFiles = entries.length + configCount;
+    // 8. Upload migrations/ directory from project root (if it exists)
+    const migrationsDir = join(projectRoot, 'migrations');
+    let migrationsCount = 0;
+    try {
+        await access(migrationsDir);
+        const migrationFiles = await walkDir(migrationsDir);
+        for (const filePath of migrationFiles) {
+            const relPath = posix.normalize(relative(projectRoot, filePath).split('\\').join('/'));
+            const content = await readFile(filePath, 'utf8');
+            await api.put(`${entityPath}/contents/${relPath}`, {
+                content,
+                encoding: 'utf8'
+            });
+            console.log(`  ${relPath} (from project root)`);
+            migrationsCount++;
+        }
+    } catch {
+        // No migrations directory, skip
+    }
+
+    // 9. Upload 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
+    }
+
+    // 10. Deploy: run migrations + scan/bundle server routes
+    if (apiPrefix === 'apps') {
+        try {
+            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}`);
+                    }
+                }
+            }
+        } catch {
+            // Server may not support _deploy yet — ignore
+        }
+    }
+
+    // 11. Print URL and return UUID for saving
+    const totalFiles = entries.length + configCount + migrationsCount + serverCount;
     const base = baseUrl.replace(/\/+$/, '');
     const entityUrl = apiPrefix === 'apps'
         ? `${base}/api/apps/${naturalId}/view`

package/src/index.js

@@ -1,9 +1,16 @@
 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 { init, migrate } from './workspace.js';
 
 /**
  * Vite plugin for local Magic Report development.
  *
  * - Proxies /api requests to the Informer server with Basic auth
+ * - 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
  *
@@ -12,6 +19,9 @@ import dotenv from 'dotenv';
  */
 export default function informer(options = {}) {
     let isDev = false;
+    let authHeader = null;
+    let serverOrigin = null;
+    let devWorkspaceId = null;
 
     return {
         name: 'vite-plugin-informer',
@@ -31,8 +41,11 @@ export default function informer(options = {}) {
                 const user = process.env.INFORMER_USER;
                 const pass = process.env.INFORMER_PASS;
 
+                devWorkspaceId = process.env.INFORMER_DEV_WORKSPACE || null;
+
                 if (baseUrl) {
-                    const auth = apiKey
+                    serverOrigin = baseUrl.replace(/\/+$/, '');
+                    authHeader = apiKey
                         ? 'Bearer ' + apiKey
                         : 'Basic ' + Buffer.from(`${user}:${pass}`).toString('base64');
 
@@ -42,7 +55,7 @@ export default function informer(options = {}) {
                                 target: baseUrl,
                                 changeOrigin: true,
                                 headers: {
-                                    Authorization: auth
+                                    Authorization: authHeader
                                 }
                             }
                         }
@@ -53,6 +66,71 @@ export default function informer(options = {}) {
             return cfg;
         },
 
+        async configureServer(server) {
+            if (!isDev || !serverOrigin) return;
+
+            const projectRoot = process.cwd();
+            const migrationsDir = resolve(projectRoot, 'migrations');
+
+            // 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;
+                    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) {
+                    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);
+            }
+
+        },
+
         transformIndexHtml: {
             order: 'pre',
             handler(html) {
@@ -64,6 +142,7 @@ export default function informer(options = {}) {
                         name: 'Local Development'
                     },
                     theme: 'light',
+                    roles: [],
                     ...options.mock
                 };
 

package/src/server-routes.js

@@ -0,0 +1,284 @@
+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
+            const chunks = [];
+            for await (const chunk of req) {
+                chunks.push(chunk);
+            }
+            const rawBody = Buffer.concat(chunks).toString('utf8');
+            let body = null;
+            if (rawBody) {
+                try { body = JSON.parse(rawBody); } catch { body = rawBody; }
+            }
+
+            // Build request context
+            const request = {
+                method: req.method.toUpperCase(),
+                path: routePath,
+                params: match.params,
+                query: parsed.query || {},
+                body,
+                headers: req.headers,
+                roles: roles || []
+            };
+
+            // Call handler
+            const result = await handler({ query, fetch: apiFetch, env: {}, request });
+
+            // 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 }));
+        }
+    };
+}

package/src/workspace.js

@@ -0,0 +1,159 @@
+import { readdir, readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Execute raw SQL against a workspace datasource via the _sql route.
+ */
+async function execSql(api, workspaceId, sql, params = []) {
+    return api.post(`datasources/${workspaceId}/_sql`, { sql, params });
+}
+
+/**
+ * Ensure the _migrations tracking table exists in the workspace.
+ */
+async function ensureMigrationsTable(api, workspaceId) {
+    await execSql(api, workspaceId, `
+        CREATE TABLE IF NOT EXISTS _migrations (
+            name TEXT PRIMARY KEY,
+            executed_at TIMESTAMPTZ DEFAULT NOW()
+        )
+    `);
+}
+
+/**
+ * Read local migration files sorted alphabetically.
+ * @returns {Promise<string[]>} Sorted filenames (e.g., ['001-create-orders.sql', '002-add-index.sql'])
+ */
+async function readMigrationFiles(migrationsDir) {
+    try {
+        await access(migrationsDir);
+    } catch {
+        return [];
+    }
+
+    const entries = await readdir(migrationsDir);
+    return entries
+        .filter(f => f.endsWith('.sql'))
+        .sort();
+}
+
+/**
+ * Get the set of already-executed migration names.
+ */
+async function getCompletedMigrations(api, workspaceId) {
+    const result = await execSql(api, workspaceId, 'SELECT name FROM _migrations');
+    return new Set(result.rows.map(r => r.name));
+}
+
+/**
+ * Run pending migrations against a workspace.
+ */
+async function runMigrations(api, workspaceId, migrationsDir) {
+    await ensureMigrationsTable(api, workspaceId);
+
+    const files = await readMigrationFiles(migrationsDir);
+    if (files.length === 0) {
+        console.log('No migration files found in migrations/');
+        return { migrated: [], total: 0 };
+    }
+
+    const completed = await getCompletedMigrations(api, workspaceId);
+    const pending = files.filter(f => !completed.has(f));
+
+    if (pending.length === 0) {
+        console.log(`All ${files.length} migration(s) already applied.`);
+        return { migrated: [], total: files.length };
+    }
+
+    const migrated = [];
+    for (const file of pending) {
+        const sql = await readFile(join(migrationsDir, file), 'utf8');
+        console.log(`  Running ${file}...`);
+        await execSql(api, workspaceId, sql);
+        await execSql(api, workspaceId, 'INSERT INTO _migrations (name) VALUES ($1)', [file]);
+        migrated.push(file);
+    }
+
+    console.log(`Applied ${migrated.length} migration(s). Total: ${files.length}`);
+    return { migrated, total: files.length };
+}
+
+/**
+ * Initialize a dev workspace datasource.
+ *
+ * Creates a new workspace datasource named "{slug}-dev", runs all
+ * migrations, and saves the workspace ID to .env.
+ */
+export async function init({ api, slug, migrationsDir, envPath }) {
+    const name = `${slug}-dev`;
+    console.log(`Creating workspace datasource "${name}"...`);
+
+    const datasource = await api.post('datasources', {
+        name,
+        type: 'workspace'
+    });
+
+    if (!datasource || !datasource.naturalId) {
+        throw new Error('Failed to create workspace datasource');
+    }
+
+    const workspaceId = datasource.naturalId;
+    console.log(`Created: ${workspaceId}`);
+
+    // Run all migrations
+    const result = await runMigrations(api, workspaceId, migrationsDir);
+
+    // Save workspace ID to .env
+    let envContent = '';
+    try {
+        envContent = await readFile(envPath, 'utf8');
+    } catch {
+        // .env doesn't exist yet
+    }
+
+    if (envContent.includes('INFORMER_DEV_WORKSPACE=')) {
+        envContent = envContent.replace(
+            /INFORMER_DEV_WORKSPACE=.*/,
+            `INFORMER_DEV_WORKSPACE=${workspaceId}`
+        );
+    } else {
+        const nl = envContent.length > 0 && !envContent.endsWith('\n') ? '\n' : '';
+        envContent += `${nl}\n# Dev workspace (created by workspace:init)\nINFORMER_DEV_WORKSPACE=${workspaceId}\n`;
+    }
+
+    await writeFile(envPath, envContent);
+    console.log(`Saved INFORMER_DEV_WORKSPACE=${workspaceId} to .env`);
+
+    return { workspaceId, ...result };
+}
+
+/**
+ * Run pending migrations against the dev workspace.
+ */
+export async function migrate({ api, workspaceId, migrationsDir }) {
+    console.log(`Migrating workspace ${workspaceId}...`);
+    return runMigrations(api, workspaceId, migrationsDir);
+}
+
+/**
+ * Reset the dev workspace: drop all tables, then re-run all migrations.
+ */
+export async function reset({ api, workspaceId, migrationsDir }) {
+    console.log(`Resetting workspace ${workspaceId}...`);
+
+    // Drop all tables in the workspace schema
+    await execSql(api, workspaceId, `
+        DO $$
+        DECLARE r RECORD;
+        BEGIN
+            FOR r IN SELECT tablename FROM pg_tables WHERE schemaname = current_schema()
+            LOOP
+                EXECUTE 'DROP TABLE IF EXISTS "' || r.tablename || '" CASCADE';
+            END LOOP;
+        END $$
+    `);
+    console.log('Dropped all tables.');
+
+    // Re-run all migrations from scratch
+    return runMigrations(api, workspaceId, migrationsDir);
+}