@svgrid/studio 0.2.0 → 0.4.0

package/LICENSE

@@ -1,46 +1,85 @@
-This repository is a multi-package workspace. Different packages ship
-under different licenses. The authoritative license for each package is
-the LICENSE file inside that package directory.
+SVGRID STUDIO COMMERCIAL LICENSE
+Version 1.0
+
+Copyright (c) 2026 jQWidgets Ltd
+Project: @svgrid/studio
+
+This software is licensed, not sold. Use requires a valid, paid SvGrid
+Pro or Enterprise license. The authoritative agreement is the SvGrid
+End User License Agreement at https://svgrid.com/eula; this file
+summarises the terms that apply to this package.
 
 ------------------------------------------------------------------------
-Per-package licensing
+1. GRANT (with valid SvGrid Pro or Enterprise license)
 ------------------------------------------------------------------------
 
-  packages/grid/       MIT (terms below, and packages/grid/LICENSE)
-  packages/enterprise/        Commercial - see packages/enterprise/LICENSE
-  packages/mcp/        Commercial - see packages/mcp/LICENSE
-  website/                     Proprietary - see website/LICENSE
+Subject to the Subscriber's compliance with this License and continued
+payment of the applicable license fee, the Author grants the Subscriber
+a non-exclusive, non-transferable, non-sublicensable license to:
+
+  (a) install and run the Software on developer workstations and on
+      build / CI machines belonging to the Subscriber;
+  (b) use the Software to generate application source code, and to
+      use, modify, and distribute that generated output as part of the
+      Subscriber's own applications;
+  (c) modify the Software for the Subscriber's internal use, provided
+      that all copyright notices and license terms are preserved.
+
+The number of developer seats covered is determined by the
+Subscriber's SvGrid Pro / Enterprise order. A "developer" is any
+individual who runs the Software, or who writes or modifies source
+code it generated.
 
-Only `@svgrid/grid` is open source. Everything else in this
-repository (the Pro feature pack, the MCP server, the marketing +
-docs website, and any other package added later that does not ship
-its own MIT LICENSE) is proprietary and may not be copied, modified,
-or redistributed without a paid license. Source is visible in this
-repository for transparency and for paying customers; visibility does
-not grant a license.
+Code generated by the Software is owned by the Subscriber and is not
+subject to Section 2, except that generated code which imports
+`@svgrid/enterprise` still requires an Enterprise license at runtime.
 
 ------------------------------------------------------------------------
-MIT License (applies ONLY to packages/grid)
+2. RESTRICTIONS
 ------------------------------------------------------------------------
 
-MIT License
+The Subscriber may NOT:
 
-Copyright (c) 2026 jQWidgets Ltd
+  (a) redistribute the Software as a standalone package, library, CLI,
+      or hosted service;
+  (b) sublicense, rent, lease, or sell the Software to third parties;
+  (c) expose the Software's code generation as a service to users
+      outside the Subscriber's organisation;
+  (d) use the Software to develop a directly competing application
+      builder, code generator, or data-grid product.
+
+------------------------------------------------------------------------
+3. SUBSCRIPTION AND TERMINATION
+------------------------------------------------------------------------
+
+The license is granted for the term specified in the Subscriber's
+SvGrid Pro or Enterprise order. On non-renewal or material breach of
+Sections 1 or 2, the license terminates automatically and the
+Subscriber must cease all use of the Software and remove it from
+development environments and CI infrastructure. Applications already
+generated and shipped are not affected.
+
+------------------------------------------------------------------------
+4. WARRANTY DISCLAIMER AND LIABILITY
+------------------------------------------------------------------------
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM USE OF THE SOFTWARE,
+WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE.
+
+The Author's total cumulative liability under this License shall not
+exceed the license fees paid by the Subscriber in the twelve months
+preceding the event giving rise to the claim.
+
+------------------------------------------------------------------------
+5. CONTACT
+------------------------------------------------------------------------
+
+To purchase a license, request a quote, or report unauthorized use,
+contact: boikom@jqwidgets.com
+Pricing: https://svgrid.com/pricing
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+END OF LICENSE

package/README.md

@@ -1,7 +1,41 @@
-# @svgrid/studio
+<p align="center">
+  <img src="https://svgrid.com/brand/svgrid-logo-icon-1200.png" alt="SvGrid" width="100" height="100" />
+</p>
 
