@svgrid/studio 0.3.0 → 0.5.0

package/README.md

@@ -19,8 +19,23 @@
 
 ---
 
-Scaffold a full CRUD screen for SvelteKit from a **live database** or a
-**Drizzle / Prisma schema** in **one command**.
+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)

package/dist/cli.js

@@ -12,10 +12,11 @@
  */
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 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, serializeProject, setEntityDataSource, summarizeVerify, } from '@svgrid/enterprise/studio';
+import { buildStudioBugReport, createProject, deployCommands, emitStudioAppBundle, emitStudioFragment, introspectDatabase, introspectOpenApi, isUserError, runtimeDeps, listDatabaseTables, missingEnvKeys, parseProject, resolveDeployTarget, resolveSchemas, runStudioAdd, runStudioAddApp, runStudioInit, sampleApps, serializeProject, setEntityDataSource, summarizeVerify, UserError, } 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 = {
@@ -35,44 +36,75 @@ const io = {
 function parse(args) {
     const out = {};
     const positional = [];
-    for (let i = 0; i < args.length; i++) {
+    /**
+     * Read the value that follows a flag. A missing or flag-shaped value used to
+     * come back as `undefined` and read as "not passed", so `--url` at the end of
+     * the line silently fell through to a different code path instead of saying
+     * what was wrong.
+     */
+    let i = 0;
+    const value = (flag) => {
+        const next = args[i + 1];
+        if (next === undefined || next.startsWith('-')) {
+            throw new UserError(`${flag} needs a value.`, 'Run `svgrid-studio --help` to see what each flag expects.');
+        }
+        i++;
+        return next;
+    };
+    for (i = 0; i < args.length; i++) {
         const a = args[i];
         if (a === '--from')
-            out.from = args[++i];
+            out.from = value(a);
         else if (a === '--table')
-            out.table = args[++i];
+            out.table = value(a);
         else if (a === '--route')
-            out.route = args[++i];
+            out.route = value(a);
         else if (a === '--api')
-            out.apiRoute = args[++i];
+            out.apiRoute = value(a);
         else if (a === '--sql')
             out.dataSource = 'sql';
         else if (a === '--db')
-            out.db = args[++i];
+            out.db = value(a);
         else if (a === '--url')
-            out.url = args[++i];
+            out.url = value(a);
         else if (a === '--all')
             out.all = true;
         else if (a === '--config')
-            out.config = args[++i];
+            out.config = value(a);
         else if (a === '--out')
-            out.outDir = args[++i];
+            out.outDir = value(a);
         else if (a === '--port')
-            out.port = Number(args[++i]);
+            out.port = Number(value(a));
         else if (a === '--template')
-            out.template = args[++i];
+            out.template = value(a);
         else if (a === '--no-open')
             out.noOpen = true;
         else if (a === '--target')
-            out.target = args[++i];
+            out.target = value(a);
         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]);
+            out.appPort = Number(value(a));
         else if (a === '--fragment')
             out.fragment = true;
+        else if (a === '--supabase-url')
+            out.supabaseUrl = value(a);
+        else if (a === '--supabase-key')
+            out.supabaseKey = value(a);
+        else if (a === '--dataset')
+            out.dataset = value(a);
+        else if (a === '--theme')
+            out.theme = value(a);
+        else if (a === '--dark')
+            out.dark = true;
+        else if (a === '--title')
+            out.title = value(a);
+        else if (a === '-f' || a === '--force')
+            out.force = true;
+        else if (a === '-y' || a === '--yes')
+            out.yes = true;
         else if (a === '-h' || a === '--help')
             out.help = true;
         else if (!a.startsWith('-'))
@@ -85,56 +117,161 @@ function parse(args) {
         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
-  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
-
-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)
-  --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
-  --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.
-
-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
+/**
+ * Every sample id, wrapped so the help stays readable. Built from the registry
+ * rather than a hand-kept list: a new sample used to be invisible here until
+ * someone remembered to update the sentence.
+ */
+function templateIds(width = 62) {
+    const lines = [];
+    let line = '';
+    for (const id of sampleApps.map((s) => s.id)) {
+        const next = line ? `${line} | ${id}` : id;
+        if (next.length > width) {
+            lines.push(line);
+            line = id;
+        }
+        else {
+            line = next;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines.join('\n                   ');
+}
+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
+  -f, --force      write into a folder that already holds another app
+
+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:
+                   ${templateIds()}
+  --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
+  --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.
+
+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 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)
@@ -144,6 +281,25 @@ 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 } : {}),
+            ...(opts.force ? { force: 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';
@@ -291,29 +447,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);
@@ -399,6 +536,14 @@ async function writeCrashReport(err) {
 }
 main().catch(async (err) => {
     process.stderr.write(`svgrid-studio: ${err instanceof Error ? err.message : String(err)}\n`);
+    // A mistyped connection string is not a bug. Only real crashes earn a report -
+    // otherwise ordinary fat-fingering ends with "report this on GitHub", which
+    // teaches people to distrust the message and file noise.
+    if (isUserError(err)) {
+        if (err.hint)
+            process.stderr.write(`  ${err.hint}\n`);
+        process.exit(1);
+    }
     try {
         await writeCrashReport(err);
     }

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,7 +4,7 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "0.3.0",
+  "version": "0.5.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>",
@@ -27,7 +27,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@svgrid/enterprise": "^2.3.0"
+    "@svgrid/enterprise": "^2.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",
@@ -56,6 +56,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test:types": "tsc -p tsconfig.json --noEmit"
+    "test:types": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint ./src"
   }
 }