@protobase/cli 0.66.8 → 0.66.9

package/dist/cli/package.js

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

package/dist/dev/api-forward.js

@@ -9,7 +9,8 @@ import { request } from "node:http";
 * discovery documents MCP clients read (`oauthWellKnownPaths`), below which a resource's own one is, and the push worker
 * (`withDevServiceWorker`). Vite serves the rest.
 */
-const isApiRequest = (url) => /^(\/api(\/|\?|$)|\/\.well-known\/webauthn(\?|$)|\/\.well-known\/oauth-(authorization-server|protected-resource)(\/|\?|$)|\/protobase\.sw\.js(\?|$))/.test(url);
+const apiRequestPattern = /^(\/api(\/|\?|$)|\/\.well-known\/webauthn(\?|$)|\/\.well-known\/oauth-(authorization-server|protected-resource)(\/|\?|$)|\/protobase\.sw\.js(\?|$))/;
+const isApiRequest = (url) => apiRequestPattern.test(url);
 const hopByHop = /* @__PURE__ */ new Set([
 	"connection",
 	"keep-alive",
@@ -67,4 +68,4 @@ const apiForward = (port) => ({
 	}
 });
 //#endregion
-export { apiForward, isApiRequest };
+export { apiForward, apiRequestPattern, isApiRequest };

package/dist/dev/app-files.js

@@ -0,0 +1,11 @@
+import { adminAppMain } from "../project/admin-app.js";
+import { existsSync } from "node:fs";
+import path from "node:path";
+//#region src/dev/app-files.ts
+/** Fails, naming them, when the admin app in `appDir` lacks the files `protobase dev` serves it from. */
+const requireAppFiles = (appDir) => {
+	const missing = ["index.html", adminAppMain].filter((file) => !existsSync(path.join(appDir, file)));
+	if (missing.length > 0) throw new Error(`The admin app is missing ${missing.join(", ")} in ${appDir}; \`protobase dev\` serves the app from there`);
+};
+//#endregion
+export { requireAppFiles };

package/dist/dev/check-remote-api.js

@@ -0,0 +1,18 @@
+//#region src/dev/check-remote-api.ts
+/**
+* Fails, before the dev server starts, when the instance at `origin` cannot be reached or does not answer `/api/meta`
+* as a Protobase API does, with the X-Meta-Version header.
+*/
+const checkRemoteApi = async (origin) => {
+	const meta = `${origin}/api/meta`;
+	const answer = await fetch(meta, {
+		signal: AbortSignal.timeout(1e4),
+		redirect: "manual"
+	}).catch((error) => {
+		throw new Error(`Cannot reach the API at ${meta}: ${error.cause?.message ?? error.message}`);
+	});
+	await answer.body?.cancel();
+	if (!answer.headers.has("x-meta-version")) throw new Error(`${origin} answered ${meta} with ${answer.status} and no X-Meta-Version header; is it a Protobase app?`);
+};
+//#endregion
+export { checkRemoteApi };

package/dist/dev/remote-api.js

@@ -0,0 +1,58 @@
+import { isAllowedHost } from "./allowed-host.js";
+import { apiRequestPattern } from "./api-forward.js";
+//#region src/dev/remote-api.ts
+/**
+* The origin of the Protobase instance `protobase dev --api` hands the API to, from the URL given: http or https, and
+* no path, since an instance serves its API at /api of its origin.
+*/
+const remoteApiOrigin = (value) => {
+	const url = URL.parse(value);
+	if (!url || url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`--api expects an http or https URL, such as https://app.example.com, not "${value}"`);
+	if (url.pathname !== "/" || url.search) throw new Error(`--api expects the instance's origin, such as ${url.origin}, without a path`);
+	return url.origin;
+};
+const ofDevServer = (value, request) => {
+	const url = value === void 0 ? null : URL.parse(value);
+	return url?.host === request.headers.host ? url : void 0;
+};
+/**
+* Hands the requests the API process answers in `protobase dev` (`isApiRequest`), and the API's WebSockets, to the
+* instance at `origin` through Vite's proxy. The instance sees its own Host, and its own origin in the Origin and Referer
+* of a page of this dev server, so its sign-in and its checks of a request's origin take them; a request from any other
+* page keeps the origin it came with. Its cookies come back without their Domain, for localhost to keep, and a
+* redirect to its own address comes back as a path on this server. A socket whose Host fails Vite's host check is
+* refused, as Vite refuses such a request.
+*/
+const remoteApi = (origin) => {
+	let allowedHosts = [];
+	return {
+		name: "protobase-remote-api",
+		config: () => ({ server: { proxy: { [apiRequestPattern.source]: {
+			target: origin,
+			changeOrigin: true,
+			ws: true,
+			rewriteWsOrigin: true,
+			cookieDomainRewrite: { "*": "" },
+			bypass: (request, response) => {
+				if (!(response === void 0)) return void 0;
+				return isAllowedHost(request.headers.host, allowedHosts) ? void 0 : false;
+			},
+			configure: (proxy) => {
+				proxy.on("proxyReq", (upstream, request) => {
+					if (ofDevServer(request.headers.origin, request)) upstream.setHeader("origin", origin);
+					const referer = ofDevServer(request.headers.referer, request);
+					if (referer) upstream.setHeader("referer", `${origin}${referer.pathname}${referer.search}`);
+				});
+				proxy.on("proxyRes", (answer) => {
+					const location = answer.headers.location;
+					if (location?.startsWith(`${origin}/`)) answer.headers.location = location.slice(origin.length);
+				});
+			}
+		} } } }),
+		configResolved: (config) => {
+			allowedHosts = config.server.allowedHosts;
+		}
+	};
+};
+//#endregion
+export { remoteApi, remoteApiOrigin };

package/dist/dev/run-ui.js

@@ -0,0 +1,34 @@
+import { adminAppDir } from "../project/admin-app.js";
+import { alsoOnIpv6, checkPortFree } from "./loopback.js";
+import { remoteApi } from "./remote-api.js";
+import { requireAppFiles } from "./app-files.js";
+import { checkRemoteApi } from "./check-remote-api.js";
+//#region src/dev/run-ui.ts
+/**
+* `protobase dev --api`: the admin app with the project's UI, theme and icons, as `runDev` serves it, with its API
+* requests handed to a running instance instead of an API process of its own; no database and no project config are read.
+*/
+const runUiDev = async (options, out) => {
+	const appDir = options.appDir ?? adminAppDir;
+	requireAppFiles(appDir);
+	await checkRemoteApi(options.api);
+	if (options.port !== 0) await checkPortFree(options.port);
+	const { createAppServer } = await import("./app-server.js");
+	const server = await createAppServer({
+		...options,
+		appDir,
+		extensions: options.extensions ?? []
+	}, [remoteApi(options.api)]);
+	const closeAndThrow = async (error) => {
+		await server.close();
+		throw error;
+	};
+	await server.listen().catch(closeAndThrow);
+	const address = server.httpServer?.address();
+	const port = typeof address === "object" && address ? address.port : options.port;
+	if (server.httpServer) await alsoOnIpv6(server.httpServer, port).catch(closeAndThrow);
+	out(`protobase dev ready at http://localhost:${port}\n  project  ${options.projectDir} (UI only)\n  api      ${options.api}/api/v1, through http://localhost:${port}/api/v1\n  login    sign in as a user of ${options.api}\n`);
+	return server;
+};
+//#endregion
+export { runUiDev };

package/dist/dev/run.js

@@ -1,18 +1,14 @@
 import { loadNearestEnvFile } from "./env.js";
-import { adminAppDir, adminAppMain } from "../project/admin-app.js";
+import { adminAppDir } from "../project/admin-app.js";
 import { alsoOnIpv6, checkPortFree } from "./loopback.js";
+import { apiForward } from "./api-forward.js";
+import { requireAppFiles } from "./app-files.js";
 import { checkDatabase } from "./check-database.js";
 import { authDriftLines } from "./auth-drift-lines.js";
 import { loginLine } from "./login-line.js";
-import { apiForward } from "./api-forward.js";
 import { forkApiChild } from "./api-child.js";
-import { existsSync } from "node:fs";
 import path from "node:path";
 //#region src/dev/run.ts
-const requireAppFiles = (appDir) => {
-	const missing = ["index.html", adminAppMain].filter((file) => !existsSync(path.join(appDir, file)));
-	if (missing.length > 0) throw new Error(`The admin app is missing ${missing.join(", ")} in ${appDir}; \`protobase dev\` serves the app from there`);
-};
 const runDev = async (options, out) => {
 	loadNearestEnvFile(options.projectDir);
 	const url = process.env[options.envVar];

package/dist/main.js

@@ -60,23 +60,34 @@ program.command("doctor").description("Check a config folder against the databas
 	}, out);
 	if (errors > 0) process.exitCode = 1;
 });