-Scaffold a full CRUD screen for SvelteKit from a **live database** or a
-**Drizzle / Prisma schema** in **one command**.
+<h1 align="center">@svgrid/studio</h1>
+
+<p align="center"><strong>Generate SvelteKit CRUD screens from your database schema.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@svgrid/studio"><img src="https://img.shields.io/npm/v/%40svgrid%2Fstudio.svg?label=%40svgrid%2Fstudio" alt="npm version" /></a>
+  <a href="https://svgrid.com/pricing/"><img src="https://img.shields.io/badge/license-commercial-blue.svg" alt="Commercial license" /></a>
+</p>
+
+<p align="center">
+  <a href="https://svgrid.com">Website</a> ·
+  <a href="https://svgrid.com/docs/">Docs</a> ·
+  <a href="https://svgrid.com/pricing/">Pricing</a>
+</p>
+
+---
+
+Not sure where to start? Let it ask:
+
+```bash
+npx @svgrid/studio init
+```
+
+`init` walks you through it - where your data lives, which tables you want,
+which pages each gets - and writes a runnable SvelteKit app: a searchable list,
+an edit form and a record page per table, plus an overview dashboard. Point it
+straight at a database and it installs the driver for you:
+
+```bash
+npx @svgrid/studio init --db postgres --url "$DATABASE_URL" --out my-app
+```
+
+Or scaffold a single CRUD screen into an existing app from a **live database**
+or a **Drizzle / Prisma schema** in **one command**:
 
 ```bash
 # from a live database (PostgreSQL / Supabase / MySQL / SQL Server / SQLite)
@@ -14,9 +48,9 @@ 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
+- `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:
@@ -79,11 +113,11 @@ 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
+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).
+[licensing](https://svgrid.com/pricing/).

package/dist/cli.js

@@ -11,11 +11,14 @@
  * the node:fs wiring.
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { buildStudioBugReport, introspectDatabase, listDatabaseTables, parseProject, resolveSchemas, runStudioAdd, runStudioAddApp, summarizeVerify, } from '@svgrid/enterprise/studio';
+import { spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { dirname, resolve } from 'node:path';
+import { buildStudioBugReport, createProject, deployCommands, emitStudioAppBundle, emitStudioFragment, introspectDatabase, introspectOpenApi, runtimeDeps, listDatabaseTables, missingEnvKeys, parseProject, resolveDeployTarget, resolveSchemas, runStudioAdd, runStudioAddApp, runStudioInit, serializeProject, setEntityDataSource, summarizeVerify, } from '@svgrid/enterprise/studio';
 import { connect } from './db-connect.js';
-import { DRIVER_FOR, installDriver, isDriverInstalled } from './driver-install.js';
+import { ensureDriverInstalled } from './driver-install.js';
 import { startDesignerServer } from './designer-server.js';
+import { ensureApp, startAppServer } from './dev.js';
 const io = {
     readFile: async (path) => {
         try {
@@ -61,6 +64,30 @@ function parse(args) {
             out.template = args[++i];
         else if (a === '--no-open')
             out.noOpen = true;
+        else if (a === '--target')
+            out.target = args[++i];
+        else if (a === '--dry-run')
+            out.dryRun = true;
+        else if (a === '--ai')
+            out.ai = true;
+        else if (a === '--app-port')
+            out.appPort = Number(args[++i]);
+        else if (a === '--fragment')
+            out.fragment = true;
+        else if (a === '--supabase-url')
+            out.supabaseUrl = args[++i];
+        else if (a === '--supabase-key')
+            out.supabaseKey = args[++i];
+        else if (a === '--dataset')
+            out.dataset = args[++i];
+        else if (a === '--theme')
+            out.theme = args[++i];
+        else if (a === '--dark')
+            out.dark = true;
+        else if (a === '--title')
+            out.title = args[++i];
+        else if (a === '-y' || a === '--yes')
+            out.yes = true;
         else if (a === '-h' || a === '--help')
             out.help = true;
         else if (!a.startsWith('-'))
@@ -76,11 +103,34 @@ function parse(args) {
 const HELP = `svgrid-studio - scaffold CRUD screens from a schema file or a live database
 
 Usage:
+  svgrid-studio init                                # guided: pick your data, get a working CRUD app
   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
+  svgrid-studio openapi <file|url>                   # import an OpenAPI (JSON) spec -> studio.config.json
+  svgrid-studio eject [--fragment]                  # write the app (or a drop-in fragment) from studio.config.json
+  svgrid-studio dev                                 # designer + the RUNNING app, side by side (HMR)
+  svgrid-studio deploy [--target <provider>] [--dry-run]  # build + deploy via the provider CLI
+
+Guided setup (init) - asks where your data lives, which tables you want, and
+which pages each gets, then writes a runnable app + studio.config.json.
+Running \`svgrid-studio\` with no arguments starts it too.
+  --db <dialect> --url <conn>   skip the questions and read a live database
+  --supabase-url <url> --supabase-key <anon>   read a Supabase project over its
+                   REST API (no driver, works without a local database)
+  --dataset <id>   start from sample data (customers-orders, products-categories,
+                   projects-tasks, employees-departments, tickets-accounts)
+  --title <name>   app name
+  --out <dir>      folder to write the app into (default: .)
+  --theme <id>     design-system preset      --dark   dark mode
+  -y, --yes        take every default, ask nothing
+
+Deploy (build first, then the provider CLI; target from --target, else
+studio.config.json, else the adapter in svelte.config.js):
+  --target <p>     vercel | netlify | cloudflare | node
+  --dry-run        print the resolved commands without running anything
 
 Designer (visual app builder, auto-saves to studio.config.json):
   --template <id>  open a ready-made sample app (crm | ecommerce | projects | support)
@@ -88,6 +138,8 @@ Designer (visual app builder, auto-saves to 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
+  --ai             enable the AI copilot (needs ANTHROPIC_API_KEY in the environment)
+  --app-port <n>   dev: port for the generated app's dev server (default: designer port + 1)
 
 Schema files: a Drizzle schema.ts or a Prisma schema.prisma (auto-detected).
   Foreign keys become searchable relation lookups; enums become select fields.
@@ -107,11 +159,78 @@ Options:
   -h, --help       Show this help
 
 Examples:
+  svgrid-studio init
+  svgrid-studio init --db postgres --url $DATABASE_URL --out my-app
   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
 `;
+/**
+ * Terminal prompts for the guided `init`.
+ *
+ * Lines are queued from a listener attached up front rather than read one at a
+ * time with `rl.question()`: on a pipe or a redirected file, readline delivers
+ * the whole buffer at once, and anything arriving before the next question is
+ * asked would simply be dropped. Once input runs out we answer with each
+ * question's default, so a scripted run finishes instead of hanging.
+ */
+function terminalPrompts() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const waiting = [];
+    const buffered = [];
+    let ended = false;
+    rl.on('line', (line) => {
+        const next = waiting.shift();
+        if (next)
+            next(line);
+        else
+            buffered.push(line);
+    });
+    rl.on('close', () => {
+        ended = true;
+        for (const resolve of waiting.splice(0))
+            resolve(null);
+    });
+    const nextLine = () => {
+        if (buffered.length)
+            return Promise.resolve(buffered.shift());
+        if (ended)
+            return Promise.resolve(null);
+        return new Promise((resolve) => waiting.push(resolve));
+    };
+    return {
+        ask: async (question, def) => {
+            process.stdout.write(`${question}${def ? ` (${def})` : ''} `);
+            const line = await nextLine();
+            if (line === null) {
+                process.stdout.write(`${def ?? ''}\n`); // echo the default we fell back to
+                return def ?? '';
+            }
+            return line.trim() || def || '';
+        },
+        say: (line) => process.stdout.write(line + '\n'),
+        close: () => rl.close(),
+    };
+}
+/** Read an OpenAPI spec / REST response from a URL or a local file. */
+const fetchText = async (source) => /^https?:\/\//.test(source) ? (await fetch(source)).text() : readFile(source, 'utf8');
+/** The guided "build me a CRUD app" flow. */
+async function runInit(flags) {
+    const prompts = terminalPrompts();
+    try {
+        const result = await runStudioInit(flags, prompts, {
+            ensureDriver: (dialect) => ensureDriverInstalled(dialect, process.cwd(), prompts.say),
+            connect: (dialect, url) => connect(dialect, url),
+        }, io, fetchText);
+        process.stdout.write('\nNext:\n');
+        for (const stepLine of result.nextSteps)
+            process.stdout.write(`  ${stepLine}\n`);
+    }
+    finally {
+        prompts.close();
+    }
+}
 function report(name, written, verifyLine) {
     process.stdout.write(`Scaffolded "${name}":\n`);
     for (const path of written)
@@ -121,6 +240,107 @@ function report(name, written, verifyLine) {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const opts = parse(rest);
+    // --- guided setup: the few-clicks path from nothing to a CRUD app ---------
+    // Bare `svgrid-studio` in a terminal starts here too: with no argument, the
+    // most useful thing we can do is walk the user through building an app.
+    if ((cmd === 'init' || (!cmd && process.stdin.isTTY)) && !opts.help) {
+        await runInit({
+            ...(opts.outDir ? { out: opts.outDir } : {}),
+            ...(opts.db ? { db: opts.db } : {}),
+            ...(opts.url ? { url: opts.url } : {}),
+            ...(opts.supabaseUrl ? { supabaseUrl: opts.supabaseUrl } : {}),
+            ...(opts.supabaseKey ? { supabaseKey: opts.supabaseKey } : {}),
+            ...(opts.dataset ? { dataset: opts.dataset } : {}),
+            ...(opts.theme ? { theme: opts.theme } : {}),
+            ...(opts.dark ? { dark: true } : {}),
+            ...(opts.title ? { title: opts.title } : {}),
+            ...(opts.yes ? { yes: true } : {}),
+        });
+        return;
+    }
+    // --- eject: write the app (or a fragment) from studio.config.json ---------
+    if (cmd === 'eject' && !opts.help) {
+        const configPath = opts.config ?? 'studio.config.json';
+        const json = await io.readFile(configPath);
+        if (json == null) {
+            process.stderr.write(`eject: ${configPath} not found - run \`svgrid-studio designer\` first, or pass --config.\n`);
+            process.exit(1);
+        }
+        const project = parseProject(json);
+        const outDir = opts.outDir ?? '.';
+        const files = opts.fragment ? emitStudioFragment(project) : emitStudioAppBundle(project);
+        for (const f of files) {
+            const full = resolve(outDir, f.path);
+            await mkdir(dirname(full), { recursive: true });
+            await writeFile(full, f.contents);
+        }
+        process.stdout.write(`Wrote ${files.length} ${opts.fragment ? 'fragment' : 'app'} file(s) -> ${resolve(outDir)}\n`);
+        if (opts.fragment) {
+            const deps = runtimeDeps(project, files.map((f) => f.contents).join('\n'));
+            const install = Object.keys(deps).filter((d) => d !== '@svgrid/grid' && d !== '@svgrid/enterprise');
+            process.stdout.write(`Fragment: merge src/routes + src/lib into your app, import src/app.css, then:\n  npm install ${install.join(' ') || '@svgrid/grid @svgrid/enterprise'}\nSee FRAGMENT.md for the full runbook.\n`);
+        }
+        return;
+    }
+    // --- import an OpenAPI spec into a studio.config.json ---------------------
+    if (cmd === 'openapi' && !opts.help) {
+        const src = opts.from ?? rest.find((a) => !a.startsWith('-'));
+        if (!src) {
+            process.stderr.write('openapi: pass a spec - `svgrid-studio openapi ./openapi.json` (or a URL)\n');
+            process.exit(1);
+        }
+        const text = /^https?:\/\//.test(src) ? await (await fetch(src)).text() : await readFile(src, 'utf8');
+        const { entities, sources, warnings } = introspectOpenApi(text);
+        let project = createProject(entities, { title: 'API app' });
+        for (const [name, source] of Object.entries(sources))
+            project = setEntityDataSource(project, name, source);
+        const outPath = opts.config ?? 'studio.config.json';
+        await writeFile(outPath, serializeProject(project));
+        process.stdout.write(`Imported ${entities.length} REST resource(s) -> ${outPath}\n`);
+        for (const w of warnings)
+            process.stdout.write(`  ! ${w}\n`);
+        process.stdout.write(`Next: svgrid-studio designer   (open it visually)  or  svgrid-studio dev\n`);
+        return;
+    }
+    // --- live dev loop: designer + the real app, side by side ----------------
+    if (cmd === 'dev' && !opts.help) {
+        const configPath = opts.config ?? 'studio.config.json';
+        const outDir = opts.outDir ?? '.';
+        const port = Number.isFinite(opts.port) ? opts.port : 4321;
+        const appPort = Number.isFinite(opts.appPort) ? opts.appPort : port + 1;
+        const log = (l) => process.stdout.write(l + '\n');
+        const hasApp = await ensureApp(resolve(outDir), resolve(configPath), log);
+        let app = null;
+        if (hasApp) {
+            app = await startAppServer({ outDir, port: appPort, log });
+            log(`\n  app:      ${app.url} (Vite dev server - designer saves hot-reload it)`);
+        }
+        else {
+            log(`\n  No app here yet - design something and hit "Save to folder"; the app server starts on the first save.`);
+        }
+        process.on('SIGINT', () => {
+            app?.stop();
+            process.exit(0);
+        });
+        await startDesignerServer({
+            configPath,
+            outDir,
+            port,
+            open: !opts.noOpen,
+            template: opts.template,
+            ai: !!opts.ai,
+            appUrl: app?.url,
+            onGenerated: async () => {
+                if (app)
+                    await app.syncDeps();
+                else {
+                    app = await startAppServer({ outDir, port: appPort, log });
+                    log(`  app:      ${app.url} (started after first save)`);
+                }
+            },
+        });
+        return;
+    }
     // --- visual designer -----------------------------------------------------
     if (cmd === 'designer' && !opts.help) {
         await startDesignerServer({
@@ -129,10 +349,48 @@ async function main() {
             port: Number.isFinite(opts.port) ? opts.port : 4321,
             open: !opts.noOpen,
             template: opts.template,
+            ai: !!opts.ai,
         });
         // Keep the process alive; the server holds the event loop until Ctrl+C.
         return;
     }
+    // --- deploy --------------------------------------------------------------
+    if (cmd === 'deploy' && !opts.help) {
+        const read = (p) => io.readFile(p);
+        const resolution = resolveDeployTarget({
+            flag: opts.target,
+            configJson: await read('studio.config.json'),
+            svelteConfig: (await read('svelte.config.js')) ?? (await read('svelte.config.ts')),
+        });
+        if (!resolution.ok) {
+            process.stderr.write(`deploy: ${resolution.reason}\n`);
+            process.exit(1);
+        }
+        const plan = deployCommands(resolution.provider);
+        process.stdout.write(`Deploying to ${plan.provider} (from ${resolution.source === 'flag' ? '--target' : resolution.source === 'config' ? 'studio.config.json' : 'svelte.config.js adapter'}).\n`);
+        // Preflight: env keys the app declares but the local .env doesn't set.
+        const missing = missingEnvKeys(await read('.env.example'), await read('.env'));
+        if (missing.length)
+            process.stdout.write(`! Unset env keys (set them on the host too): ${missing.join(', ')}\n`);
+        for (const note of plan.notes)
+            process.stdout.write(`  ${note}\n`);
+        const commands = [plan.build, ...(plan.deploy ? [plan.deploy] : [])];
+        if (opts.dryRun) {
+            process.stdout.write(commands.map((c) => `> ${c}\n`).join(''));
+            return;
+        }
+        for (const command of commands) {
+            process.stdout.write(`\n> ${command}\n`);
+            const res = spawnSync(command, { stdio: 'inherit', shell: true });
+            if (res.status !== 0) {
+                if (command !== plan.build) {
+                    process.stderr.write(`deploy: "${command}" failed. If the provider CLI isn't set up yet, log in first (see the note above) and re-run.\n`);
+                }
+                process.exit(res.status ?? 1);
+            }
+        }
+        return;
+    }
     if (cmd !== 'add' || opts.help) {
         process.stdout.write(HELP);
         process.exit(opts.help || !cmd ? 0 : 1);
@@ -147,29 +405,10 @@ async function main() {
         // the user - they never need to know `pg`/`mysql2`/etc. must be present
         // before --db works (mirrors the designer's "Install driver" flow).
         const cwd = process.cwd();
-        if (!isDriverInstalled(opts.db, cwd)) {
-            const driver = DRIVER_FOR[opts.db];
-            process.stdout.write(`Installing ${driver} (required for --db ${opts.db})...\n`);
-            const result = await installDriver(opts.db, cwd);
-            if (!result.ok) {
-                process.stderr.write(`svgrid-studio: could not install "${driver}" automatically.\n${result.output}\n` +
-                    `Run \`${result.manager} install ${driver}\` yourself and try again.\n`);
-                process.exit(1);
-            }
-            process.stdout.write(`Installed ${driver}.\n`);
-            // The install child process can report success before the new module is
-            // reliably resolvable (seen on Windows - antivirus/file-sync tools can
-            // briefly hold the just-written files). Poll rather than racing straight
-            // into connect(), which would resolve the driver too early and crash.
-            const deadline = Date.now() + 5000;
-            while (!isDriverInstalled(opts.db, cwd) && Date.now() < deadline) {
-                await new Promise((r) => setTimeout(r, 200));
-            }
-            if (!isDriverInstalled(opts.db, cwd)) {
-                process.stderr.write(`svgrid-studio: installed "${driver}" but it's still not resolvable from this directory.\n` +
-                    `Something (antivirus, a file-sync tool) may be holding a lock on the new files. Try running the command again.\n`);
-                process.exit(1);
-            }
+        const driver = await ensureDriverInstalled(opts.db, cwd, (l) => process.stdout.write(l + '\n'));
+        if (!driver.ok) {
+            process.stderr.write(`svgrid-studio: ${driver.message}\n`);
+            process.exit(1);
         }
         const execute = await connect(opts.db, opts.url);
         // A dialect dataSource emits a fully-connected +server.ts (driver + DATABASE_URL);

package/dist/copilot.js

@@ -0,0 +1,43 @@
+/**
+ * Copilot backend for the CLI designer (`svgrid-studio designer --ai`): calls
+ * Anthropic's Messages API with the request built by the tested enterprise core
+ * and returns the validated, serialized project. Dependency-free by design -
+ * a plain fetch, no SDK - so the CLI keeps running on bare Node. The API key
+ * stays server-side (read from ANTHROPIC_API_KEY by the designer server).
+ */
+import { buildCopilotMessages, projectFromModelText, parseProject, serializeProject } from '@svgrid/enterprise/studio';
+const API_URL = 'https://api.anthropic.com/v1/messages';
+/** Overridable for teams pinning a model (SVGRID_COPILOT_MODEL). */
+const DEFAULT_MODEL = 'claude-sonnet-5';
+/** One copilot round: instruction + current project JSON -> updated project JSON. */
+export async function runCopilot(prompt, projectJson, opts) {
+    const project = parseProject(projectJson);
+    const { system, messages } = buildCopilotMessages(prompt, project);
+    const doFetch = opts.fetchImpl ?? fetch;
+    const res = await doFetch(API_URL, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-api-key': opts.apiKey,
+            'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+            model: opts.model ?? process.env.SVGRID_COPILOT_MODEL ?? DEFAULT_MODEL,
+            max_tokens: 32000,
+            system,
+            messages,
+        }),
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        throw new Error(`Anthropic API ${res.status}: ${detail.slice(0, 300)}`);
+    }
+    const body = (await res.json());
+    const text = (body.content ?? [])
+        .filter((c) => c.type === 'text')
+        .map((c) => c.text ?? '')
+        .join('');
+    if (!text)
+        throw new Error('Anthropic API returned no text content.');
+    return serializeProject(projectFromModelText(text));
+}

package/dist/designer-server.js

@@ -15,9 +15,11 @@ 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 { createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { createProject, parseProject, serializeProject, introspectDatabase, listDatabaseTables, probeConnection, linkRelationLabels, buildConnectionString, getSampleApp, skipUserOwned, } from '@svgrid/enterprise/studio';
+import { parseProject, serializeProject, introspectDatabase, listDatabaseTables, probeConnection, linkRelationLabels, buildConnectionString, getSampleApp, starterProject as buildStarterProject, skipUserOwned, } from '@svgrid/enterprise/studio';
 import { connect } from './db-connect.js';
+import { runCopilot } from './copilot.js';
 import { DRIVER_FOR, installDriver, isDriverInstalled } from './driver-install.js';
 const MIME = {
     '.html': 'text/html; charset=utf-8',
@@ -32,6 +34,21 @@ const MIME = {
     '.woff2': 'font/woff2',
     '.map': 'application/json; charset=utf-8',
 };
+/** Quote a SQL identifier for the dialect (doubling the closing quote char). */
+function quoteIdent(dialect, name) {
+    if (dialect === 'mysql')
+        return '`' + name.replace(/`/g, '``') + '`';
+    if (dialect === 'mssql')
+        return '[' + name.replace(/]/g, ']]') + ']';
+    return '"' + name.replace(/"/g, '""') + '"'; // postgres / supabase / sqlite
+}
+/** A read-only preview SELECT for one table (optionally schema-qualified). No
+ *  params - it's a fixed `SELECT * ... LIMIT n` (MSSQL uses `TOP n`). */
+function buildPreviewSql(dialect, table, schema, limit) {
+    const t = schema ? `${quoteIdent(dialect, schema)}.${quoteIdent(dialect, table)}` : quoteIdent(dialect, table);
+    const n = Math.max(1, Math.min(200, Math.floor(limit)));
+    return dialect === 'mssql' ? `SELECT TOP ${n} * FROM ${t}` : `SELECT * FROM ${t} LIMIT ${n}`;
+}
 /** 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'],
@@ -50,26 +67,16 @@ function resolveDesignerDir() {
     }
     return dir;
 }
-/** The project a fresh session opens with: a chosen sample app (`--template`), or
- *  a minimal tasks starter. */
+/** The project a fresh session opens with: a chosen sample app (`--template`), or the
+ *  default enterprise-ready Customers CRUD showcase (rich grid + export + popup form,
+ *  seeded) - so the first screen is a complete, generate-and-copy-ready SvGrid app. */
 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' });
+    return buildStarterProject();
 }
 function send(res, status, body, type = 'application/json; charset=utf-8') {
     res.writeHead(status, { 'content-type': type });
@@ -95,8 +102,24 @@ function serveStatic(res, dir, urlPath) {
     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) {
+/** Write the generated app bundle to disk and add any runtime deps it imports.
+ *
+ *  Clobber guard: `.studio/manifest.json` records the hash of every file Studio
+ *  last wrote. On regenerate, a file the USER has since edited (disk differs from
+ *  the manifest) gets the new version written as `<file>.new` + reported as a
+ *  conflict, instead of silently overwriting their work. Files Studio wrote and
+ *  nobody touched are overwritten as before. */
+export async function writeBundle(outDir, files) {
+    const manifestPath = join(outDir, '.studio', 'manifest.json');
+    let manifest = {};
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch {
+        /* first generate (or pre-manifest project) - guard activates from now on */
+    }
+    const sha = (s) => createHash('sha256').update(s).digest('hex');
+    const conflicts = [];
     let written = 0;
     for (const f of files) {
         const full = join(outDir, f.path);
@@ -105,10 +128,30 @@ async function writeBundle(outDir, files) {
         // the make-or-break round-trip guarantee. See HANDLERS-DESIGN.md.
         if (skipUserOwned(f, existsSync(full)))
             continue;
+        const newHash = sha(f.contents);
+        if (existsSync(full)) {
+            const onDisk = await readFile(full, 'utf8').catch(() => null);
+            const diskHash = onDisk == null ? null : sha(onDisk);
+            if (diskHash === newHash) {
+                manifest[f.path] = newHash; // already identical - nothing to write
+                continue;
+            }
+            const lastGenerated = manifest[f.path];
+            if (lastGenerated !== undefined && diskHash !== null && diskHash !== lastGenerated) {
+                // Locally modified since the last generate AND the regenerated content
+                // differs: park it next to the user's version instead of clobbering.
+                await writeFile(full + '.new', f.contents);
+                conflicts.push(f.path);
+                continue;
+            }
+        }
         await mkdir(dirname(full), { recursive: true });
         await writeFile(full, f.contents);
+        manifest[f.path] = newHash;
         written++;
     }
+    await mkdir(dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
     const allSource = files.map((f) => f.contents).join('\n');
     const pkgPath = join(outDir, 'package.json');
     if (existsSync(pkgPath)) {
@@ -128,7 +171,7 @@ async function writeBundle(outDir, files) {
             // leave package.json untouched if it isn't valid JSON
         }
     }
-    return written;
+    return { written, conflicts };
 }
 /** Best-effort open the default browser (no dependency). */
 function openBrowser(url) {
@@ -152,9 +195,33 @@ export async function startDesignerServer(opts) {
             send(res, 500, JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
         });
     });
+    // Copilot is live only when BOTH the flag and the key are present; the SPA
+    // probes /api/capabilities and only then wires (and shows) the Copilot button.
+    const copilotKey = process.env.ANTHROPIC_API_KEY;
+    const copilotOn = !!opts.ai && !!copilotKey;
     async function handle(req, res) {
         const url = req.url ?? '/';
         const path = url.split('?')[0];
+        if (path === '/api/capabilities' && req.method === 'GET') {
+            send(res, 200, JSON.stringify({ copilot: copilotOn, ...(opts.appUrl ? { appUrl: opts.appUrl } : {}) }));
+            return;
+        }
+        if (path === '/api/copilot' && req.method === 'POST') {
+            if (!copilotOn) {
+                send(res, 404, JSON.stringify({ error: 'Copilot is not enabled. Start with --ai and set ANTHROPIC_API_KEY.' }));
+                return;
+            }
+            const body = await readBody(req);
+            const { prompt, project } = JSON.parse(body);
+            if (!prompt || !project) {
+                send(res, 400, JSON.stringify({ error: 'prompt and project are required' }));
+                return;
+            }
+            log(`  copilot: ${prompt.slice(0, 80)}`);
+            const updated = await runCopilot(prompt, project, { apiKey: copilotKey });
+            send(res, 200, updated);
+            return;
+        }
         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,
@@ -179,9 +246,18 @@ export async function startDesignerServer(opts) {
                 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 }));
+            const { written, conflicts } = await writeBundle(outDir, files);
+            log(`  generated ${written} files -> ${outDir}`);
+            if (conflicts.length) {
+                log(`  ! ${conflicts.length} file(s) were edited by hand since the last generate - the new`);
+                log(`    version was written NEXT TO yours as "<file>.new" (merge or replace, then delete it):`);
+                for (const c of conflicts)
+                    log(`    - ${c}  ->  ${c}.new`);
+            }
+            // `studio dev`: give the app-server loop a chance to install newly added
+            // deps + restart; plain file rewrites are picked up by Vite's HMR.
+            await opts.onGenerated?.();
+            send(res, 200, JSON.stringify({ ok: true, count: written, conflicts, outDir }));
             return;
         }
         // Assemble a connection string from guided-form fields (host/port/user/...).
@@ -249,6 +325,23 @@ export async function startDesignerServer(opts) {
                 }
                 return;
             }
+            if (action === 'preview') {
+                // "Preview data": run a real SELECT so the designer canvas shows the user's
+                // actual rows (the SQL equivalent of the Supabase/REST live preview).
+                const table = Array.isArray(reqBody.tables) ? reqBody.tables[0] : undefined;
+                if (!table) {
+                    send(res, 400, JSON.stringify({ error: 'a table is required for preview' }));
+                    return;
+                }
+                try {
+                    const rows = await execute(buildPreviewSql(dialect, table, reqBody.schema, 25), []);
+                    send(res, 200, JSON.stringify({ rows }));
+                }
+                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 = [];
@@ -297,6 +390,10 @@ export async function startDesignerServer(opts) {
     log(`\n  SvGrid Studio designer running at ${url}`);
     log(`  config:  ${configPath}`);
     log(`  output:  ${outDir}`);
+    if (copilotOn)
+        log(`  copilot: ON (Anthropic)`);
+    else if (opts.ai)
+        log(`  copilot: OFF - --ai was passed but ANTHROPIC_API_KEY is not set`);
     log(`  (edits auto-save; "Save to folder" writes the app. Ctrl+C to stop.)\n`);
     if (opts.open)
         openBrowser(url);

package/dist/dev.js

@@ -0,0 +1,125 @@
+/**
+ * `svgrid-studio dev` - the live loop: the visual designer AND the real generated
+ * app's Vite dev server running side by side. Designer saves write real files
+ * into the app folder (targeted, hash-guarded writes), Vite picks them up as
+ * HMR - so the designer edits the actual running app, not a simulation.
+ *
+ * Dependency-free like the rest of the CLI: node:child_process + the existing
+ * package-manager/driver plumbing.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { emitStudioAppBundle, parseProject } from '@svgrid/enterprise/studio';
+import { readFile } from 'node:fs/promises';
+import { writeBundle } from './designer-server.js';
+import { detectPackageManager } from './driver-install.js';
+const isWin = process.platform === 'win32';
+/** Ensure the folder holds a generated app; generate from studio.config.json when
+ *  it doesn't. Returns false when there's nothing to run yet (no app, no config). */
+export async function ensureApp(outDir, configPath, log) {
+    if (existsSync(join(outDir, 'package.json')))
+        return true;
+    if (!existsSync(configPath))
+        return false;
+    const project = parseProject(await readFile(configPath, 'utf8'));
+    await mkdir(outDir, { recursive: true });
+    const { written } = await writeBundle(outDir, emitStudioAppBundle(project));
+    log(`  generated the app from ${configPath} (${written} files)`);
+    return true;
+}
+/** Deps declared in the app's package.json that aren't installed yet. Includes
+ *  devDependencies - `vite`/`svelte-kit` live there and `dev` can't run without
+ *  them (a wiped-then-partially-restored node_modules is a real scenario). */
+export function missingDeps(outDir) {
+    try {
+        const req = createRequire(join(resolve(outDir), 'package.json'));
+        const pkg = req('./package.json');
+        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).filter((dep) => {
+            try {
+                req.resolve(join(dep, 'package.json'));
+                return false;
+            }
+            catch {
+                try {
+                    req.resolve(dep);
+                    return false;
+                }
+                catch {
+                    return true;
+                }
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function install(outDir, log) {
+    const pm = detectPackageManager(outDir);
+    log(`  installing dependencies (${pm} install)...`);
+    const res = spawnSync(`${pm} install`, { cwd: outDir, stdio: 'inherit', shell: true });
+    if (res.status !== 0)
+        throw new Error(`${pm} install failed (exit ${res.status ?? 'signal'})`);
+}
+function spawnVite(outDir, port, log) {
+    const pm = detectPackageManager(outDir);
+    // `-- --port` threads through the package script to vite; strictPort so a
+    // taken port errors loudly instead of silently drifting to another one.
+    const child = spawn(`${pm} run dev -- --port ${port} --strictPort`, { cwd: outDir, shell: true });
+    const prefix = (data) => {
+        for (const line of String(data).split(/\r?\n/))
+            if (line.trim())
+                log(`  [app] ${line}`);
+    };
+    child.stdout?.on('data', prefix);
+    child.stderr?.on('data', prefix);
+    return child;
+}
+/** Kill the dev-server process tree (shell:true leaves grandchildren on Windows). */
+function killTree(child) {
+    if (child.pid == null)
+        return;
+    if (isWin)
+        spawnSync(`taskkill /pid ${child.pid} /T /F`, { shell: true, stdio: 'ignore' });
+    else
+        child.kill('SIGTERM');
+}
+/** The `npm run dev` launcher must actually exist - a package can resolve while
+ *  its .bin shim is gone (partially wiped node_modules), which fails with a
+ *  cryptic "'vite' is not recognized". */
+function viteBinMissing(outDir) {
+    const bin = join(outDir, 'node_modules', '.bin');
+    return !existsSync(join(bin, 'vite')) && !existsSync(join(bin, 'vite.cmd')) && !existsSync(join(bin, 'vite.CMD'));
+}
+/** Start the generated app's dev server (installing first when needed). */
+export async function startAppServer(opts) {
+    const log = opts.log ?? ((l) => process.stdout.write(l + '\n'));
+    const outDir = resolve(opts.outDir);
+    if (!existsSync(join(outDir, 'node_modules')) || viteBinMissing(outDir) || missingDeps(outDir).length)
+        install(outDir, log);
+    let child = spawnVite(outDir, opts.port, log);
+    let stopped = false;
+    child.on('exit', (code) => {
+        if (!stopped && code !== 0 && code != null)
+            log(`  [app] dev server exited with code ${code}`);
+    });
+    return {
+        url: `http://localhost:${opts.port}`,
+        async syncDeps() {
+            const missing = missingDeps(outDir);
+            if (!missing.length)
+                return; // nothing new - the running server HMRs the file writes
+            log(`  new dependenc${missing.length === 1 ? 'y' : 'ies'} (${missing.join(', ')}) - installing + restarting the app server...`);
+            killTree(child);
+            install(outDir, log);
+            child = spawnVite(outDir, opts.port, log);
+        },
+        stop() {
+            stopped = true;
+            killTree(child);
+        },
+    };
+}

package/dist/driver-install.js

@@ -61,6 +61,42 @@ export function isDriverInstalled(dialect, cwd) {
         return false;
     }
 }
+/**
+ * Make sure the dialect's driver is installed and actually resolvable, installing
+ * it if needed. Shared by `add --db` and the guided `init`, so a user connecting
+ * to Postgres never has to know `pg` must be present first.
+ *
+ * Never rejects: reports `{ ok: false, message }` the caller can print.
+ */
+export async function ensureDriverInstalled(dialect, cwd, log = () => { }) {
+    if (isDriverInstalled(dialect, cwd))
+        return { ok: true };
+    const driver = DRIVER_FOR[dialect];
+    log(`Installing ${driver} (needed to connect to ${dialect})...`);
+    const result = await installDriver(dialect, cwd);
+    if (!result.ok) {
+        return {
+            ok: false,
+            message: `Could not install "${driver}" automatically.\n${result.output}\nRun \`${result.manager} install ${driver}\` yourself and try again.`,
+        };
+    }
+    log(`Installed ${driver}.`);
+    // The install child process can report success before the new module is
+    // reliably resolvable (seen on Windows - antivirus/file-sync tools can briefly
+    // hold the just-written files). Poll rather than racing straight into
+    // connect(), which would resolve the driver too early and crash.
+    const deadline = Date.now() + 5000;
+    while (!isDriverInstalled(dialect, cwd) && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    if (!isDriverInstalled(dialect, cwd)) {
+        return {
+            ok: false,
+            message: `Installed "${driver}" but it's still not resolvable from this directory.\nSomething (antivirus, a file-sync tool) may be holding a lock on the new files. Try running the command again.`,
+        };
+    }
+    return { ok: true };
+}
 /**
  * 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

package/package.json

@@ -4,14 +4,14 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "0.2.0",
+  "version": "0.4.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",
+    "url": "git+https://github.com/sv-grid/sv-grid.git",
     "directory": "packages/studio"
   },
   "type": "module",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@svgrid/enterprise": "^2.2.0"
+    "@svgrid/enterprise": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",
@@ -36,8 +36,27 @@
   "engines": {
     "node": ">=18"
   },
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "sveltekit",
+    "crud",
+    "scaffold",
+    "codegen",
+    "drizzle",
+    "prisma",
+    "admin panel",
+    "low-code",
+    "data app",
+    "data grid",
+    "datagrid",
+    "studio",
+    "svgrid",
+    "sv-grid"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test:types": "tsc -p tsconfig.json --noEmit"
+    "test:types": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint ./src"
   }
 }