schematic-pg 0.1.5 → 0.1.6

package/README.md

@@ -201,11 +201,12 @@ npx schematic-pg init my-app
 cd my-app
 ```
 
-Edit `app.schema`, then generate code and start the API:
+Edit `app.schema`, then start the full dev loop:
 
 ```bash
 make dev
-# → starts PostgreSQL, generates code, bootstraps the DB, and runs the dev server
+# → starts PostgreSQL, generates code, bootstraps the DB, runs the dev server,
+#   and watches app.schema for changes (regenerate + bootstrap + restart)
 # → http://localhost:3000
 ```
 
@@ -213,17 +214,22 @@ Or run each step individually:
 
 ```bash
 # Start PostgreSQL (PostGIS-enabled, matches .env defaults)
-docker compose up -d
+docker compose up -d --wait
 
-# Generate schema.sql + generated/ (db client, routes, policies, Zod schemas)
-npx schematic-pg generate
-
-# Apply DDL to the database and snapshot schema state
-npx schematic-pg db:bootstrap
-
-# Regenerate client + API and start the server
+# Generate, bootstrap, start server, and watch app.schema (default)
 npx schematic-pg dev
 # → http://localhost:3000
+
+# One-shot dev server without schema watching:
+npx schematic-pg dev --no-watch
+```
+
+Manual split when you need finer control:
+
+```bash
+npx schematic-pg generate
+npx schematic-pg db:bootstrap
+npx schematic-pg dev --no-watch
 ```
 
 The `init` command creates everything you need to get running:
@@ -233,7 +239,7 @@ The `init` command creates everything you need to get running:
 | `app.schema` | Starter schema (one `User` model) — edit this |
 | `.env` | `DATABASE_URL`, JWT settings |
 | `docker-compose.yml` | Local PostGIS PostgreSQL on `:5432` |
-| `Makefile` | `make dev` — docker compose + generate + db:bootstrap + dev |
+| `Makefile` | `make dev` — docker compose (with health wait) + `schematic-pg dev` |
 | `tsconfig.json` | TypeScript config for `generated/` and `src/routes/` |
 | `package.json` | `schematic-pg` + runtime deps (`hono`, `pg`, `zod`, …) |
 | `src/routes/health.ts` | Example custom route mounted at `/health` |
@@ -261,7 +267,7 @@ Generated code imports the runtime from the `schematic-pg` package (`schematic-p
 | `JWT_ROLE_CLAIM` | `role` | JWT claim mapped to `auth.role` |
 | `JWT_USER_ID_CLAIM` | `sub` | JWT claim mapped to `auth.user.id` |
 
-Set these in `.env` before running `db:bootstrap` or `dev`.
+Set these in `.env` before running `dev` or `db:bootstrap`.
 
 ---
 
@@ -289,13 +295,22 @@ Run `generate:client` before `generate:api` when using the split commands — ro
 ### Development server
 
 ```bash
-schematic-pg dev [schema]   # generate:client + generate:api, then start generated/app.ts
+schematic-pg dev [schema] [--no-watch]
 ```
 
+`dev` runs the full local loop:
+
+1. `generate` — writes `schema.sql` and `generated/*`
+2. `db:bootstrap` — waits for Postgres, applies DDL, snapshots schema state
+3. Starts `generated/app.ts`
+4. Watches `app.schema` (default) — on change, re-runs generate, bootstrap, and server restart
+
+Pass `--no-watch` for a one-shot run without file watching.
+
 Equivalent npm scripts in a project created by `init`:
 
 ```bash
-make dev           # docker compose up -d + generate + db:bootstrap + dev
+make dev           # docker compose up -d --wait + schematic-pg dev
 npm run dev        # schematic-pg dev
 npm run generate   # schematic-pg generate
 ```

package/dist/cli/db.js

@@ -5,6 +5,7 @@ import { applyPendingMigrations } from '../db/migrate.js';
 import { createMigration, getAppliedMigrationFilenames, listMigrationFiles } from '../db/migrations.js';
 import { snapshotExists } from '../db/schema-state.js';
 import { resolveSchemaPath } from './paths.js';
