@svgrid/studio 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @svgrid/studio
+
+Scaffold a full CRUD screen for SvelteKit from a **live database** or a
+**Drizzle / Prisma schema** in **one command**.
+
+```bash
+# from a live database (PostgreSQL / Supabase / MySQL / SQL Server / SQLite)
+npx @svgrid/studio add customers --db postgres --url "$DATABASE_URL"
+
+# or from a schema file - a Drizzle schema.ts or a Prisma schema.prisma
+npx @svgrid/studio add customers --from src/lib/db/schema.ts
+npx @svgrid/studio add User      --from prisma/schema.prisma
+```
+
+That generates, into your SvelteKit app:
+
+- `src/lib/customers.schema.ts` — the entity schema + row type
+- `src/routes/api/customers/+server.ts` — the API route
+- `src/routes/customers/+page.svelte` — a working screen: grid + edit panel, with
+  search, server sort, pagination, and multi-select (optimistic) delete
+
+Then:
+
+```bash
+npm run dev   # open /customers
+```
+
+## Connect to a database
+
+Install the driver for your database, then point `--db` / `--url` at it. The CLI
+reads the table's columns from the catalog and wires the generated route to that
+driver. No driver is bundled.
+
+| Database | Install | Flag |
+| --- | --- | --- |
+| PostgreSQL | `pg` | `--db postgres` |
+| Supabase | `pg` | `--db supabase` |
+| MySQL / MariaDB | `mysql2` | `--db mysql` |
+| SQL Server | `mssql` | `--db mssql` |
+| SQLite | `better-sqlite3` | `--db sqlite` |
+
+```bash
+npm i pg
+npx @svgrid/studio add --all --db postgres --url "$DATABASE_URL"   # every table
+npx @svgrid/studio add todos --db sqlite --url ./data.db           # one table
+```
+
+## Scaffold the whole app from your schema
+
+`--all --from` reads **every** table/model in a schema file and generates a
+screen for each, plus a nav layout and home page. Foreign keys are followed
+across the file - a Drizzle `.references()` or a Prisma `@relation` becomes a
+searchable lookup, and enums become select fields:
+
+```bash
+npx @svgrid/studio add --all --from src/lib/db/schema.ts   # every Drizzle table
+npx @svgrid/studio add --all --from prisma/schema.prisma   # every Prisma model
+```
+
+## Options
+
+```
+svgrid-studio add <name> [--from <schema> | --db <dialect> --url <conn>] [options]
+
+  --from <path>    Drizzle (.ts) or Prisma (.prisma) schema file to introspect
+  --db <dialect>   Connect to a live database (postgres|supabase|mysql|mssql|sqlite)
+  --url <conn>     Connection string / file path for --db
+  --all            Scaffold a screen for every table/model (with --from or --db)
+  --table <name>   Which table/model to use (defaults to <name>)
+  --sql            Use createSqlDataSource with an execute() stub (instead of a driver)
+  --route <seg>    Route segment (default: <name> / table name)
+  --api <path>     API route path (default: /api/<route>)
+```
+
+With `--db`, the generated route is fully connected to that driver via
+`process.env.DATABASE_URL`. With `--from` (no `--db`) it starts in-memory so the
+screen runs immediately; add `--sql` for a `createSqlDataSource` stub you fill
+in with any client (Drizzle `db.execute`, postgres.js, better-sqlite3, mysql2).
+
+## Regeneration is safe
+
+Re-running `add` replaces only the `svgrid:managed` regions of each file — your
+edits outside those markers are preserved.
+
+## Requires
+
+`@svgrid/grid` and `@svgrid/enterprise` in your project. The Studio is part of the
+**Enterprise** license (soft-gate: it works unlicensed, with a nudge). See
+[licensing](https://svgrid.com/pricing).

package/dist/cli.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * SvGrid Studio CLI. Scaffold a full CRUD screen from a Drizzle schema in one
+ * command - the "CRUD app in seconds" entry point.
+ *
+ *   npx @svgrid/studio add customers --from src/lib/db/schema.ts
+ *   npx @svgrid/studio add orders    --from src/lib/db/schema.ts --sql
+ *
+ * All the work (introspect -> scaffold -> merge-write -> verify) lives in the
+ * tested `runStudioAdd` orchestrator; this file is just argument parsing plus
+ * the node:fs wiring.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { introspectDatabase, listDatabaseTables, resolveSchemas, runStudioAdd, runStudioAddApp, summarizeVerify, } from '@svgrid/enterprise/studio';
+import { connect } from './db-connect.js';
+import { startDesignerServer } from './designer-server.js';
+const io = {
+    readFile: async (path) => {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    },
+    writeFile: async (path, contents) => {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, contents);
+    },
+};
+function parse(args) {
+    const out = {};
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--from')
+            out.from = args[++i];
+        else if (a === '--table')
+            out.table = args[++i];
+        else if (a === '--route')
+            out.route = args[++i];
+        else if (a === '--api')
+            out.apiRoute = args[++i];
+        else if (a === '--sql')
+            out.dataSource = 'sql';
+        else if (a === '--db')
+            out.db = args[++i];
+        else if (a === '--url')
+            out.url = args[++i];
+        else if (a === '--all')
+            out.all = true;
+        else if (a === '--config')
+            out.config = args[++i];
+        else if (a === '--out')
+            out.outDir = args[++i];
+        else if (a === '--port')
+            out.port = Number(args[++i]);
+        else if (a === '--template')
+            out.template = args[++i];
+        else if (a === '--no-open')
+            out.noOpen = true;
+        else if (a === '-h' || a === '--help')
+            out.help = true;
+        else if (!a.startsWith('-'))
+            positional.push(a);
+    }
+    const name = positional[0];
+    if (name && !out.route)
+        out.route = name;
+    if (name && !out.table)
+        out.table = name;
+    return out;
+}
+const HELP = `svgrid-studio - scaffold CRUD screens from a schema file or a live database
+
+Usage:
+  svgrid-studio designer                            # open the visual designer in your browser
+  svgrid-studio add <name> --from <schema>          # one table/model from a schema file
+  svgrid-studio add --all   --from <schema>         # every table/model, linked
+  svgrid-studio add <name> --db <dialect> --url <conn>   # one table from a live database
+  svgrid-studio add --all   --db <dialect> --url <conn>  # every table from a live database
+
+Designer (visual app builder, auto-saves to studio.config.json):
+  --template <id>  open a ready-made sample app (crm | ecommerce | projects | support)
+  --config <path>  studio.config.json to load + auto-save (default: ./studio.config.json)
+  --out <dir>      folder to write the generated app into (default: .)
+  --port <n>       port to serve on (default: 4321)
+  --no-open        don't open the browser
+
+Schema files: a Drizzle schema.ts or a Prisma schema.prisma (auto-detected).
+  Foreign keys become searchable relation lookups; enums become select fields.
+
+Databases: postgres | supabase | mysql | mssql | sqlite
+  (the matching driver - pg / mysql2 / mssql / better-sqlite3 - must be installed)
+
+Options:
+  --from <path>    Drizzle (.ts) or Prisma (.prisma) schema file to introspect
+  --db <dialect>   Connect to a live database and read its catalog
+  --url <conn>     Connection string / file path for --db
+  --all            Scaffold a screen for every table/model (+ nav & home)
+  --table <name>   Which table/model to use (defaults to <name>)
+  --sql            Wire a real SQL data source (default with --db)
+  --route <seg>    Route segment (default: <name> / table name)
+  --api <path>     API route path (default: /api/<route>)
+  -h, --help       Show this help
+
+Examples:
+  svgrid-studio add customers --from src/lib/db/schema.ts
+  svgrid-studio add --all     --from prisma/schema.prisma
+  svgrid-studio add customers --db postgres --url $DATABASE_URL --sql
+  svgrid-studio add --all     --db supabase --url $DATABASE_URL
+`;
+function report(name, written, verifyLine) {
+    process.stdout.write(`Scaffolded "${name}":\n`);
+    for (const path of written)
+        process.stdout.write(`  + ${path}\n`);
+    process.stdout.write(`  ${verifyLine}\n`);
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const opts = parse(rest);
+    // --- visual designer -----------------------------------------------------
+    if (cmd === 'designer' && !opts.help) {
+        await startDesignerServer({
+            configPath: opts.config ?? 'studio.config.json',
+            outDir: opts.outDir ?? '.',
+            port: Number.isFinite(opts.port) ? opts.port : 4321,
+            open: !opts.noOpen,
+            template: opts.template,
+        });
+        // Keep the process alive; the server holds the event loop until Ctrl+C.
+        return;
+    }
+    if (cmd !== 'add' || opts.help) {
+        process.stdout.write(HELP);
+        process.exit(opts.help || !cmd ? 0 : 1);
+    }
+    // --- live database -------------------------------------------------------
+    if (opts.db) {
+        if (!opts.url) {
+            process.stderr.write('svgrid-studio: --url is required with --db\n\n' + HELP);
+            process.exit(1);
+        }
+        const execute = await connect(opts.db, opts.url);
+        // A dialect dataSource emits a fully-connected +server.ts (driver + DATABASE_URL);
+        // --sql keeps the generic execute() stub instead.
+        const ds = opts.dataSource === 'sql' ? 'sql' : opts.db;
+        if (opts.all) {
+            // Whole app: every table + a nav layout and home page.
+            const tables = await listDatabaseTables(opts.db, execute);
+            if (tables.length === 0) {
+                process.stderr.write('svgrid-studio: no tables found\n');
+                process.exit(1);
+            }
+            const schemas = [];
+            for (const table of tables) {
+                schemas.push(await introspectDatabase({ dialect: opts.db, table, execute }));
+            }
+            const res = await runStudioAddApp(schemas, { dataSource: ds }, io);
+            report(`app (${schemas.length} entities)`, res.written, summarizeVerify(res.verify));
+            process.stdout.write(`\nRun \`npm run dev\` and open /\n`);
+            return;
+        }
+        const table = opts.table ?? opts.route;
+        const schema = await introspectDatabase({ dialect: opts.db, table, execute });
+        const res = await runStudioAdd({ schema, route: opts.route ?? table, dataSource: ds }, io);
+        report(table, res.written, summarizeVerify(res.verify));
+        process.stdout.write(`\nRun \`npm run dev\` and open /${opts.route ?? table}\n`);
+        return;
+    }
+    // --- schema file (Drizzle or Prisma) -------------------------------------
+    if (!opts.from) {
+        process.stderr.write('svgrid-studio: pass --from <schema.ts|schema.prisma> or --db <dialect> --url <conn>\n\n' + HELP);
+        process.exit(1);
+    }
+    if (opts.all) {
+        // Whole app from every table/model in the file, linked by foreign keys.
+        const schemas = await resolveSchemas(opts.from, io);
+        if (schemas.length === 0) {
+            process.stderr.write('svgrid-studio: no tables/models found in ' + opts.from + '\n');
+            process.exit(1);
+        }
+        const res = await runStudioAddApp(schemas, { dataSource: opts.dataSource }, io);
+        report(`app (${schemas.length} entities)`, res.written, summarizeVerify(res.verify));
+        process.stdout.write(`\nRun \`npm run dev\` and open /\n`);
+        return;
+    }
+    const result = await runStudioAdd({ from: opts.from, table: opts.table, route: opts.route, apiRoute: opts.apiRoute, dataSource: opts.dataSource }, io);
+    report(result.schema.name, result.written, summarizeVerify(result.verify));
+    process.stdout.write(`\nRun \`npm run dev\` and open /${opts.route ?? result.schema.name}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`svgrid-studio: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/db-connect.js

@@ -0,0 +1,56 @@
+/**
+ * Connect to a live database by dynamically importing the matching driver, and
+ * return a neutral `execute(sql, params)` the Studio introspection core uses.
+ *
+ * The driver is an optional peer - it must be installed in the project running
+ * the CLI (`pg` / `mysql2` / `mssql` / `better-sqlite3`). The module specifier
+ * is held in a variable so it isn't a hard dependency of this package. Shared by
+ * the `add --db` command and the `designer` connect wizard (`/api/introspect`).
+ */
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+/**
+ * Load a driver from the *project's* node_modules (the current working
+ * directory), not this CLI's. In an `npx`/global install the CLI lives in a
+ * cache far from the user's project, so resolving relative to `import()` would
+ * miss a driver the user installed. Resolving from cwd finds it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function loadDriver(spec) {
+    const requireFromCwd = createRequire(pathToFileURL(join(process.cwd(), 'noop.js')));
+    const resolved = requireFromCwd.resolve(spec);
+    return import(pathToFileURL(resolved).href);
+}
+export async function connect(dialect, url) {
+    if (dialect === 'postgres' || dialect === 'supabase') {
+        const pg = await loadDriver('pg');
+        const Client = pg.Client ?? pg.default?.Client;
+        const client = new Client({ connectionString: url });
+        await client.connect();
+        return async (sql, params) => (await client.query(sql, params)).rows;
+    }
+    if (dialect === 'mysql') {
+        const mysql = await loadDriver('mysql2/promise');
+        const conn = await mysql.createConnection(url);
+        return async (sql, params) => {
+            const [rows] = await conn.execute(sql, params);
+            return rows;
+        };
+    }
+    if (dialect === 'mssql') {
+        const mod = await loadDriver('mssql');
+        const mssql = mod.default ?? mod;
+        const pool = await mssql.connect(url);
+        return async (text, params) => {
+            const req = pool.request();
+            params.forEach((p, i) => req.input(`p${i + 1}`, p));
+            return (await req.query(text)).recordset;
+        };
+    }
+    // sqlite (better-sqlite3, synchronous)
+    const mod = await loadDriver('better-sqlite3');
+    const Database = mod.default ?? mod;
+    const db = new Database(url);
+    return async (sql, params) => db.prepare(sql).all(...params);
+}

package/dist/designer-server.js

@@ -0,0 +1,297 @@
+/**
+ * The local server behind `npx @svgrid/studio designer`. A tiny zero-dep
+ * `node:http` server that:
+ *   - serves the pre-built designer SPA from `@svgrid/enterprise/dist/designer`
+ *   - GET  /api/project   -> the saved studio.config.json (or a starter project)
+ *   - POST /api/project   -> auto-save the design back to studio.config.json
+ *   - POST /api/generate  -> write the generated app bundle into the launch folder
+ *
+ * All the model + codegen work is reused from `@svgrid/enterprise/studio` (the
+ * Svelte-free Node bundle); this file is just HTTP + node:fs wiring. Keeping it
+ * dependency-free means the CLI runs on bare Node.
+ */
+import { createServer } from 'node:http';
+import { createReadStream, existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, normalize, resolve, extname } from 'node:path';
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { createProject, parseProject, serializeProject, introspectDatabase, listDatabaseTables, probeConnection, linkRelationLabels, buildConnectionString, getSampleApp, } from '@svgrid/enterprise/studio';
+import { connect } from './db-connect.js';
+import { DRIVER_FOR, installDriver, isDriverInstalled } from './driver-install.js';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.png': 'image/png',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.map': 'application/json; charset=utf-8',
+};
+/** The runtime deps the generated code imports, keyed by a source needle. */
+const RUNTIME_DEPS = [
+    ["from '@supabase/supabase-js'", '@supabase/supabase-js', '^2.45.0'],
+    ["import pg from 'pg'", 'pg', '^8.11.0'],
+    ["from 'mysql2/promise'", 'mysql2', '^3.9.0'],
+    ["import mssql from 'mssql'", 'mssql', '^10.0.0'],
+    ["import Database from 'better-sqlite3'", 'better-sqlite3', '^11.0.0'],
+];
+/** Resolve the shipped static designer bundle (`dist/designer`). */
+function resolveDesignerDir() {
+    const require = createRequire(import.meta.url);
+    const pkgJson = require.resolve('@svgrid/enterprise/package.json');
+    const dir = join(dirname(pkgJson), 'dist', 'designer');
+    if (!existsSync(join(dir, 'index.html'))) {
+        throw new Error('The designer bundle is missing. Reinstall @svgrid/enterprise, or run its build (`npm run build`).');
+    }
+    return dir;
+}
+/** The project a fresh session opens with: a chosen sample app (`--template`), or
+ *  a minimal tasks starter. */
+function starterProject(templateId) {
+    if (templateId) {
+        const app = getSampleApp(templateId);
+        if (app)
+            return app.build();
+    }
+    const tasks = {
+        name: 'tasks',
+        label: 'Task',
+        idField: 'id',
+        fields: [
+            { field: 'id', type: 'number', primaryKey: true, readonly: true },
+            { field: 'title', type: 'text', required: true },
+            { field: 'status', type: 'enum', options: [{ value: 'todo', label: 'To do' }, { value: 'doing', label: 'Doing' }, { value: 'done', label: 'Done' }] },
+            { field: 'due', type: 'date' },
+        ],
+    };
+    return createProject([tasks], { title: 'My App' });
+}
+function send(res, status, body, type = 'application/json; charset=utf-8') {
+    res.writeHead(status, { 'content-type': type });
+    res.end(body);
+}
+function readBody(req) {
+    return new Promise((resolveBody, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolveBody(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** Serve a file from the static bundle (SPA fallback to index.html). */
+function serveStatic(res, dir, urlPath) {
+    // Strip the query, decode, and normalize away any `..` traversal.
+    const clean = normalize(decodeURIComponent(urlPath.split('?')[0])).replace(/^(\.\.[/\\])+/, '');
+    let filePath = join(dir, clean);
+    if (!filePath.startsWith(dir))
+        filePath = join(dir, 'index.html');
+    if (clean === '/' || clean === '\\' || !existsSync(filePath))
+        filePath = join(dir, 'index.html');
+    res.writeHead(200, { 'content-type': MIME[extname(filePath)] ?? 'application/octet-stream' });
+    createReadStream(filePath).pipe(res);
+}
+/** Write the generated app bundle to disk and add any runtime deps it imports. */
+async function writeBundle(outDir, files) {
+    for (const f of files) {
+        const full = join(outDir, f.path);
+        await mkdir(dirname(full), { recursive: true });
+        await writeFile(full, f.contents);
+    }
+    const allSource = files.map((f) => f.contents).join('\n');
+    const pkgPath = join(outDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+            let changed = false;
+            for (const [needle, dep, version] of RUNTIME_DEPS) {
+                if (allSource.includes(needle)) {
+                    pkg.dependencies = { ...pkg.dependencies, [dep]: version };
+                    changed = true;
+                }
+            }
+            if (changed)
+                await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        }
+        catch {
+            // leave package.json untouched if it isn't valid JSON
+        }
+    }
+    return files.length;
+}
+/** Best-effort open the default browser (no dependency). */
+function openBrowser(url) {
+    const cmd = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // ignore - the URL is printed anyway
+    }
+}
+/** Start the designer server. Resolves once it is listening. */
+export async function startDesignerServer(opts) {
+    const log = opts.log ?? ((line) => process.stdout.write(line + '\n'));
+    const dir = resolveDesignerDir();
+    const configPath = resolve(process.cwd(), opts.configPath);
+    const outDir = resolve(process.cwd(), opts.outDir);
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((err) => {
+            send(res, 500, JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        });
+    });
+    async function handle(req, res) {
+        const url = req.url ?? '/';
+        const path = url.split('?')[0];
+        if (path === '/api/project' && req.method === 'GET') {
+            const json = existsSync(configPath) ? await readFile(configPath, 'utf8') : null;
+            // Round-trip through parse/serialize so we hand the client a normalized,
+            // validated project (or the starter / chosen sample when there's no saved config).
+            const project = json ? parseProject(json) : starterProject(opts.template);
+            send(res, 200, serializeProject(project));
+            return;
+        }
+        if (path === '/api/project' && req.method === 'POST') {
+            const body = await readBody(req);
+            const project = parseProject(body); // validate before persisting
+            await mkdir(dirname(configPath), { recursive: true });
+            await writeFile(configPath, serializeProject(project));
+            send(res, 200, JSON.stringify({ ok: true, saved: configPath }));
+            return;
+        }
+        if (path === '/api/generate' && req.method === 'POST') {
+            const body = await readBody(req);
+            const parsed = JSON.parse(body);
+            const files = Array.isArray(parsed.files) ? parsed.files : [];
+            if (files.length === 0) {
+                send(res, 400, JSON.stringify({ error: 'no files to write' }));
+                return;
+            }
+            const count = await writeBundle(outDir, files);
+            log(`  generated ${count} files -> ${outDir}`);
+            send(res, 200, JSON.stringify({ ok: true, count, outDir }));
+            return;
+        }
+        // Assemble a connection string from guided-form fields (host/port/user/...).
+        if (path === '/api/build-connection' && req.method === 'POST') {
+            const body = await readBody(req);
+            const reqBody = JSON.parse(body);
+            if (!reqBody.dialect) {
+                send(res, 400, JSON.stringify({ error: 'dialect is required' }));
+                return;
+            }
+            try {
+                const url = buildConnectionString(reqBody.dialect, reqBody.parts ?? {});
+                send(res, 200, JSON.stringify({ url }));
+            }
+            catch (err) {
+                send(res, 400, JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+            }
+            return;
+        }
+        // Install the dialect's driver into the user's project (auto-detects the PM).
+        if (path === '/api/install-driver' && req.method === 'POST') {
+            const body = await readBody(req);
+            const reqBody = JSON.parse(body);
+            if (!reqBody.dialect) {
+                send(res, 400, JSON.stringify({ error: 'dialect is required' }));
+                return;
+            }
+            const cwd = process.cwd();
+            log(`  installing ${DRIVER_FOR[reqBody.dialect]} driver...`);
+            const result = await installDriver(reqBody.dialect, cwd);
+            log(result.ok ? `  driver ready (${result.package})` : `  driver install failed (${result.package})`);
+            send(res, result.ok ? 200 : 500, JSON.stringify(result));
+            return;
+        }
+        if (path === '/api/introspect' && req.method === 'POST') {
+            const body = await readBody(req);
+            const reqBody = JSON.parse(body);
+            const { dialect, url, action } = reqBody;
+            if (!dialect || !url) {
+                send(res, 400, JSON.stringify({ error: 'dialect and url are required' }));
+                return;
+            }
+            let execute;
+            try {
+                execute = await connect(dialect, url);
+            }
+            catch (err) {
+                // Missing driver / bad connection string - report it, don't crash. When
+                // the driver is simply absent, flag it so the UI can offer to install it.
+                const msg = err instanceof Error ? err.message : String(err);
+                const driver = DRIVER_FOR[dialect];
+                const missingDriver = /cannot find|module not found|err_module/i.test(msg) && !isDriverInstalled(dialect, process.cwd());
+                const hint = missingDriver ? ` Install the "${driver}" driver in this project (npm i ${driver}).` : '';
+                send(res, 502, JSON.stringify({ error: `Could not connect: ${msg}.${hint}`, missingDriver, driver }));
+                return;
+            }
+            if (action === 'test') {
+                // "Test connection": prove connectivity + show real row counts per table.
+                try {
+                    const probe = await probeConnection(dialect, execute, { counts: true });
+                    send(res, 200, JSON.stringify(probe));
+                }
+                catch (err) {
+                    send(res, 502, JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+                }
+                return;
+            }
+            if (action === 'introspect') {
+                const tables = Array.isArray(reqBody.tables) ? reqBody.tables : [];
+                const schemas = [];
+                const errors = [];
+                // Resilient per table: one bad table (odd type, permissions) shouldn't
+                // sink the whole import - collect what worked and report the rest.
+                for (const table of tables) {
+                    try {
+                        schemas.push(await introspectDatabase({ dialect, table, execute }));
+                    }
+                    catch (err) {
+                        errors.push({ table, message: err instanceof Error ? err.message : String(err) });
+                    }
+                }
+                // Resolve each relation's label field against the other picked tables.
+                send(res, 200, JSON.stringify({ schemas: linkRelationLabels(schemas), errors }));
+                return;
+            }
+            // Default: list the tables so the wizard can offer a pick list.
+            const tables = await listDatabaseTables(dialect, execute);
+            send(res, 200, JSON.stringify({ tables }));
+            return;
+        }
+        if (path.startsWith('/api/')) {
+            send(res, 404, JSON.stringify({ error: 'not found' }));
+            return;
+        }
+        serveStatic(res, dir, url);
+    }
+    const url = `http://localhost:${opts.port}`;
+    await new Promise((ready, fail) => {
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                fail(new Error(`Port ${opts.port} is already in use. Pick another with --port <n>.`));
+            }
+            else {
+                fail(err);
+            }
+        });
+        server.listen(opts.port, () => ready());
+    });
+    if (opts.template && !getSampleApp(opts.template)) {
+        const { sampleApps } = await import('@svgrid/enterprise/studio');
+        log(`  (unknown --template "${opts.template}"; try: ${sampleApps.map((s) => s.id).join(', ')})`);
+    }
+    log(`\n  SvGrid Studio designer running at ${url}`);
+    log(`  config:  ${configPath}`);
+    log(`  output:  ${outDir}`);
+    log(`  (edits auto-save; "Save to folder" writes the app. Ctrl+C to stop.)\n`);
+    if (opts.open)
+        openBrowser(url);
+    return { url, close: () => server.close() };
+}

package/dist/driver-install.js

@@ -0,0 +1,87 @@
+/**
+ * Install the database driver a dialect needs, into the *user's* project. Powers
+ * the designer's "Install driver" button and the CLI's auto-offer, so a user
+ * connecting to Postgres never has to know they must `npm i pg` first - Studio
+ * detects the project's package manager and runs it for them.
+ *
+ * Node-only (spawns the package manager); kept out of the Svelte-free enterprise
+ * bundle. The driver package names mirror `DRIVER_PACKAGE` in
+ * `@svgrid/enterprise/studio`.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join as joinNative } from 'node:path';
+import { pathToFileURL as toFileURL } from 'node:url';
+/** The npm driver package each dialect connects through. */
+export const DRIVER_FOR = {
+    postgres: 'pg',
+    supabase: 'pg',
+    mysql: 'mysql2',
+    mssql: 'mssql',
+    sqlite: 'better-sqlite3',
+};
+/** Pick the package manager from the project's lockfile (npm is the fallback). */
+export function detectPackageManager(cwd) {
+    if (existsSync(joinNative(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(joinNative(cwd, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(joinNative(cwd, 'bun.lockb')) || existsSync(joinNative(cwd, 'bun.lock')))
+        return 'bun';
+    return 'npm';
+}
+/** The install args to add `pkg` as a dev dependency for a given manager. */
+export function installArgs(pm, pkg) {
+    switch (pm) {
+        case 'pnpm':
+            return ['add', '-D', pkg];
+        case 'yarn':
+            return ['add', '--dev', pkg];
+        case 'bun':
+            return ['add', '-d', pkg];
+        default:
+            return ['install', '--save-dev', pkg];
+    }
+}
+/** Is the driver already resolvable from the project? (skip a needless install). */
+export function isDriverInstalled(dialect, cwd) {
+    const pkg = DRIVER_FOR[dialect];
+    try {
+        const requireFromCwd = createRequire(toFileURL(joinNative(cwd, 'noop.js')));
+        requireFromCwd.resolve(pkg);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install the dialect's driver into `cwd`. No-ops (ok:true) when it's already
+ * present. Never rejects: a failed install resolves with `ok:false` and the
+ * captured output so the UI can show it.
+ */
+export function installDriver(dialect, cwd) {
+    const pkg = DRIVER_FOR[dialect];
+    const manager = detectPackageManager(cwd);
+    if (isDriverInstalled(dialect, cwd)) {
+        return Promise.resolve({ ok: true, alreadyInstalled: true, manager, package: pkg, output: '' });
+    }
+    return new Promise((resolve) => {
+        let output = '';
+        // shell:true on Windows so `npm`/`pnpm` (.cmd shims) resolve on PATH.
+        const child = spawn(manager, installArgs(manager, pkg), {
+            cwd,
+            shell: process.platform === 'win32',
+        });
+        const capture = (buf) => {
+            output += buf.toString();
+            if (output.length > 8000)
+                output = output.slice(-8000);
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
+        child.on('error', (err) => resolve({ ok: false, alreadyInstalled: false, manager, package: pkg, output: `${output}\n${String(err)}`.trim() }));
+        child.on('close', (code) => resolve({ ok: code === 0, alreadyInstalled: false, manager, package: pkg, output: output.trim() }));
+    });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@svgrid/studio",
+  "version": "0.1.0",
+  "description": "SvGrid Studio CLI: scaffold a full CRUD screen (grid + edit panel + SvelteKit API route) from a Drizzle schema in one command.",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "jQWidgets <sales@jqwidgets.com>",
+  "homepage": "https://svgrid.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sv-grid/sv-grid.git",
+    "directory": "packages/studio"
+  },
+  "type": "module",
+  "bin": {
+    "svgrid-studio": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test:types": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@svgrid/enterprise": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}