-program.command("dev").description("Serve the admin app and API for the project in the current directory").option("--port <port>", "port for the app and API", "5173").option("--env <variable>", "environment variable holding the database URL", "DATABASE_URL").option("--allowed-hosts <hosts>", "extra Host headers to accept, comma separated; a leading dot matches subdomains (.trycloudflare.com)").option("--cache-dir <dir>", "Vite's dependency cache, so parallel dev servers do not share one").option("--extend <dir>", "merge the protobase.config.ts and protobase.ui.tsx in this folder before the project's, repeatable", collect, []).option("--no-jobs", "run none of the app's jobs and deliver none of its events, such as against its hosted database").action(async (opts) => {
-	const [{ runDev }, { resolveExtensions }, { writeProjectTypes }] = await Promise.all([
-		import("./dev/run.js"),
-		import("./project/extensions.js"),
-		import("./project/project-types.js")
-	]);
-	await writeProjectTypes(process.cwd());
+const runUiDevAgainst = async (api, options) => {
+	const [{ runUiDev }, { remoteApiOrigin }] = await Promise.all([import("./dev/run-ui.js"), import("./dev/remote-api.js")]);
+	return runUiDev({
+		...options,
+		api: remoteApiOrigin(api)
+	}, out);
+};
+const runFullDev = async (envVar, jobs, options) => {
+	const { runDev } = await import("./dev/run.js");
 	const server = await runDev({
+		...options,
+		envVar,
+		jobs
+	}, out);
+	warn(placeholderSecretWarning(process.env));
+	return server;
+};
+program.command("dev").description("Serve the admin app and API for the project in the current directory").option("--port <port>", "port for the app and API", "5173").option("--env <variable>", "environment variable holding the database URL", "DATABASE_URL").option("--allowed-hosts <hosts>", "extra Host headers to accept, comma separated; a leading dot matches subdomains (.trycloudflare.com)").option("--cache-dir <dir>", "Vite's dependency cache, so parallel dev servers do not share one").option("--extend <dir>", "merge the protobase.config.ts and protobase.ui.tsx in this folder before the project's, repeatable", collect, []).option("--no-jobs", "run none of the app's jobs and deliver none of its events, such as against its hosted database").option("--api <url>", "serve the admin app alone, with the API of the running Protobase instance at this URL; no database or API process").action(async (opts) => {
+	const [{ resolveExtensions }, { writeProjectTypes }] = await Promise.all([import("./project/extensions.js"), import("./project/project-types.js")]);
+	await writeProjectTypes(process.cwd());
+	const shared = {
 		extensions: resolveExtensions(opts.extend),
 		port: Number(opts.port),
-		envVar: opts.env,
 		projectDir: process.cwd(),
 		cacheDir: opts.cacheDir && path.resolve(opts.cacheDir),
-		allowedHosts: parseHosts(opts.allowedHosts),
-		jobs: opts.jobs
-	}, out);
-	warn(placeholderSecretWarning(process.env));
+		allowedHosts: parseHosts(opts.allowedHosts)
+	};
+	const server = opts.api ? await runUiDevAgainst(opts.api, shared) : await runFullDev(opts.env, opts.jobs, shared);
 	process.once("SIGINT", () => void server.close().then(() => process.exit(0)));
 	process.once("SIGTERM", () => void server.close().then(() => process.exit(0)));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.66.8",
+  "version": "0.66.9",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,12 +43,12 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.66.8",
-    "@protobase/layout": "0.66.8",
-    "@protobase/query": "0.66.8",
-    "@protobase/schema": "0.66.8",
-    "@protobase/server": "0.66.8",
-    "@protobase/ui": "0.66.8",
+    "@protobase/config": "0.66.9",
+    "@protobase/layout": "0.66.9",
+    "@protobase/query": "0.66.9",
+    "@protobase/schema": "0.66.9",
+    "@protobase/server": "0.66.9",
+    "@protobase/ui": "0.66.9",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/references/features/build-and-run.md

@@ -7,6 +7,7 @@ Develop, build and run an app, on servers, in containers and on phones.
 - [Node and Bun](../reference/cli.md#how-it-runs): The `protobase` command runs on Node 22.12 or later or on Bun, and a bundle runs on both unless it is built for Bun only.
 - [Dev server](../reference/cli.md#dev): The admin app and the API on one port, with changes shown without a restart.
 - [Dev server without jobs](../reference/cli.md#dev): `protobase dev --no-jobs` runs no jobs and delivers no events, webhooks or pushes, to develop against a hosted app's database without doing its work twice.
+- [UI-only dev server](../reference/cli.md#ui-only) (beta): `protobase dev --api <url>` serves the app's UI from the project with the API of an app already running, such as its staging deploy, with no database.
 - [Editor types](../reference/cli.md#types): `protobase types` gives the editor and `tsc` the types of the CLI that builds the app, with nothing installed.
 - [Project scripts](../reference/cli.md#run): `protobase run` runs a seed or a migration script on the CLI's packages.
 - [Migrate command](../reference/cli.md#migrate): `protobase migrate` applies the project's SQL migrations in one transaction, with nothing installed.

package/skills/protobase/references/reference/cli.md

@@ -134,6 +134,7 @@ Exit code is 1 when there are errors. Run it after the project's migrations and
 
 ```sh
 protobase dev [--port 5173] [--env DATABASE_URL] [--cache-dir <dir>] [--allowed-hosts <hosts>] [--extend <dir>] [--no-jobs]   # run inside a project, e.g. bun run --cwd tests/apps/erp dev
+protobase dev --api <url> [--port 5173] [--cache-dir <dir>] [--allowed-hosts <hosts>] [--extend <dir>]   # the UI alone, on the API at <url>
 ```
 
 One port, two processes: Vite serves the admin app from `@protobase/ui`'s `src/app/` (`dist/app/` when installed; `index.html` and `main.tsx`, or `main.js`; the command fails with a clear message when they are missing) and hands `/api`, supabase-js's `/api/sb` included, to the Hono app from `createAdmin`, which runs in a process of its own; the CLI's process never loads `@protobase/server`. Open `http://localhost:<port>`; the API reference is at `/api/docs`.
@@ -154,6 +155,17 @@ One port, two processes: Vite serves the admin app from `@protobase/ui`'s `src/a
 - **Extensions:** `--extend <dir>` merges an extension in, its UI built into the dev page beside the project's, to try one out; its files reload like the project's.
 - **Hot reload:** server code, data configs, `ui.ts` views, layouts and the config are loaded through Vite's SSR module graph, and the config is read again with each rebuild. A change inside the project (or, in this repository, in `packages/server`, `packages/query`, `packages/schema`) rebuilds the API on the next request without a restart; `/meta` and `X-Meta-Version` change, so open tabs refetch. The database pool survives reloads. Newly added `ui.ts` files appear after the next change inside the project.
 
+### UI only
+
+:::caution[Beta]
+Sign-in with a passkey or an outside provider, such as Google, belongs to the instance's own address and does not return to the dev server; sign in with an emailed code or a password. Safari keeps no cookie of an `https` instance on `http://localhost`; use Chrome or Firefox.
+:::
+
+`--api <url>` serves the admin app with the project's UI, theme, icons and `--extend` folders, hot reloaded as above, and hands every request the API process would answer (`/api`, `/.well-known/webauthn`, the OAuth discovery documents and `/protobase.sw.js`), its WebSockets included, to the Protobase app already running at `<url>`, such as `https://staging.example.com` or another `protobase dev`. Nothing reads a database or the project's config: no `DATABASE_URL`, no `PROTOBASE_SECRET`, no migration checks and no jobs, and resources, roles and data are the instance's. Change the UI here and the server code where the instance runs.
+
+- **Checked at start:** the instance must answer `/api/meta` with an `X-Meta-Version` header, as every Protobase app does; otherwise the command names the URL and what came back. `<url>` is an origin, without a path.
+- **Sign-in:** sign in as a user of the instance. Requests from the dev server's own pages reach it with its own Host, Origin and Referer, so its origin checks pass; a request from any other site keeps its own origin, which the instance refuses. Its cookies come back without their `Domain`, for `localhost` to keep, and a redirect to its own address becomes a path on the dev server.
+
 ### Extending a config
 
 `--extend <dir>` (repeatable) merges an extension's folder into the app before the project: its config and the code its paths find, the same as the project's. How each part merges, and what a name defined twice does, is in [Extensions](config.md#extensions).