+import { waitForDatabase } from './wait-for-database.js';
 function parseDiffArgs(args) {
     let schemaPath = resolveSchemaPath();
     let name;
@@ -50,6 +51,7 @@ export async function runDbBootstrap(schemaPath) {
     const resolvedSchemaPath = resolveSchemaPath(schemaPath);
     const client = new DatabaseClient();
     try {
+        await waitForDatabase({ client });
         await bootstrapDatabase(resolvedSchemaPath, client);
         process.stdout.write(`Database bootstrapped from ${resolvedSchemaPath}\n`);
     }

package/dist/cli/dev.d.ts

@@ -1 +1 @@
-export declare function runDev(schemaPath?: string): Promise<void>;
+export declare function runDev(args?: string[]): Promise<void>;

package/dist/cli/dev.js

@@ -1,10 +1,150 @@
-import { execFileSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { watch } from 'node:fs';
 import path from 'node:path';
-import { generateApi, generateClient } from './generate.js';
-import { DEFAULT_OUTPUT_DIR } from './paths.js';
-export async function runDev(schemaPath) {
-    await generateClient(schemaPath);
-    await generateApi(schemaPath);
+import { runDbBootstrap } from './db.js';
+import { generateAll } from './generate.js';
+import { DEFAULT_OUTPUT_DIR, resolveSchemaPath } from './paths.js';
+const WATCH_DEBOUNCE_MS = 300;
+const SERVER_STOP_TIMEOUT_MS = 5000;
+function parseDevArgs(args) {
+    let schemaPath = resolveSchemaPath();
+    let watchSchema = true;
+    for (const arg of args) {
+        if (arg === '--no-watch') {
+            watchSchema = false;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            schemaPath = resolveSchemaPath(arg);
+        }
+    }
+    return { schemaPath, watchSchema };
+}
+function createDebouncer(fn, ms) {
+    let timer;
+    return () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void fn();
+        }, ms);
+    };
+}
+function startServer(appPath) {
+    return spawn(process.execPath, ['--import', 'tsx', appPath], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+    });
+}
+function stopServer(serverProcess) {
+    if (!serverProcess || serverProcess.exitCode !== null || serverProcess.killed) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        serverProcess.once('exit', () => resolve());
+        if (process.platform === 'win32') {
+            serverProcess.kill();
+        }
+        else {
+            serverProcess.kill('SIGTERM');
+        }
+        setTimeout(() => {
+            if (serverProcess.exitCode === null && !serverProcess.killed) {
+                serverProcess.kill('SIGKILL');
+            }
+        }, SERVER_STOP_TIMEOUT_MS);
+    });
+}
+function waitForServerExit(serverProcess) {
+    return new Promise((resolve) => {
+        serverProcess.once('exit', () => resolve());
+    });
+}
+export async function runDev(args = []) {
+    const { schemaPath, watchSchema } = parseDevArgs(args);
     const appPath = path.resolve(DEFAULT_OUTPUT_DIR, 'app.ts');
-    execFileSync(process.execPath, ['--import', 'tsx', appPath], { stdio: 'inherit', cwd: process.cwd() });
+    let serverProcess = null;
+    let syncInProgress = false;
+    let restarting = false;
+    let shuttingDown = false;
+    async function syncAndServe() {
+        if (syncInProgress) {
+            return;
+        }
+        syncInProgress = true;
+        try {
+            await generateAll(schemaPath);
+            await runDbBootstrap(schemaPath);
+            await stopServer(serverProcess);
+            serverProcess = startServer(appPath);
+            serverProcess.on('exit', (code, signal) => {
+                if (restarting || shuttingDown) {
+                    return;
+                }
+                if (!watchSchema) {
+                    if (code !== 0 && code !== null) {
+                        process.exitCode = code;
+                    }
+                    return;
+                }
+                if (code !== 0 && code !== null) {
+                    process.stderr.write(`Dev server exited with code ${code}\n`);
+                    process.exitCode = code;
+                    shuttingDown = true;
+                }
+                else if (signal) {
+                    process.stderr.write(`Dev server terminated by signal ${signal}\n`);
+                }
+            });
+        }
+        finally {
+            syncInProgress = false;
+        }
+    }
+    async function reload() {
+        if (shuttingDown || syncInProgress) {
+            return;
+        }
+        process.stderr.write('\nSchema changed — regenerating, bootstrapping, and restarting...\n');
+        restarting = true;
+        try {
+            await syncAndServe();
+        }
+        finally {
+            restarting = false;
+        }
+    }
+    const scheduleReload = createDebouncer(reload, WATCH_DEBOUNCE_MS);
+    async function shutdown() {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        await stopServer(serverProcess);
+    }
+    process.once('SIGINT', () => {
+        void shutdown().finally(() => {
+            process.exit(process.exitCode ?? 0);
+        });
+    });
+    process.once('SIGTERM', () => {
+        void shutdown().finally(() => {
+            process.exit(process.exitCode ?? 0);
+        });
+    });
+    await syncAndServe();
+    if (!watchSchema) {
+        if (serverProcess) {
+            await waitForServerExit(serverProcess);
+        }
+        return;
+    }
+    watch(schemaPath, scheduleReload);
+    await new Promise((resolve) => {
+        const interval = setInterval(() => {
+            if (shuttingDown) {
+                clearInterval(interval);
+                resolve();
+            }
+        }, 100);
+    });
 }

package/dist/cli/init.js

