turbine-orm 0.36.1 → 0.37.0

package/README.md

@@ -614,7 +614,7 @@ Commands:
   seed                         Run seed file
   status                       Show database schema summary
   doctor                       Check relations for missing FK indexes (--fix emits migration)
-  studio                       Launch local Studio web UI (read-only; --write opts in to single-row writes)
+  studio                       Launch local Studio web UI (read-only; --write for writes, --demo for a sample DB)
   mcp                          Start read-only MCP server over JSON-RPC stdio
   observe                      Launch local metrics dashboard (requires TURBINE_OBSERVE_URL)
 
@@ -688,6 +688,8 @@ DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine studio
 npx turbine studio --port 5173 --host 127.0.0.1 --no-open
 ```
 
+**Try it without a database.** `npx turbine-orm@latest studio --demo` boots Studio against a seeded, in-memory sample database (users, posts, comments, orgs) with no `DATABASE_URL` and no extra dependency, backed by Turbine's own SQLite engine over `node:sqlite` (Node 22.5+). An in-UI switcher flips the three modes live (Read-only / Show PII / Write), so you can feel PII redaction and the write flow back to back. Writes genuinely apply to the in-memory store but nothing is ever saved: every launch starts fresh.
+
 **Features**
 
 - **Query / Data / Schema tabs.** Compose queries visually, browse rows, and inspect tables and relations.

package/dist/cjs/cli/index.js

@@ -15,7 +15,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
- *   turbine studio                — Launch local read-only web UI
+ *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
@@ -190,6 +190,9 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--show-pii':
                 result.showPii = true;
                 break;
+            case '--demo':
+                result.demo = true;
+                break;
             default:
                 if (!arg.startsWith('-')) {
                     result.positional.push(arg);
@@ -1503,7 +1506,10 @@ function isLoopbackHost(host) {
 // ---------------------------------------------------------------------------
 async function cmdStudio(args, config) {
     (0, ui_js_1.banner)();
-    const url = requireUrl(config);
+    const demo = args.demo === true;
+    // Demo mode is self-contained (seeded in-memory database), so it never needs
+    // a DATABASE_URL. The placeholder is only used for display.
+    const url = demo ? 'demo://in-memory' : requireUrl(config);
     const port = args.port ?? 4983;
     const host = args.host ?? '127.0.0.1';
     const openBrowser = !args.noOpen;
@@ -1526,7 +1532,7 @@ async function cmdStudio(args, config) {
         console.log((0, ui_js_1.warn)(`Studio is binding to ${(0, ui_js_1.yellow)(host)} — this is NOT loopback. ` +
             `Anyone on your network who can reach this port + guess the session token can read your database.`));
     }
-    const spinner = new ui_js_1.Spinner('Introspecting database').start();
+    const spinner = new ui_js_1.Spinner(demo ? 'Seeding demo dataset' : 'Introspecting database').start();
     let studio;
     try {
         studio = await (0, studio_js_1.startStudio)({
@@ -1537,39 +1543,60 @@ async function cmdStudio(args, config) {
             openBrowser,
             include: config.include.length ? config.include : undefined,
             exclude: config.exclude.length ? config.exclude : undefined,
+            // Demo boots read-only + PII redacted; the flags are ignored in demo mode
+            // (the in-UI switcher controls modes live).
             write: args.write === true,
             showPii: args.showPii === true,
+            demo,
         });
-        spinner.succeed(`Studio is running`);
+        spinner.succeed(demo ? 'Demo Studio is running' : 'Studio is running');
     }
     catch (err) {
         spinner.fail(`Failed to start Studio: ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
