@protobase/cli 0.8.0 → 0.8.2

package/dist/dev/dev-jobs.js

@@ -0,0 +1,25 @@
+import { checkJobsSchema, startJobs } from "@protobase/server";
+//#region src/dev/dev-jobs.ts
+const store = globalThis;
+/**
+* Runs the project's jobs in the dev server: started on the first load, once the jobs schema checks out, and given the
+* reloaded definitions on every load after it, so an edited job runs its new code from the next job on.
+*/
+const devJobs = async (db, definitions) => {
+	if (store.__protobaseJobs) return store.__protobaseJobs.update(definitions);
+	if (definitions.length === 0) return;
+	await checkJobsSchema(db);
+	store.__protobaseJobs = await startJobs({
+		db,
+		jobs: definitions,
+		onError: (error) => console.error(error)
+	});
+};
+/** Lets running jobs finish and stops them, when the dev server closes. */
+const stopDevJobs = async () => {
+	const runtime = store.__protobaseJobs;
+	delete store.__protobaseJobs;
+	await runtime?.stop();
+};
+//#endregion
+export { devJobs, stopDevJobs };

package/dist/dev/entry.js

@@ -1,5 +1,6 @@
+import { devJobs } from "./dev-jobs.js";
 import { loadProject, projectDb } from "./project.js";
-import { checkAuthSchema, configExports, createAdmin, hasUsers } from "@protobase/server";
+import { checkAuthSchema, checkChanges, configExports, createAdmin, hasUsers, jobDefinitions } from "@protobase/server";
 import { Hono } from "hono";
 //#region src/dev/entry.ts
 const projectDir = process.env.PROTOBASE_PROJECT;
@@ -12,6 +13,8 @@ if (project.auth && !store.__protobaseAuthSchemaChecked) {
 	await checkAuthSchema(project.auth);
 	store.__protobaseAuthSchemaChecked = true;
 }