@@ -105,8 +105,11 @@ export async function runInit(args) {
     console.log('  make dev');
     console.log('');
     console.log('  # or run individually:');
-    console.log('  docker compose up -d');
+    console.log('  docker compose up -d --wait');
+    console.log(`  npx ${PACKAGE_NAME} dev   # generate + bootstrap + server + schema watch`);
+    console.log('');
+    console.log('  # split steps (dev already includes generate, bootstrap, and watch):');
     console.log(`  npx ${PACKAGE_NAME} generate`);
     console.log(`  npx ${PACKAGE_NAME} db:bootstrap`);
-    console.log(`  npx ${PACKAGE_NAME} dev`);
+    console.log(`  npx ${PACKAGE_NAME} dev --no-watch`);
 }

package/dist/cli/templates.d.ts

@@ -3,6 +3,6 @@ export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgre
 export declare const GITIGNORE_TEMPLATE = "node_modules/\ndist/\n.env\ndocker_data/\n.DS_Store\n*.log\nnpm-debug.log*\n";
 export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgis/postgis:16-3.4\n    container_name: schematic-pg-postgres\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"outDir\": \"dist\",\n    \"rootDir\": \".\"\n  },\n  \"include\": [\"generated/**/*\", \"src/**/*\"]\n}\n";
-export declare const MAKEFILE_TEMPLATE = ".PHONY: dev\n\ndev:\n\tdocker compose up -d\n\tnpx schematic-pg generate\n\tnpx schematic-pg db:bootstrap\n\tnpx schematic-pg dev\n";
+export declare const MAKEFILE_TEMPLATE = ".PHONY: dev\n\ndev:\n\tdocker compose up -d --wait\n\tnpx schematic-pg dev\n";
 export declare const HEALTH_ROUTE_TEMPLATE = "import { Hono } from 'hono';\nimport type { AppEnv } from 'schematic-pg/api/types';\n\nconst router = new Hono<AppEnv>();\nrouter.get('/', (c) => c.json({ ok: true }));\nexport default router;\n";
 export declare function createPackageJsonTemplate(projectName: string): string;

package/dist/cli/templates.js

@@ -65,9 +65,7 @@ export const TSCONFIG_TEMPLATE = `{
 export const MAKEFILE_TEMPLATE = `.PHONY: dev
 
 dev:
-\tdocker compose up -d
-\tnpx ${PACKAGE_NAME} generate
-\tnpx ${PACKAGE_NAME} db:bootstrap
+\tdocker compose up -d --wait
 \tnpx ${PACKAGE_NAME} dev
 `;
 export const HEALTH_ROUTE_TEMPLATE = `import { Hono } from 'hono';

package/dist/cli/wait-for-database.d.ts

@@ -0,0 +1,9 @@
+import { DatabaseClient } from '../db/client.js';
+export type WaitForDatabaseOptions = {
+    maxAttempts?: number;
+    intervalMs?: number;
+    client?: Pick<DatabaseClient, 'query'>;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare function pingDatabase(client: Pick<DatabaseClient, 'query'>): Promise<void>;
+export declare function waitForDatabase(options?: WaitForDatabaseOptions): Promise<void>;

package/dist/cli/wait-for-database.js

@@ -0,0 +1,39 @@
+import { DatabaseClient } from '../db/client.js';
+export async function pingDatabase(client) {
+    const result = await client.query('SELECT 1 AS ok');
+    const ok = result.rows[0]?.ok;
+    if (ok !== 1) {
+        throw new Error(`Unexpected ping result: ${String(ok)}`);
+    }
+}
+export async function waitForDatabase(options = {}) {
+    const maxAttempts = options.maxAttempts ?? 30;
+    const intervalMs = options.intervalMs ?? 1000;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const ownClient = options.client ? null : new DatabaseClient();
+    const client = options.client ?? ownClient;
+    try {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                await pingDatabase(client);
+                if (attempt > 1) {
+                    process.stderr.write(`Database ready (attempt ${attempt}/${maxAttempts})\n`);
+                }
+                return;
+            }
+            catch (error) {
+                if (attempt === maxAttempts) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Database not ready after ${maxAttempts} attempts (${intervalMs}ms interval): ${message}`);
+                }
+                process.stderr.write(`Waiting for database (${attempt}/${maxAttempts})...\n`);
+                await sleep(intervalMs);
+            }
+        }
+    }
+    finally {
+        if (ownClient) {
+            await ownClient.close();
+        }
+    }
+}

package/dist/cli.js

@@ -12,7 +12,7 @@ Commands:
   generate:sql [schema]      Generate SQL DDL to stdout
   generate:client [schema]   Generate db client files
   generate:api [schema]      Generate API files
-  dev [schema]               Regenerate client + API and start server
+  dev [schema] [--no-watch]  Generate, bootstrap DB, start server, watch schema
   db:ping                    Test database connection
   db:bootstrap [schema]      Apply DDL and snapshot schema state
   db:diff [schema]           Show schema diff (--name <name> to write migration)
@@ -50,7 +50,7 @@ async function main() {
                 await generateApi(schemaPath);
                 break;
             case 'dev':
-                await runDev(schemaPath);
+                await runDev(args);
                 break;
             case 'db:ping':
                 await runDbPing();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",