-    // Loud startup warnings for the opt-in modes that widen Studio's surface.
-    if (args.write) {
+    if (demo) {
+        (0, ui_js_1.newline)();
+        console.log((0, ui_js_1.box)([
+            `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)('DEMO MODE (seeded in-memory sample database)')}`,
+            '',
+            `  ${(0, ui_js_1.cyan)('URL:')}    ${(0, ui_js_1.bold)(studio.url)}`,
+            `  ${(0, ui_js_1.cyan)('Data:')}   seeded sample dataset (users, posts, comments, orgs)`,
+            `  ${(0, ui_js_1.cyan)('Modes:')}  switch Read-only / Show PII / Write live from inside the UI`,
+            '',
+            (0, ui_js_1.dim)('Nothing you do here is saved anywhere. The database lives only in'),
+            (0, ui_js_1.dim)('memory: every launch starts fresh and restarts reset all edits.'),
+            (0, ui_js_1.dim)('Open the URL above (it carries a one-time session token).'),
+            (0, ui_js_1.dim)('Press Ctrl+C to stop.'),
+        ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio · demo')), padding: 1 }));
         (0, ui_js_1.newline)();
-        console.log((0, ui_js_1.warn)('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
-            `${(0, ui_js_1.redactUrl)(url)}. Every change is committed directly to your database.`));
     }
-    if (args.showPii) {
+    else {
+        // Loud startup warnings for the opt-in modes that widen Studio's surface.
+        if (args.write) {
+            (0, ui_js_1.newline)();
+            console.log((0, ui_js_1.warn)('WRITE MODE is ON. Studio can update, insert, and delete single rows in ' +
+                `${(0, ui_js_1.redactUrl)(url)}. Every change is committed directly to your database.`));
+        }
+        if (args.showPii) {
+            (0, ui_js_1.newline)();
+            console.log((0, ui_js_1.warn)('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
+        }
+        (0, ui_js_1.newline)();
+        console.log((0, ui_js_1.box)([
+            `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
+            '',
+            `  ${(0, ui_js_1.cyan)('URL:')}    ${(0, ui_js_1.bold)(studio.url)}`,
+            `  ${(0, ui_js_1.cyan)('Schema:')} ${config.schema}`,
+            `  ${(0, ui_js_1.cyan)('DB:')}     ${(0, ui_js_1.redactUrl)(url)}`,
+            `  ${(0, ui_js_1.cyan)('Mode:')}   ${args.write ? (0, ui_js_1.red)('read-write (single-row)') : 'read-only'}`,
+            '',
+            (0, ui_js_1.dim)('Open the URL above in your browser. It includes a one-time session'),
+            (0, ui_js_1.dim)('token that gets set as an HttpOnly cookie on first load.'),
+            (0, ui_js_1.dim)('Press Ctrl+C to stop.'),
+        ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio')), padding: 1 }));
         (0, ui_js_1.newline)();
-        console.log((0, ui_js_1.warn)('--show-pii is ON. PII-tagged column values are shown UNREDACTED in Studio.'));
     }
-    (0, ui_js_1.newline)();
-    console.log((0, ui_js_1.box)([
-        `${(0, ui_js_1.bold)('Turbine Studio')}  ${(0, ui_js_1.dim)(args.write ? 'local UI (WRITE MODE)' : 'local read-only UI')}`,
-        '',
-        `  ${(0, ui_js_1.cyan)('URL:')}    ${(0, ui_js_1.bold)(studio.url)}`,
-        `  ${(0, ui_js_1.cyan)('Schema:')} ${config.schema}`,
-        `  ${(0, ui_js_1.cyan)('DB:')}     ${(0, ui_js_1.redactUrl)(url)}`,
-        `  ${(0, ui_js_1.cyan)('Mode:')}   ${args.write ? (0, ui_js_1.red)('read-write (single-row)') : 'read-only'}`,
-        '',
-        (0, ui_js_1.dim)('Open the URL above in your browser. It includes a one-time session'),
-        (0, ui_js_1.dim)('token that gets set as an HttpOnly cookie on first load.'),
-        (0, ui_js_1.dim)('Press Ctrl+C to stop.'),
-    ].join('\n'), { title: (0, ui_js_1.bold)((0, ui_js_1.cyan)('Studio')), padding: 1 }));
-    (0, ui_js_1.newline)();
     // Wait forever until SIGINT/SIGTERM, then dispose cleanly.
     await new Promise((resolve) => {
         const shutdown = async () => {
@@ -1850,7 +1877,7 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
     console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Check relations for missing FK indexes ${(0, ui_js_1.dim)('(--fix emits migration)')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI ${(0, ui_js_1.dim)('(--write opts in to single-row writes)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI ${(0, ui_js_1.dim)('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);
     (0, ui_js_1.newline)();
@@ -1876,6 +1903,7 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--allow-remote')}       Allow non-loopback --host ${(0, ui_js_1.dim)('(refused without this flag)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--write')}              Studio: enable single-row update/insert/delete ${(0, ui_js_1.dim)('(read-only by default)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--show-pii')}           Studio: show PII-tagged values unredacted ${(0, ui_js_1.dim)('(redacted by default)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--demo')}               Studio: launch with a seeded in-memory sample database ${(0, ui_js_1.dim)('(no DATABASE_URL needed; nothing is saved)')}`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Config file:')}`);
     console.log(`    ${(0, ui_js_1.dim)('Create')} ${(0, ui_js_1.cyan)('turbine.config.ts')} ${(0, ui_js_1.dim)('with')} ${(0, ui_js_1.cyan)('npx turbine init')}`);

package/dist/cjs/cli/studio-demo.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * turbine-orm CLI: Studio demo mode (`turbine studio --demo`)
+ *
+ * Boots Studio with NO database and NO DATABASE_URL: a baked-in, seeded sample
+ * dataset served from an in-memory engine. It is the "feel the product in 10
+ * seconds" experience: read mode, PII redaction, and the single-row write flow,
+ * all safely fake.
+ *
+ * The store is backed by Turbine's OWN SQLite engine over `node:sqlite`'s
+ * `:memory:` database (a built-in on Node >= 22.5, zero new dependency). Because
+ * `:memory:` is per-handle, the store dies with the process and every launch
+ * starts pristine: writes genuinely apply (edits stick, a refresh shows them)
+ * but nothing is ever persisted anywhere.
+ *
+ * This module lives under `src/cli/` (coverage-excluded, never imported by
+ * library code) and reuses `SqlitePool` + `sqliteDialect` from `../sqlite.js`;
+ * it never writes its own SQL evaluator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEMO_SCHEMA = void 0;
+exports.createDemoContext = createDemoContext;
+const node_module_1 = require("node:module");
+const sqlite_js_1 = require("../sqlite.js");
+/**
+ * Load `node:sqlite`'s `DatabaseSync` constructor, throwing a clear,
+ * demo-specific message on older Node. Kept lazy (called only when a demo
+ * context is actually created) so `import`ing this module never crashes the CLI
+ * on Node < 22.5.
+ */
+function loadDatabaseSync() {
+    let ctor;
+    try {
+        const req = (0, node_module_1.createRequire)(process.cwd());
+        ctor = req('node:sqlite').DatabaseSync;
+    }
+    catch {
+        ctor = undefined;
+    }
+    if (typeof ctor !== 'function') {
+        throw new Error('studio --demo needs Node 22.5+ (uses the built-in node:sqlite engine)');
+    }
+    return ctor;
+}
+/** Map a demo column's Postgres-flavored type to a TypeScript type string. */
+function demoTsType(pgType, nullable) {
+    let base;
+    if (/int|serial/i.test(pgType))
+        base = 'number';
+    else if (/bool/i.test(pgType))
+        base = 'boolean';
+    else if (/timestamp|date/i.test(pgType))
+        base = 'Date';
+    else
+        base = 'string';
+    return nullable ? `${base} | null` : base;
+}
+function demoColumn(spec) {
+    const nullable = spec.nullable === true;
+    return {
+        name: spec.name,
+        field: spec.field,
+        dialectType: spec.pgType,
+        pgType: spec.pgType,
+        tsType: demoTsType(spec.pgType, nullable),
+        nullable,
+        hasDefault: spec.hasDefault ?? spec.isGenerated ?? false,
+        isGenerated: spec.isGenerated === true,
+        pii: spec.pii === true,
+        isArray: false,
+        pgArrayType: 'text[]',
+    };
+}
+function demoTable(name, columnSpecs, relations = {}) {
+    const columns = columnSpecs.map(demoColumn);
+    const columnMap = {};
+    const reverseColumnMap = {};
+    const dateColumns = new Set();
+    const pgTypes = {};
+    const allColumns = [];
+    for (const col of columns) {
+        columnMap[col.field] = col.name;
+        reverseColumnMap[col.name] = col.field;
+        pgTypes[col.name] = col.pgType;
+        allColumns.push(col.name);
+        if (/timestamp|date/i.test(col.pgType))
+            dateColumns.add(col.name);
+    }
+    return {
+        name,
+        columns,
+        columnMap,
+        reverseColumnMap,
+        dateColumns,
+        dialectTypes: pgTypes,
+        pgTypes,
+        allColumns,
+        primaryKey: ['id'],
+        uniqueColumns: [['id']],
+        relations,
+        indexes: [],
+    };
+}
+/**
+ * The seeded sample schema. Four tables with realistic relations; `email` and
+ * `phone` are tagged `pii` so Studio's redaction path is exercised out of the
+ * box.
+ */
+exports.DEMO_SCHEMA = {
+    tables: {
+        users: demoTable('users', [
+            { name: 'id', field: 'id', pgType: 'int4', isGenerated: true },
+            { name: 'name', field: 'name', pgType: 'text' },
+            { name: 'email', field: 'email', pgType: 'text', pii: true },
+            { name: 'phone', field: 'phone', pgType: 'text', nullable: true, pii: true },
+            { name: 'role', field: 'role', pgType: 'text' },
+            { name: 'created_at', field: 'createdAt', pgType: 'timestamptz' },
+        ], {
+            posts: {
+                type: 'hasMany',
+                name: 'posts',
+                from: 'users',
+                to: 'posts',
+                foreignKey: 'user_id',
+                referenceKey: 'id',
+            },
+        }),
+        posts: demoTable('posts', [
+            { name: 'id', field: 'id', pgType: 'int4', isGenerated: true },
+            { name: 'user_id', field: 'userId', pgType: 'int4' },
+            { name: 'title', field: 'title', pgType: 'text' },
+            { name: 'body', field: 'body', pgType: 'text' },
+            { name: 'published', field: 'published', pgType: 'bool' },
+            { name: 'created_at', field: 'createdAt', pgType: 'timestamptz' },
+        ], {
+            comments: {
+                type: 'hasMany',
+                name: 'comments',
+                from: 'posts',
+                to: 'comments',
+                foreignKey: 'post_id',
+                referenceKey: 'id',
+            },
+            author: {
+                type: 'belongsTo',
+                name: 'author',
+                from: 'posts',
+                to: 'users',
+                foreignKey: 'user_id',
+                referenceKey: 'id',
+            },
+        }),
+        comments: demoTable('comments', [
+            { name: 'id', field: 'id', pgType: 'int4', isGenerated: true },
+            { name: 'post_id', field: 'postId', pgType: 'int4' },
+            { name: 'user_id', field: 'userId', pgType: 'int4' },
+            { name: 'body', field: 'body', pgType: 'text' },
+            { name: 'created_at', field: 'createdAt', pgType: 'timestamptz' },
+        ], {
+            post: {
+                type: 'belongsTo',
+                name: 'post',
+                from: 'comments',
+                to: 'posts',
+                foreignKey: 'post_id',
+                referenceKey: 'id',
+            },
+            user: {
+                type: 'belongsTo',
+                name: 'user',
+                from: 'comments',
+                to: 'users',
+                foreignKey: 'user_id',
+                referenceKey: 'id',
+            },
+        }),
+        orgs: demoTable('orgs', [
+            { name: 'id', field: 'id', pgType: 'int4', isGenerated: true },
+            { name: 'name', field: 'name', pgType: 'text' },
+            { name: 'plan', field: 'plan', pgType: 'text' },
+        ]),
+    },
+    enums: {},
+};
+// ---------------------------------------------------------------------------
+// Deterministic seed data (hardcoded, no randomness)
+// ---------------------------------------------------------------------------
+/** A fixed base instant so every launch produces byte-identical timestamps. */
+const SEED_EPOCH = Date.UTC(2024, 0, 1, 9, 0, 0);
+const DAY_MS = 86_400_000;
+/** ISO timestamp `n` days after the seed epoch (deterministic, no `Date.now()`). */
+function seedTime(dayOffset) {
+    return new Date(SEED_EPOCH + dayOffset * DAY_MS).toISOString();
+}
+const USERS = [
+    { id: 1, name: 'Ada Lovelace', email: 'ada@example.com', phone: '+1-202-555-0101', role: 'admin' },
+    { id: 2, name: 'Grace Hopper', email: 'grace@example.com', phone: '+1-202-555-0102', role: 'admin' },
+    { id: 3, name: 'Alan Turing', email: 'alan@example.com', phone: '+1-202-555-0103', role: 'member' },
+    { id: 4, name: 'Katherine Johnson', email: 'katherine@example.com', phone: '+1-202-555-0104', role: 'member' },
+    { id: 5, name: 'Linus Torvalds', email: 'linus@example.com', phone: '+1-202-555-0105', role: 'member' },
+    { id: 6, name: 'Margaret Hamilton', email: 'margaret@example.com', phone: null, role: 'member' },
+    { id: 7, name: 'Dennis Ritchie', email: 'dennis@example.com', phone: '+1-202-555-0107', role: 'member' },
+    { id: 8, name: 'Barbara Liskov', email: 'barbara@example.com', phone: '+1-202-555-0108', role: 'viewer' },
+];
+const ORGS = [
+    { id: 1, name: 'Analytical Engines', plan: 'pro' },
+    { id: 2, name: 'Compiler Collective', plan: 'team' },
+    { id: 3, name: 'Kernel Works', plan: 'free' },
+];
+const POST_TOPICS = [
+    'Notes on the Analytical Engine',
+    'Debugging the first moth',
+    'On computable numbers',
+    'Orbital mechanics by hand',
+    'Why monolithic kernels win',
+    'The Apollo guidance software',
+    'A tour of the C language',
+    'Abstraction and specification',
+    'Loop invariants in practice',
+    'Sequential vs parallel search',
+];
+/** 20 deterministic posts spread across the 8 users. */
+const POSTS = Array.from({ length: 20 }, (_, i) => {
+    const id = i + 1;
+    const userId = (i % USERS.length) + 1;
+    return {
+        id,
+        userId,
+        title: `${POST_TOPICS[i % POST_TOPICS.length]} (part ${Math.floor(i / POST_TOPICS.length) + 1})`,
+        body: `A short sample body for post ${id}, written by user ${userId}. Everything here is fake demo data.`,
+        published: id % 4 !== 0,
+        createdAt: seedTime(id),
+    };
+});
+/** 40 deterministic comments (two per post), authored round-robin. */
+const COMMENTS = Array.from({ length: 40 }, (_, i) => {
+    const id = i + 1;
+    const postId = (i % POSTS.length) + 1;
+    const userId = ((i * 3) % USERS.length) + 1;
+    return {
+        id,
+        postId,
+        userId,
+        body: `Comment ${id} on post ${postId}. Nicely done. This is seeded demo content.`,
+        createdAt: seedTime(20 + id),
+    };
+});
+// ---------------------------------------------------------------------------
+// DDL + seeding
+// ---------------------------------------------------------------------------
+/** SQLite DDL for the demo tables. Types map cleanly onto SQLite affinities. */
+const DEMO_DDL = `
+CREATE TABLE orgs (
+  id    INTEGER PRIMARY KEY,
+  name  TEXT NOT NULL,
+  plan  TEXT NOT NULL
+);
+CREATE TABLE users (
+  id          INTEGER PRIMARY KEY,
+  name        TEXT NOT NULL,
+  email       TEXT NOT NULL,
+  phone       TEXT,
+  role        TEXT NOT NULL,
+  created_at  TEXT NOT NULL
+);
+CREATE TABLE posts (
+  id          INTEGER PRIMARY KEY,
+  user_id     INTEGER NOT NULL REFERENCES users(id),
+  title       TEXT NOT NULL,
+  body        TEXT NOT NULL,
+  published   INTEGER NOT NULL,
+  created_at  TEXT NOT NULL
+);
+CREATE TABLE comments (
+  id          INTEGER PRIMARY KEY,
+  post_id     INTEGER NOT NULL REFERENCES posts(id),
+  user_id     INTEGER NOT NULL REFERENCES users(id),
+  body        TEXT NOT NULL,
+  created_at  TEXT NOT NULL
+);
+`;
+function seedDemoData(db) {
+    const insOrg = db.prepare('INSERT INTO orgs (id, name, plan) VALUES (?, ?, ?)');
+    for (const o of ORGS)
+        insOrg.run(o.id, o.name, o.plan);
+    const insUser = db.prepare('INSERT INTO users (id, name, email, phone, role, created_at) VALUES (?, ?, ?, ?, ?, ?)');
+    for (const u of USERS)
+        insUser.run(u.id, u.name, u.email, u.phone, u.role, seedTime(u.id));
+    const insPost = db.prepare('INSERT INTO posts (id, user_id, title, body, published, created_at) VALUES (?, ?, ?, ?, ?, ?)');
+    for (const p of POSTS)
+        insPost.run(p.id, p.userId, p.title, p.body, p.published ? 1 : 0, p.createdAt);
+    const insComment = db.prepare('INSERT INTO comments (id, post_id, user_id, body, created_at) VALUES (?, ?, ?, ?, ?)');
+    for (const c of COMMENTS)
+        insComment.run(c.id, c.postId, c.userId, c.body, c.createdAt);
+}
+/**
+ * Open a fresh, seeded in-memory demo store and return the pool + metadata +
+ * dialect Studio needs. Each call yields an independent, pristine database
+ * (`:memory:` is per-handle), so demo launches never share state.
+ *
+ * @throws Error on Node < 22.5 (no built-in `node:sqlite`).
+ */
+function createDemoContext() {
+    const DatabaseSyncCtor = loadDatabaseSync();
+    const db = new DatabaseSyncCtor(':memory:');
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec(DEMO_DDL);
+    seedDemoData(db);
+    return { pool: new sqlite_js_1.SqlitePool(db), metadata: exports.DEMO_SCHEMA, dialect: sqlite_js_1.sqliteDialect };
+}