+await checkChanges(db, resources.map((resource) => resource.toModel()), project.events);
+await devJobs(db, jobDefinitions(project.jobs ?? {}));
 const admin = createAdmin({
 	resources,
 	views,
@@ -22,6 +25,8 @@ const admin = createAdmin({
 	...project.auth && { auth: project.auth },
 	...project.functions && { functions: project.functions },
 	...project.files && { files: project.files },
+	...project.events && { events: project.events },
+	jobs: jobDefinitions(project.jobs ?? {}),
 	options: {
 		onUnhandledError: (error) => console.error(error),
 		...project.options

package/dist/dev/run.js

@@ -5,6 +5,7 @@ import { moduleFile } from "../module-file.js";
 import { layoutCheck } from "../build/layout-check.js";
 import { projectUiPlugin } from "../project/project-ui.js";
 import { checkDatabase } from "./check-database.js";
+import { stopDevJobs } from "./dev-jobs.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { createServer, searchForWorkspaceRoot } from "vite";
@@ -23,6 +24,10 @@ const reloadOnProjectChange = (dirs) => ({
 		if (dirs.some((dir) => file.startsWith(`${dir}${path.sep}`)) && !file.includes(`${path.sep}node_modules${path.sep}`)) server.environments.ssr.moduleGraph.invalidateAll();
 	}
 });
+const stopJobsOnClose = {
+	name: "protobase-jobs",
+	closeBundle: () => stopDevJobs()
+};
 const appDependencies = [
 	"react",
 	"react/jsx-runtime",
@@ -65,6 +70,7 @@ const runDev = async (options, out) => {
 		},
 		plugins: [
 			reloadOnProjectChange([options.projectDir, ...extensions.map((extension) => extension.dir)]),
+			stopJobsOnClose,
 			projectUiPlugin(options.projectDir, extensions),
 			extensionImports(options.projectDir, extensions),
 			extensionStyles(extensions),

package/dist/main.js

@@ -9,10 +9,13 @@ import { parseHosts } from "./dev/hosts.js";
 import { runDev } from "./dev/run.js";
 import { runDoctor } from "./doctor/run.js";
 import { runScaffold } from "./scaffold/run.js";
+import { closeOnSignals } from "./serve/signals.js";
 import { serveBundle } from "./serve/serve-bundle.js";
 import { serveBundleDir } from "./serve/serve-dir.js";
+import { loadWorkerBundle, startWorker } from "./worker/start-worker.js";
 import { registerOrganizations } from "./organizations/register.js";
 import { registerFiles } from "./files/register.js";
+import { registerMigration } from "./migration/register.js";
 import { registerToken, registerUsers } from "./users/register.js";
 import { statSync } from "node:fs";
 import path from "node:path";
@@ -85,10 +88,20 @@ program.command("serve").description("Serve a bundle written by `protobase build
 	if (statSync(bundle).isDirectory()) await serveBundleDir(bundle, process.env, out);
 	else await serveBundle(bundle, process.env, out);
 });
+program.command("worker").description("Run the jobs of a bundle from `protobase build` in a process of their own, until SIGTERM or SIGINT, as `serve` runs them beside the API").argument("<bundle>", "the bundle folder, e.g. dist, or its dist/protobase.config.js").action(async (bundle) => {
+	loadNearestEnvFile(process.cwd());
+	const worker = await startWorker({
+		project: await loadWorkerBundle(bundle),
+		databaseUrl: process.env.DATABASE_URL || void 0
+	});
+	closeOnSignals(worker.stop);
+	out(`protobase worker running ${worker.jobs} job${worker.jobs === 1 ? "" : "s"}\n`);
+});
 registerUsers(program);
 registerOrganizations(program);
 registerToken(program);
 registerAuth(program);
+registerMigration(program);
 registerFiles(program);
 const run = (argv) => program.parseAsync(argv).catch((error) => {
 	process.stderr.write(`error: ${error.message}\n`);

package/dist/migration/load-project.js

@@ -0,0 +1,42 @@
+import { loadNearestEnvFile } from "../dev/env.js";
+import { importProjectFile } from "../project/import-project-file.js";
+import { createPgDb } from "../project/pg-db.js";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { configExports, jobDefinitions, mergeConfig } from "@protobase/server";
+import pg from "pg";
+//#region src/migration/load-project.ts
+const configOf = async (file) => (await importProjectFile(file)).default ?? {};
+/**
+* The project in `dir` as `protobase dev` merges it, for what its database needs: protobase.config.ts, or
+* config/index.ts when that has no `config`, after the configs of `extensions` and the configs it extends. `close`
+* ends the pool it opened; a `db` the project exports stays the project's.
+*/
+const loadMigrationProject = async (dir, extensions = []) => {
+	loadNearestEnvFile(dir);
+	const file = path.join(dir, "protobase.config.ts");
+	const custom = existsSync(file) ? await configOf(file) : {};
+	const index = path.join(dir, "config", "index.ts");
+	if (!custom.config && !existsSync(index)) throw new Error(`No config/index.ts or protobase.config.ts in ${dir}; run this inside a project`);
+	const own = {
+		...custom,
+		config: custom.config ?? await importProjectFile(index)
+	};
+	const extended = await Promise.all(extensions.flatMap((extension) => extension.config ? [configOf(extension.config)] : []));
+	const project = mergeConfig(...extended, own);
+	const url = process.env.DATABASE_URL;
+	if (!project.db && !url) throw new Error("No database: set DATABASE_URL or export `db` from protobase.config.ts");
+	const ownDb = project.db ? void 0 : createPgDb(pg, url);
+	return {
+		models: configExports(project.config ?? {}).resources.map((source) => source.toModel()),
+		db: project.db ?? ownDb,
+		...project.auth && { auth: project.auth },
+		...project.events && { events: project.events },
+		jobs: jobDefinitions(project.jobs ?? {}),
+		close: async () => {
+			await ownDb?.destroy();
+		}
+	};
+};
+//#endregion
+export { loadMigrationProject };

package/dist/migration/parts.js

@@ -0,0 +1,22 @@
+import { authSchemaMigration, changesMigration, jobsSchemaMigration } from "@protobase/server";
+//#region src/migration/parts.ts
+/** Every feature the project's config enables, in the order their files are written. */
+const migrationParts = (project) => [
+	...project.auth ? [{
+		name: "auth",
+		title: "The auth schema changes this version of Protobase needs",
+		sql: () => authSchemaMigration(project.auth)
+	}] : [],
+	...project.jobs.length > 0 ? [{
+		name: "jobs",
+		title: "The jobs schema this version of Protobase needs",
+		sql: () => jobsSchemaMigration(project.db)
+	}] : [],
+	{
+		name: "changes",
+		title: "The change capture the resources' events need",
+		sql: () => changesMigration(project.db, project.models, project.events)
+	}
+];
+//#endregion
+export { migrationParts };

package/dist/migration/register.js

@@ -0,0 +1,22 @@
+import { resolveExtensions } from "../project/extensions.js";
+import { loadMigrationProject } from "./load-project.js";
+import { migrationParts } from "./parts.js";
+import { writeMigrations } from "./write-migrations.js";
+import path from "node:path";
+//#region src/migration/register.ts
+const out = (text) => process.stdout.write(text);
+const collect = (value, previous) => [...previous, value];
+const registerMigration = (program) => {
+	program.command("migration").description("Write what the database still needs for every feature the config enables (auth, events, jobs) as the project's next SQL migrations").option("--dir <dir>", "migrations folder", "db/migrations").option("--extend <dir>", "merge the protobase.config.ts in this folder before the project's, as dev and build do, repeatable", collect, []).action(async (opts) => {
+		const project = await loadMigrationProject(process.cwd(), resolveExtensions(opts.extend));
+		try {
+			const files = await writeMigrations(migrationParts(project), path.resolve(opts.dir));
+			out(files.length > 0 ? files.map((file) => `wrote ${path.relative(process.cwd(), file)}\n`).join("") + "apply them with the project's migrations\n" : "the database is up to date; nothing to write\n");
+		} finally {
+			await project.close();
+		}
+		process.exit(0);
+	});
+};
+//#endregion
+export { registerMigration };

package/dist/migration/write-migrations.js

@@ -0,0 +1,32 @@
+import { nextMigrationName } from "../auth/migration-file.js";
+import path from "node:path";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+//#region src/migration/write-migrations.ts
+/** A part's file: what wrote it and why, then its statements. */
+const partText = (title, sql) => `-- ${title}, written by \`protobase migration\`.\n-- Applied with the project's other migrations; edit or remove statements the project handles differently.\n\n${sql}\n`;
+/**
+* Writes what each part still needs as the next migrations in `dir`, one file per part, and returns their paths; none
+* when the database is current. Every part is compared with the database before any file is written, so the
+* project's earlier migrations must be applied to it first.
+*/
+const writeMigrations = async (parts, dir) => {
+	const pending = [];
+	for (const part of parts) {
+		const sql = await part.sql();
+		if (sql !== void 0) pending.push({
+			part,
+			sql
+		});
+	}
+	if (pending.length === 0) return [];
+	await mkdir(dir, { recursive: true });
+	const files = [];
+	for (const { part, sql } of pending) {
+		const file = path.join(dir, nextMigrationName(await readdir(dir), part.name));
+		await writeFile(file, partText(part.title, sql), { flag: "wx" });
+		files.push(file);
+	}
+	return files;
+};
+//#endregion
+export { partText, writeMigrations };

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.8.0";
+var version = "0.8.2";
 //#endregion
 export { version };

package/dist/serve/app.js

@@ -1,10 +1,10 @@
 import { isApiPath } from "../bundle/manifest.js";
 import { serveStaticSite } from "./static-site.js";
-import { configExports, createAdmin } from "@protobase/server";
+import { configExports, createAdmin, jobDefinitions, jobsDrainApp } from "@protobase/server";
 import { Hono } from "hono";
 import { logger } from "hono/logger";
 //#region src/serve/app.ts
-const createServeApp = ({ project, db, requestLog, site }) => {
+const createServeApp = ({ project, db, requestLog, site, jobs, drainToken }) => {
 	const { resources, views, pages, userMenu } = configExports(project.config);
 	const admin = createAdmin({
 		resources,
@@ -16,6 +16,8 @@ const createServeApp = ({ project, db, requestLog, site }) => {
 		...project.auth && { auth: project.auth },
 		...project.functions && { functions: project.functions },
 		...project.files && { files: project.files },
+		...project.events && { events: project.events },
+		jobs: jobDefinitions(project.jobs ?? {}),
 		options: {
 			onUnhandledError: (error) => console.error(error),
 			...project.options
@@ -25,6 +27,10 @@ const createServeApp = ({ project, db, requestLog, site }) => {
 	if (requestLog) app.use(logger());
 	app.get("/health", (c) => c.json({ status: "ok" }));
 	if (site) app.use("*", (c, next) => isApiPath(site.api, c.req.path) ? next() : serveStaticSite(site, c.req.raw));
+	if (jobs && drainToken) app.route("/", jobsDrainApp({
+		runtime: jobs,
+		token: drainToken
+	}));
 	app.route("/", admin);
 	return app;
 };

package/dist/serve/env.js

@@ -5,11 +5,15 @@ const readServeEnv = (env) => {
 	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`PORT must be a port number, not "${env.PORT}"`);
 	const minutes = env.PROTOBASE_FILES_CLEANUP_MINUTES ? Number(env.PROTOBASE_FILES_CLEANUP_MINUTES) : 60;
 	if (!Number.isInteger(minutes) || minutes < 0) throw new Error(`PROTOBASE_FILES_CLEANUP_MINUTES must be a whole number of minutes, not "${env.PROTOBASE_FILES_CLEANUP_MINUTES}"`);
+	const jobs = env.PROTOBASE_JOBS ?? "on";
+	if (jobs !== "on" && jobs !== "off") throw new Error(`PROTOBASE_JOBS must be on or off, not "${jobs}"`);
 	return {
 		port,
 		databaseUrl: env.DATABASE_URL || void 0,
 		requestLog: Boolean(env.REQUEST_LOG),
-		filesCleanupMinutes: minutes
+		filesCleanupMinutes: minutes,
+		runJobs: jobs === "on",
+		...env.PROTOBASE_JOBS_DRAIN_TOKEN && { drainToken: env.PROTOBASE_JOBS_DRAIN_TOKEN }
 	};
 };
 //#endregion

package/dist/serve/lifecycle.js

@@ -1,7 +1,7 @@
 import { createPgDb } from "../project/pg-db.js";
 import { createServeApp } from "./app.js";
 import { startCleanupTimer } from "./cleanup-timer.js";
-import { checkAuthSchema, configExports, createFileCleanup } from "@protobase/server";
+import { checkAuthSchema, checkChanges, checkJobsSchema, configExports, createFileCleanup, jobDefinitions, startJobs } from "@protobase/server";
 import { createAdaptorServer } from "@hono/node-server";
 import pg from "pg";
 //#region src/serve/lifecycle.ts
@@ -18,19 +18,41 @@ const startServe = async ({ project, env, createDb = (url) => createPgDb(pg, url
 	if (project.auth) await checkAuthSchema(project.auth);
 	const ownDb = project.db ? void 0 : createDb(env.databaseUrl);
 	const db = project.db ?? ownDb;
-	const app = createServeApp({
-		project,
-		db,
-		requestLog: env.requestLog,
-		site
-	});
-	const server = createAdaptorServer({ fetch: app.fetch });
-	await listen(server, env.port).catch(async (error) => {
+	const { resources } = configExports(project.config);
+	const definitions = jobDefinitions(project.jobs ?? {});
+	const startJobsAndListen = async () => {
+		await checkChanges(db, resources.map((resource) => resource.toModel()), project.events);
+		if (definitions.length > 0) await checkJobsSchema(db);
+		const jobs = definitions.length > 0 ? await startJobs({
+			db,
+			jobs: definitions,
+			work: env.runJobs,
+			onError: (error) => console.error(error)
+		}) : void 0;
+		const app = createServeApp({
+			project,
+			db,
+			requestLog: env.requestLog,
+			site,
+			...jobs && { jobs },
+			...env.drainToken && { drainToken: env.drainToken }
+		});
+		const server = createAdaptorServer({ fetch: app.fetch });
+		await listen(server, env.port).catch(async (error) => {
+			await jobs?.stop();
+			throw error;
+		});
+		return {
+			server,
+			jobs
+		};
+	};
+	const { server, jobs } = await startJobsAndListen().catch(async (error) => {
 		await ownDb?.destroy();
 		throw error;
 	});
 	const cleanup = createFileCleanup({
-		resources: configExports(project.config).resources,
+		resources,
 		db,
 		...project.files && { files: project.files }
 	});
@@ -38,6 +60,7 @@ const startServe = async ({ project, env, createDb = (url) => createPgDb(pg, url
 	const close = async () => {
 		await closeServer(server);
 		await timer?.stop();
+		await jobs?.stop();
 		await ownDb?.destroy();
 	};
 	return {

package/dist/worker/start-worker.js

@@ -0,0 +1,51 @@
+import { readManifest } from "../bundle/manifest.js";
+import { checkBundleVersion } from "../serve/bundle-version.js";
+import { createPgDb } from "../project/pg-db.js";
+import { loadBundle } from "../serve/load-bundle.js";
+import { statSync } from "node:fs";
+import path from "node:path";
+import { checkJobsSchema, jobDefinitions, startJobs } from "@protobase/server";
+import pg from "pg";
+//#region src/worker/start-worker.ts
+const bundleConfigFile = async (bundle) => {
+	if (!statSync(bundle).isDirectory()) return bundle;
+	return path.join(bundle, (await readManifest(bundle)).server);
+};
+/**
+* Runs the project's jobs, and nothing else, until `stop`: the same handlers `protobase serve` runs, in a process of
+* their own. It reads the jobs schema at start and refuses one that is missing or behind, like `serve`.
+*/
+const startWorker = async ({ project, databaseUrl, createDb = (url) => createPgDb(pg, url) }) => {
+	const definitions = jobDefinitions(project.jobs ?? {});
+	if (definitions.length === 0) throw new Error("The bundle has no jobs: export them from protobase.config.ts as `jobs`");
+	if (!project.db && !databaseUrl) throw new Error("No database: set DATABASE_URL or export `db` from protobase.config.ts");
+	const ownDb = project.db ? void 0 : createDb(databaseUrl);
+	const db = project.db ?? ownDb;
+	const start = async () => {
+		await checkJobsSchema(db);
+		return startJobs({
+			db,
+			jobs: definitions,
+			onError: (error) => console.error(error)
+		});
+	};
+	const jobs = await start().catch(async (error) => {
+		await ownDb?.destroy();
+		throw error;
+	});
+	return {
+		jobs: definitions.length,
+		stop: async () => {
+			await jobs.stop();
+			await ownDb?.destroy();
+		}
+	};
+};
+/** `protobase worker <bundle>`: the bundle's jobs until SIGTERM or SIGINT, once its manifest shows a version this CLI runs. */
+const loadWorkerBundle = async (bundle) => {
+	const file = await bundleConfigFile(bundle);
+	await checkBundleVersion(file);
+	return loadBundle(file);
+};
+//#endregion
+export { bundleConfigFile, loadWorkerBundle, startWorker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -34,11 +34,11 @@
   "dependencies": {
     "@hono/node-server": "^2.1.3",
     "@hono/vite-dev-server": "^0.26.1",
-    "@protobase/layout": "0.8.0",
-    "@protobase/query": "0.8.0",
-    "@protobase/schema": "0.8.0",
-    "@protobase/server": "0.8.0",
-    "@protobase/ui": "0.8.0",
+    "@protobase/layout": "0.8.2",
+    "@protobase/query": "0.8.2",
+    "@protobase/schema": "0.8.2",
+    "@protobase/server": "0.8.2",
+    "@protobase/ui": "0.8.2",
     "@scalar/hono-api-reference": "^0.12.10",
     "@tailwindcss/vite": "^4.3.3",
     "@vitejs/plugin-react": "^6.1.2",