hollware 0.2.0 → 0.4.0

package/README.md

@@ -3,8 +3,8 @@
 The command line of [Hollware](https://github.com/hollware/hollware), an open-source headless
 CMS for the agent era, native to Cloudflare Workers.
 
-> **Status: pre-alpha.** `init`, `migrate`, `token` and `import` work, against a Hollware that
-> is still being built. `export` arrives in v0.2. POSIX shells only: it has not been tried on
+> **Status: pre-alpha.** `init`, `migrate`, `deploy`, `doctor`, `token`, `invite` and `import`
+> work, against a Hollware that is still being built. POSIX shells only: it has not been tried on
 > Windows.
 
 ## Commands
@@ -13,7 +13,10 @@ CMS for the agent era, native to Cloudflare Workers.
 | --------- | -------------------------------------------------------------------------------- |
 | `init`    | Create a site, its owner and a first personal token in the project's D1 database |
 | `migrate` | Apply D1 migrations; `--check` lists the pending ones, `--remote` backs up first |
-| `token`   | Create, list and revoke personal tokens                                          |
+| `deploy`  | Deploy to Cloudflare, creating what the project needs, and migrate the database  |
+| `doctor`  | Check the project, its bindings, its database and its owner, with what to fix    |
+| `token`   | Create, list and revoke personal tokens, and read tokens with `--read`           |
+| `invite`  | Invite a person to the admin, as an editor or an author                          |
 | `import`  | Import Markdown files over MCP, as drafts, and publish them with `--publish`     |
 | `export`  | Export entries as Markdown files (v0.2)                                          |
 
@@ -32,9 +35,15 @@ hollware token list                      # never shows a hash
 hollware token revoke tok_01JAB3XQ8ZK4M6N2P5R7S9T0VW
 ```
 
+To put it on Cloudflare, log in with `wrangler login` and run `hollware deploy`: the first deploy
+creates the D1 database, the KV namespace and the queues, writes their ids and the public URL of
+the Worker into `wrangler.jsonc`, and applies the migrations. Then `hollware init --site blog
+--remote` makes the site in it.
+
 Add `--remote` to work on the database in Cloudflare instead (it needs `wrangler login` or a
 `CLOUDFLARE_API_TOKEN`). `migrate --remote` first exports the database to
-`.wrangler/hollware-backups` and stops if that fails. `--database <name>` picks another D1
+`.wrangler/hollware-backups` and stops if that fails; a new database, with none of the
+migrations, has nothing to back up. `--database <name>` picks another D1
 database than the binding `DB`. `--site <key>` picks a site when the database has several.
 
 Put the token that `init` printed in a file only you can read, and import a directory of
@@ -52,7 +61,7 @@ reported, and the command exits with code 1. The token never appears in its outp
 
 ## How it works
 
-`init`, `migrate` and `token` run the project's own `wrangler` (the nearest
+`init`, `migrate`, `deploy`, `doctor` and `token` run the project's own `wrangler` (the nearest
 `node_modules/.bin/wrangler`) against its D1 database, and read the binding from `wrangler.jsonc`.
 `import` speaks MCP to `<url>/mcp` with the token as a bearer token. The CLI never loads
 `hollware.config.ts`.

package/dist/{d1-Bd-sdoDd.mjs → d1-D5A6OVDD.mjs}

@@ -2,8 +2,8 @@ import { i as UsageError, r as CliError, t as printable } from "./format-BpRYEsG
 import { n as failureReason } from "./wrangler-BLIfwbcu.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { SCOPES, SITE_KEY_MAX_LENGTH, isId, isScope, isSiteKey } from "@hollware/core";
 import * as z from "zod";
+import { SCOPES, SITE_KEY_MAX_LENGTH, isId, isScope, isSiteKey } from "@hollware/core";
 //#region src/jsonc.ts
 /**
 * Reads JSON with comments, the format of `wrangler.jsonc`: `//` and `/* *\/` comments and a
@@ -136,13 +136,17 @@ function parseDatabase(value) {
 	if (!DATABASE.test(value)) throw new UsageError(`invalid --database ${shown(value)}: use the name or the binding of a D1 database (letters, digits, "_", "-" and ".", not starting with "-").`);
 	return value;
 }
-/** The statement that finds an owner. */
+/** The statement that finds the owners: the members with the role owner, first come first (ADR-026). */
 function ownerQuery() {
-	return "SELECT id FROM users WHERE role = 'owner' LIMIT 1";
+	return "SELECT user_id AS id, site_id AS site FROM members WHERE role = 'owner' ORDER BY created_at, user_id";
 }
 /** One statement for the sites of the database and one for its first owner. */
 function sitesAndOwnerQuery() {
-	return "SELECT id FROM sites ORDER BY id; SELECT id FROM users WHERE role = 'owner' ORDER BY created_at, id LIMIT 1;";
+	return "SELECT id FROM sites ORDER BY id; SELECT user_id AS id FROM members WHERE role = 'owner' ORDER BY created_at, user_id LIMIT 1;";
+}
+/** The owner of a site: the member with the role owner who came first. */
+function ownerOfSiteQuery(site) {
+	return `SELECT user_id AS id FROM members WHERE site_id = ${quote(site)} AND role = 'owner' ORDER BY created_at, user_id LIMIT 1;`;
 }
 /** The sites of the database. */
 function sitesQuery() {
@@ -150,21 +154,41 @@ function sitesQuery() {
 }
 /** The row of a new token. */
 function insertToken(token) {
-	return `INSERT INTO tokens (id, site_id, user_id, label, hash, scopes, expires_at, created_at, updated_at) VALUES (${quote(token.id)}, ${quote(token.site)}, ${quote(token.userId)}, ${quote(token.label)}, ${quote(token.hash)}, ${quote(JSON.stringify(token.scopes))}, ${quote(token.expiresAt)}, ${quote(token.now)}, ${quote(token.now)});`;
+	const kind = token.kind === void 0 ? ["", ""] : [", kind", `, ${quote(token.kind)}`];
+	return `INSERT INTO tokens (id, site_id, user_id, label, hash, scopes, expires_at, created_at, updated_at${kind[0]}) VALUES (${quote(token.id)}, ${quote(token.site)}, ${quote(token.userId)}, ${quote(token.label)}, ${quote(token.hash)}, ${quote(JSON.stringify(token.scopes))}, ${quote(token.expiresAt)}, ${quote(token.now)}, ${quote(token.now)}${kind[1]});`;
 }
 /**
-* What `init` writes, in one script: the site (left alone if it is already there), its owner
-* and the owner's first token.
+* What `init` writes, in one script: the site (left alone if it is already there), its owner, a
+* member of the site with the role owner, and the owner's first token. `users.role` gets the
+* owner too, the one name of a role that its CHECK and `members` share.
 */
-function initScript({ site, ownerId, ownerName, token }) {
+function initScript({ site, ownerId, memberId, ownerName, token }) {
 	const name = ownerName === void 0 ? "NULL" : quote(ownerName);
 	return [
 		`INSERT INTO sites (id, created_at, updated_at) VALUES (${quote(site)}, ${quote(token.now)}, ${quote(token.now)}) ON CONFLICT (id) DO NOTHING;`,
 		`INSERT INTO users (id, name, role, created_at, updated_at) VALUES (${quote(ownerId)}, ${name}, 'owner', ${quote(token.now)}, ${quote(token.now)});`,
+		`INSERT INTO members (id, site_id, user_id, role, created_at, updated_at) VALUES (${quote(memberId)}, ${quote(site)}, ${quote(ownerId)}, 'owner', ${quote(token.now)}, ${quote(token.now)});`,
+		insertToken(token),
+		""
+	].join("\n");
+}
+/**
+* What `init` writes for a site of a deployment that has an owner already: the site, the owner as
+* its owner too (one person across the sites of a deployment), and a token of that site.
+*/
+function anotherSiteScript({ site, ownerId, memberId, token }) {
+	return [
+		`INSERT INTO sites (id, created_at, updated_at) VALUES (${quote(site)}, ${quote(token.now)}, ${quote(token.now)}) ON CONFLICT (id) DO NOTHING;`,
+		`INSERT INTO members (id, site_id, user_id, role, created_at, updated_at) VALUES (${quote(memberId)}, ${quote(site)}, ${quote(ownerId)}, 'owner', ${quote(token.now)}, ${quote(token.now)});`,
 		insertToken(token),
 		""
 	].join("\n");
 }
+/** The row of an invitation (ADR-026): the owner's setup link, or an invitation with a role. */
+function insertInvitation(invitation) {
+	const user = invitation.userId === null ? "NULL" : quote(invitation.userId);
+	return `INSERT INTO invitations (id, site_id, hash, role, user_id, expires_at, used_at, created_at, updated_at) VALUES (${quote(invitation.id)}, ${quote(invitation.site)}, ${quote(invitation.hash)}, ${quote(invitation.role)}, ${user}, ${quote(invitation.expiresAt)}, NULL, ${quote(invitation.now)}, ${quote(invitation.now)});`;
+}
 /** The tokens of a site. It never selects the hash. */
 function listTokens(site) {
 	return `SELECT id, label, scopes, expires_at, revoked_at, last_used_at, created_at FROM tokens WHERE site_id = ${quote(site)} ORDER BY created_at, id;`;
@@ -266,16 +290,24 @@ function readAnswer(result, database, target) {
 		}
 		throw new CliError(`wrangler could not run the SQL: ${reason}`);
 	}
-	let json;
-	try {
-		json = JSON.parse(result.stdout);
-	} catch {
-		throw new CliError(`wrangler did not answer with JSON: ${failureReason(result)}`);
-	}
+	const json = jsonOf(result.stdout);
+	if (json === void 0) throw new CliError(`wrangler did not answer with JSON: ${failureReason(result)}`);
 	const answer = Answer.safeParse(json);
 	if (!answer.success) throw new CliError("wrangler answered with JSON that has an unexpected shape.");
 	if (answer.data.some((statement) => !statement.success)) throw new CliError("wrangler reported that a statement did not succeed.");
 	return answer.data.map((statement) => statement.results);
 }
+/**
+* The JSON of an answer of `wrangler d1 execute --json`: all of stdout, or, when wrangler printed a
+* warning before it (a config it finds incomplete, an update that is out), what follows the first
+* line that opens the array. `undefined` when there is no JSON. Reading past a warning matters:
+* `hollware init` prints its token only after the SQL answered, so a failure here loses it.
+*/
+function jsonOf(stdout) {
+	const attempts = [stdout, ...stdout.split("\n").flatMap((line, index, lines) => line.trimStart().startsWith("[") ? [lines.slice(index).join("\n")] : [])];
+	for (const text of attempts) try {
+		return JSON.parse(text);
+	} catch {}
+}
 //#endregion
-export { sitesAndOwnerQuery as _, runFile as a, listTokens as c, parseLabel as d, parseOwnerName as f, revokeToken as g, parseTokenId as h, resolveDatabase as i, ownerQuery as l, parseSiteKey as m, describeDatabase as n, initScript as o, parseScopes as p, query as r, insertToken as s, chooseTarget as t, parseExpiresInDays as u, sitesQuery as v };
+export { parseJsonc as S, parseSiteKey as _, runFile as a, sitesAndOwnerQuery as b, insertInvitation as c, ownerOfSiteQuery as d, ownerQuery as f, parseScopes as g, parseOwnerName as h, resolveDatabase as i, insertToken as l, parseLabel as m, describeDatabase as n, anotherSiteScript as o, parseExpiresInDays as p, query as r, initScript as s, chooseTarget as t, listTokens as u, parseTokenId as v, sitesQuery as x, revokeToken as y };

package/dist/deploy-B89D8gdO.mjs

@@ -0,0 +1,101 @@
+import { r as CliError } from "./format-BpRYEsGB.mjs";
+import { n as failureReason, r as stripAnsi } from "./wrangler-BLIfwbcu.mjs";
+import { t as parseFlags } from "./args-CljWh-kZ.mjs";
+import { f as ownerQuery, i as resolveDatabase, r as query } from "./d1-D5A6OVDD.mjs";
+import { t as publicUrlOf } from "./public-url-DURHzCaC.mjs";
+import { i as migrate } from "./migrate-D6Sgxnwx.mjs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/commands/deploy.ts
+const DEPLOY_USAGE = [
+	"Usage: hollware deploy [--url <url>]",
+	"",
+	"Deploys the project to Cloudflare with its wrangler, and applies the migrations to the remote",
+	"database. The first deploy creates the D1 database, the KV namespace and the queues that",
+	"wrangler.jsonc names without an id, and writes their ids into it: commit them.",
+	"",
+	"HOLLWARE_PUBLIC_URL must be the public URL of the Worker. While it is a localhost URL, the",
+	"workers.dev URL that wrangler prints is written into wrangler.jsonc, and the Worker is deployed",
+	"again with it. Run \"wrangler login\" first.",
+	"",
+	"Options:",
+	"  --url <url>  The public URL of the Worker, such as https://cms.example.com (default: the",
+	"               HOLLWARE_PUBLIC_URL of wrangler.jsonc, or the workers.dev URL)",
+	"  --help       Show this help"
+].join("\n");
+/** The workers.dev URL that `wrangler deploy` prints, or `undefined`. */
+function workersDevUrlOf(stdout) {
+	const match = /https:\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.workers\.dev(?![\w.-])/i.exec(stripAnsi(stdout));
+	return match === null ? void 0 : new URL(match[0]).origin;
+}
+/** Whether a URL is this machine's: the one `pnpm dev` serves, which no deploy answers at. */
+function isLoopback(url) {
+	const { hostname } = new URL(url);
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+const PUBLIC_URL_VALUE = /("HOLLWARE_PUBLIC_URL"\s*:\s*)"[^"\n]*"/;
+/**
+* `wrangler.jsonc` with `HOLLWARE_PUBLIC_URL` set to `url`, and everything else as it was: its
+* comments, its order and its spacing. It changes the one string and nothing around it.
+*/
+function withPublicUrl(text, url) {
+	if (!PUBLIC_URL_VALUE.test(text)) throw new CliError("wrangler.jsonc has no \"HOLLWARE_PUBLIC_URL\" in \"vars\". Add it, with the public URL of the Worker.");
+	return text.replace(PUBLIC_URL_VALUE, (_match, key) => `${key}${JSON.stringify(url)}`);
+}
+async function wranglerDeploy(io) {
+	const deployed = await io.wrangler(["deploy"]);
+	if (deployed.code !== 0) throw new CliError(`wrangler could not deploy: ${failureReason(deployed)}. Is wrangler logged in ("wrangler login")?`);
+	return deployed.stdout;
+}
+async function deploy(argv, io) {
+	const { values } = parseFlags({
+		args: [...argv],
+		allowPositionals: false,
+		options: {
+			url: { type: "string" },
+			help: { type: "boolean" }
+		}
+	});
+	if (values.help === true) {
+		io.out(DEPLOY_USAGE);
+		return 0;
+	}
+	const file = join(io.cwd, "wrangler.jsonc");
+	if (!existsSync(file)) throw new CliError(`${file} is missing: run hollware deploy in the directory of the project.`);
+	const configured = publicUrlOf(io.cwd, void 0);
+	const asked = values.url === void 0 ? void 0 : publicUrlOf(io.cwd, values.url);
+	const database = resolveDatabase(io.cwd, void 0);
+	io.out("Deploying with wrangler ...");
+	const printed = await wranglerDeploy(io);
+	let url = asked ?? (configured !== void 0 && !isLoopback(configured) ? configured : void 0);
+	url ??= workersDevUrlOf(printed);
+	if (url === void 0) throw new CliError("wrangler deployed the Worker but printed no workers.dev URL. Run \"hollware deploy --url <the public URL of the Worker>\".");
+	if (url !== configured) {
+		writeFileSync(file, withPublicUrl(readFileSync(file, "utf8"), url));
+		io.out(`Set HOLLWARE_PUBLIC_URL to ${url} in wrangler.jsonc. Deploying again with it ...`);
+		await wranglerDeploy(io);
+	}
+	await migrate([
+		"--remote",
+		"--database",
+		database
+	], io);
+	const [owners = []] = await query(io.wrangler, database, "remote", ownerQuery());
+	io.out([
+		`Hollware is live at ${url}.`,
+		"",
+		`  MCP    ${url}/mcp`,
+		`  Admin  ${url}/admin/`,
+		"",
+		"Commit wrangler.jsonc: it holds the ids of what the deploy created, and the public URL.",
+		...owners.length === 0 ? [
+			"",
+			"Next: create your site and its owner in the remote database, with the key of the site in",
+			"hollware.config.ts. It prints a token for your agents and a link to set up your passkey:",
+			"  hollware init --site <key> --remote"
+		] : []
+	].join("\n"));
+	return 0;
+}
+//#endregion
+export { deploy };

package/dist/doctor-Djx_3mLE.mjs

@@ -0,0 +1,113 @@
+import { r as CliError } from "./format-BpRYEsGB.mjs";
+import { n as failureReason } from "./wrangler-BLIfwbcu.mjs";
+import { t as parseFlags } from "./args-CljWh-kZ.mjs";
+import { S as parseJsonc, f as ownerQuery, r as query, t as chooseTarget } from "./d1-D5A6OVDD.mjs";
+import { a as parsePendingMigrations } from "./migrate-D6Sgxnwx.mjs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+//#region src/commands/doctor.ts
+const DOCTOR_USAGE = [
+	"Usage: hollware doctor [--local | --remote]",
+	"",
+	"Checks the project in the current directory: its wrangler.jsonc, the bindings and flags",
+	"Hollware needs, the built files of the admin, the migrations of the database and its owner.",
+	"Each problem comes with what to do about it. Exits with code 1 when something is wrong.",
+	"",
+	"Options:",
+	"  --local   Check the local database (the default)",
+	"  --remote  Check the database in Cloudflare",
+	"  --help    Show this help"
+].join("\n");
+/** The flags of `compatibility_flags` that Hollware runs with (ADR-018, ADR-026). */
+const REQUIRED_FLAGS = [
+	"no_nodejs_compat",
+	"no_nodejs_compat_v2",
+	"global_fetch_strictly_public"
+];
+const pass = (what) => ({
+	ok: true,
+	what
+});
+const fail = (what, fix) => ({
+	ok: false,
+	what,
+	fix
+});
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function records(value) {
+	return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+/** What `wrangler.jsonc` says, checked without reaching Cloudflare or the database. */
+function checkConfig(cwd, config) {
+	const findings = [];
+	const flags = Array.isArray(config["compatibility_flags"]) ? config["compatibility_flags"] : [];
+	const missing = REQUIRED_FLAGS.filter((flag) => !flags.includes(flag));
+	findings.push(missing.length === 0 ? pass(`compatibility_flags has ${REQUIRED_FLAGS.join(", ")}`) : fail(`compatibility_flags lacks ${missing.join(", ")}`, `Add ${missing.map((flag) => `"${flag}"`).join(", ")} to compatibility_flags in wrangler.jsonc.`));
+	const url = (isRecord(config["vars"]) ? config["vars"] : {})["HOLLWARE_PUBLIC_URL"];
+	const urlOk = typeof url === "string" && URL.canParse(url) && /^https?:$/.test(new URL(url).protocol);
+	findings.push(urlOk ? pass(`HOLLWARE_PUBLIC_URL is ${new URL(url).origin}`) : fail("HOLLWARE_PUBLIC_URL is missing or is no http or https URL", "Set vars.HOLLWARE_PUBLIC_URL in wrangler.jsonc to the public URL of the Worker, such as https://cms.example.com."));
+	const db = records(config["d1_databases"]).find((entry) => entry["binding"] === "DB");
+	const migrationsDir = db !== void 0 && typeof db["migrations_dir"] === "string" ? join(cwd, db["migrations_dir"]) : void 0;
+	const migrations = migrationsDir !== void 0 && existsSync(migrationsDir) ? readdirSync(migrationsDir).filter((name) => name.endsWith(".sql")) : [];
+	findings.push(db === void 0 ? fail(`there is no D1 binding "DB"`, "Add it to d1_databases in wrangler.jsonc, as the starter has it.") : migrations.length === 0 ? fail(`the D1 binding "DB" has no migrations in its migrations_dir`, "Set migrations_dir to \"node_modules/@hollware/server/migrations\", and install the dependencies.") : pass(`the D1 binding "DB" has ${migrations.length} migrations`));
+	const kv = records(config["kv_namespaces"]).some((entry) => entry["binding"] === "OAUTH_KV");
+	findings.push(kv ? pass("the KV binding \"OAUTH_KV\" is there") : fail("there is no KV binding \"OAUTH_KV\", which the OAuth server needs", "Add { \"binding\": \"OAUTH_KV\" } to kv_namespaces in wrangler.jsonc."));
+	const assets = isRecord(config["assets"]) ? config["assets"] : void 0;
+	const directory = typeof assets?.["directory"] === "string" ? assets["directory"] : void 0;
+	const admin = directory !== void 0 && existsSync(join(cwd, directory, "admin"));
+	findings.push(admin ? pass("the admin is built, in the static assets") : fail("the static assets do not hold the admin", "Install the dependencies; assets.directory of wrangler.jsonc must be \"node_modules/@hollware/admin/dist/client\"."));
+	return findings;
+}
+/** What the database says: the migrations it lacks and whether it has an owner. */
+async function checkDatabase(io, target) {
+	const listed = await io.wrangler([
+		"d1",
+		"migrations",
+		"list",
+		"DB",
+		`--${target}`
+	]);
+	if (listed.code !== 0) return [fail(`wrangler could not list the migrations of the ${target} database: ${failureReason(listed)}`, target === "remote" ? "Run \"wrangler login\", then \"hollware deploy\"." : "Check wrangler.jsonc.")];
+	const pending = parsePendingMigrations(listed.stdout);
+	if (pending.length > 0) return [fail(`the ${target} database lacks ${pending.length} ${pending.length === 1 ? "migration" : "migrations"}`, `Run "hollware migrate --${target}".`)];
+	const [owners = []] = await query(io.wrangler, "DB", target, ownerQuery());
+	return [pass(`the ${target} database has every migration`), owners.length > 0 ? pass(`the ${target} database has an owner`) : fail(`the ${target} database has no owner yet`, `Run "hollware init --site <key> --${target}", with the key of your site in hollware.config.ts.`)];
+}
+async function doctor(argv, io) {
+	const { values } = parseFlags({
+		args: [...argv],
+		allowPositionals: false,
+		options: {
+			local: { type: "boolean" },
+			remote: { type: "boolean" },
+			help: { type: "boolean" }
+		}
+	});
+	if (values.help === true) {
+		io.out(DOCTOR_USAGE);
+		return 0;
+	}
+	const target = chooseTarget(values);
+	const file = join(io.cwd, "wrangler.jsonc");
+	if (!existsSync(file)) throw new CliError(`${file} is missing: run hollware doctor in the directory of the project.`);
+	let config;
+	try {
+		config = parseJsonc(readFileSync(file, "utf8"));
+	} catch (error) {
+		throw new CliError(`wrangler.jsonc is not valid JSONC: ${String(error)}`);
+	}
+	if (!isRecord(config)) throw new CliError("wrangler.jsonc holds no object.");
+	const findings = [...checkConfig(io.cwd, config), ...await checkDatabase(io, target)];
+	io.out(findings.map((finding) => finding.ok ? `ok    ${finding.what}` : `FAIL  ${finding.what}\n      ${finding.fix ?? ""}`).join("\n"));
+	const failed = findings.filter((finding) => !finding.ok).length;
+	if (failed === 0) {
+		io.out("Everything Hollware needs is in place.");
+		return 0;
+	}
+	io.err(`hollware doctor: ${failed} ${failed === 1 ? "problem" : "problems"} to fix.`);
+	return 1;
+}
+//#endregion
+export { doctor };

package/dist/entropy-5uxirwFD.mjs

@@ -0,0 +1,27 @@
+import { ID_PREFIXES, generatePersonalToken, generateReadToken, ulid } from "@hollware/core";
+//#region src/entropy.ts
+/** A new id of a kind, such as `usr_01JAB…`, from the clock and the random source of `io`. */
+function newId(io, kind) {
+	return `${ID_PREFIXES[kind]}_${ulid(io.now().getTime(), io.randomBytes(10))}`;
+}
+/** A new personal token (`hw_pat_` and 52 characters) from the random source of `io`. */
+function newPersonalToken(io) {
+	return generatePersonalToken(io.randomBytes(52));
+}
+/** A new read token (`hw_read_`), from the same randomness. */
+function newReadToken(io) {
+	return generateReadToken(io.randomBytes(52));
+}
+const DAY_MS = 864e5;
+/** The moment, in ISO 8601 UTC, that is `days` days after `from`. */
+function inDays(from, days) {
+	return new Date(from.getTime() + days * DAY_MS).toISOString();
+}
+/** A new invitation secret (`hw_inv_` and 43 base64url characters) from the random source of `io`. */
+function newInvitationSecret(io) {
+	let binary = "";
+	for (const byte of io.randomBytes(32)) binary += String.fromCharCode(byte);
+	return `hw_inv_${btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")}`;
+}
+//#endregion
+export { newReadToken as a, newPersonalToken as i, newId as n, newInvitationSecret as r, inDays as t };

package/dist/{import-Dlpn_w3s.mjs → import-DG8AABZQ.mjs}

@@ -195,7 +195,8 @@ const IMPORT_USAGE = [
 	"  --dry-run            Only validate: write nothing, publish nothing",
 	"  --help               Show this help",
 	"",
-	"The token needs content:read and content:write, and content:publish for --publish."
+	"The token needs content:read and content:write, and content:publish for --publish: without it,",
+	"each entry asks for a review, which a person who may publish approves in the admin."
 ].join("\n");
 async function importContent(argv, io) {
 	const { values, positionals } = parseFlags({
@@ -263,7 +264,7 @@ async function importFiles({ io, token, endpoint, directory, root, publish: publ
 		if (drafts.failed > 0) throw new CliError(`${count(drafts.failed, "file")} could not be imported (see above).${publishToo ? " Nothing was published." : ""} Fix ${drafts.failed === 1 ? "it" : "them"} and run the import again: what is already there stays unchanged.`);
 		if (!publishToo) return 0;
 		const published = await publishAll(session, drafts.entries.filter((imported) => imported.summary.hasUnpublishedChanges), out);
-		out(`Publishing: ${published.published} published, ${published.needsAcknowledgement} need acknowledgement, ${published.blocked} blocked${published.other === 0 ? "" : `, ${published.other} failed`}.`);
+		out(`Publishing: ${published.published} published, ${published.needsAcknowledgement} need acknowledgement, ${published.blocked} blocked${published.reviews === 0 ? "" : `, ${published.reviews} asked for review`}${published.other === 0 ? "" : `, ${published.other} failed`}.`);
 		const problems = published.needsAcknowledgement + published.blocked + published.other;
 		if (problems > 0) throw new CliError(`${count(problems, "entry", "entries")} not published: warnings are never acknowledged here, and errors block publishing. Fix the content and run the import again with --publish: what is already published is skipped.`);
 		return 0;
@@ -442,50 +443,89 @@ function draftLine(kind, label, entry, verdict) {
 	const notes = [errors > 0 ? count(errors, "error") : void 0, warnings > 0 ? count(warnings, "warning") : void 0].filter((note) => note !== void 0);
 	return `${kind.padEnd(9)}  ${label}  ${entry.id}  v${entry.version}${notes.length === 0 ? "" : ` (${notes.join(", ")})`}`;
 }
+/** The most entries one publish takes: the entry and a group of 99 (ADR-024). */
+const GROUP_SIZE = 100;
 /**
-* Phase two: publishes each imported entry that has unpublished changes, at the version phase
-* one left it. It acknowledges no warning: an entry with warnings is reported, not published.
+* Phase two: publishes the imported entries that have unpublished changes, at the version phase
+* one left them, as one group (in groups of 100), so that entries that link to each other are
+* published together (ADR-024). When an entry stops its group, it is reported and taken out, and
+* the rest is published again without it. It acknowledges no warning: an entry with warnings is
+* reported, not published. A token without content:publish may only ask for a review of a lone
+* entry (`pending_review`): its group is refused, and then every entry asks on its own.
 */
 async function publishAll(session, entries, out) {
 	const result = {
 		published: 0,
 		needsAcknowledgement: 0,
 		blocked: 0,
+		reviews: 0,
 		other: 0
 	};
-	for (const { file, summary } of entries) {
-		const label = printable(file.path.replace(/\.md$/, ""));
-		const line = (outcome, details = []) => [`${outcome.padEnd(21)}  ${label}  ${summary.id}`, ...details.map((detail) => `    ${detail}`)].join("\n");
-		try {
-			const answer = await session.call(publish, {
-				id: summary.id,
-				version: summary.version
-			});
+	const labelOf = ({ file }) => printable(file.path.replace(/\.md$/, ""));
+	const line = (imported, outcome, details = []) => [`${outcome.padEnd(21)}  ${labelOf(imported)}  ${imported.summary.id}`, ...details.map((detail) => `    ${detail}`)].join("\n");
+	/**
+	* Whether entries go one by one, once a group was refused: a token without content:publish may
+	* only ask for a review of a lone entry.
+	*/
+	let alone = false;
+	for (let start = 0; start < entries.length; start += GROUP_SIZE) {
+		let pending = entries.slice(start, start + GROUP_SIZE);
+		while (pending.length > 0) {
+			const [first, ...rest] = pending;
+			if (first === void 0) break;
+			const batch = alone ? [first] : pending;
+			let answer;
+			try {
+				answer = await session.call(publish, {
+					id: first.summary.id,
+					version: first.summary.version,
+					...alone ? {} : { group: rest.map(({ summary }) => ({
+						id: summary.id,
+						version: summary.version
+					})) }
+				});
+			} catch (error) {
+				if (!(error instanceof ToolFailure)) throw error;
+				if (!alone && batch.length > 1) {
+					alone = true;
+					continue;
+				}
+				for (const imported of batch) out(line(imported, "failed", [error.message]));
+				result.other += batch.length;
+				pending = pending.filter((imported) => !batch.includes(imported));
+				continue;
+			}
+			if (answer.outcome === "published" || answer.outcome === "scheduled") {
+				for (const imported of batch) out(line(imported, "published"));
+				result.published += batch.length;
+				pending = pending.filter((imported) => !batch.includes(imported));
+				continue;
+			}
+			if (answer.outcome === "pending_review") {
+				for (const imported of batch) out(line(imported, "pending_review"));
+				result.reviews += batch.length;
+				pending = pending.filter((imported) => !batch.includes(imported));
+				continue;
+			}
+			const failed = batch.find(({ summary }) => summary.id === answer.failedEntry) ?? first;
 			switch (answer.outcome) {
-				case "published":
-					result.published += 1;
-					out(line("published"));
-					break;
 				case "needs_acknowledgement":
 					result.needsAcknowledgement += 1;
-					out(line("needs_acknowledgement", (answer.verdict?.warnings ?? []).map(violationLine)));
+					out(line(failed, "needs_acknowledgement", (answer.verdict?.warnings ?? []).map(violationLine)));
 					break;
 				case "blocked":
 					result.blocked += 1;
-					out(line("blocked", (answer.verdict?.errors ?? []).map(violationLine)));
+					out(line(failed, "blocked", (answer.verdict?.errors ?? []).map(violationLine)));
 					break;
 				case "conflict":
 					result.other += 1;
-					out(line("conflict", ["someone changed the entry after it was imported"]));
+					out(line(failed, "conflict", ["someone changed the entry after it was imported"]));
 					break;
 				case "not_found":
 					result.other += 1;
-					out(line("not_found", ["the entry is gone"]));
+					out(line(failed, "not_found", ["the entry is gone"]));
 			}
-		} catch (error) {
-			if (!(error instanceof ToolFailure)) throw error;
-			result.other += 1;
-			out(line("failed", [error.message]));
+			pending = pending.filter((imported) => imported !== failed);
 		}
 	}
 	return result;

package/dist/index.mjs

@@ -16,10 +16,22 @@ const COMMANDS = [
 		name: "migrate",
 		summary: "Apply D1 migrations"
 	},
+	{
+		name: "deploy",
+		summary: "Deploy to Cloudflare and migrate the remote database"
+	},
+	{
+		name: "doctor",
+		summary: "Check the project, its bindings, its database and its owner"
+	},
 	{
 		name: "token",
 		summary: "Create, list and revoke personal tokens"
 	},
+	{
+		name: "invite",
+		summary: "Invite a person to the admin, as an editor or an author"
+	},
 	{
 		name: "import",
 		summary: "Import Markdown files over MCP"
@@ -41,7 +53,8 @@ const USAGE = [
 	"  --version  Print the version",
 	"",
 	"Run \"hollware <command> --help\" for the options of a command.",
-	"init, migrate and token work on the project in the current directory, through its wrangler."
+	"init, migrate, deploy, doctor, token and invite work on the project in the current directory,",
+	"through its wrangler."
 ].join("\n");
 const TOKEN_COMMANDS = [
 	"create",
@@ -71,7 +84,10 @@ async function main(argv, io) {
 	if (![
 		"init",
 		"migrate",
+		"deploy",
+		"doctor",
 		"token",
+		"invite",
 		"import"
 	].includes(first)) {
 		io.err(`hollware: unknown command or flag "${printable(first)}"\n\n${USAGE}`);
@@ -89,10 +105,13 @@ async function main(argv, io) {
 }
 async function run(command, args, io) {
 	switch (command) {
-		case "init": return (await import("./init-Cl9Epsbp.mjs")).init(args, io);
-		case "migrate": return (await import("./migrate-CLHWuUje.mjs")).migrate(args, io);
-		case "token": return (await import("./token-BLkrPLio.mjs")).token(args, io);
-		default: return (await import("./import-Dlpn_w3s.mjs")).importContent(args, io);
+		case "init": return (await import("./init-D-q1JzcO.mjs")).init(args, io);
+		case "migrate": return (await import("./migrate-R7NAXgQT.mjs")).migrate(args, io);
+		case "deploy": return (await import("./deploy-B89D8gdO.mjs")).deploy(args, io);
+		case "doctor": return (await import("./doctor-Djx_3mLE.mjs")).doctor(args, io);
+		case "token": return (await import("./token-DeVLRP0z.mjs")).token(args, io);
+		case "invite": return (await import("./invite-PpZ5QNLx.mjs")).invite(args, io);
+		default: return (await import("./import-DG8AABZQ.mjs")).importContent(args, io);
 	}
 }
 function isEntryPoint() {

package/dist/init-D-q1JzcO.mjs

@@ -0,0 +1,189 @@
+import { i as UsageError, r as CliError } from "./format-BpRYEsGB.mjs";
+import { t as parseFlags } from "./args-CljWh-kZ.mjs";
+import { _ as parseSiteKey, a as runFile, c as insertInvitation, f as ownerQuery, h as parseOwnerName, i as resolveDatabase, n as describeDatabase, o as anotherSiteScript, r as query, s as initScript, t as chooseTarget } from "./d1-D5A6OVDD.mjs";
+import { n as setupLink, t as publicUrlOf } from "./public-url-DURHzCaC.mjs";
+import { i as newPersonalToken, n as newId, r as newInvitationSecret, t as inDays } from "./entropy-5uxirwFD.mjs";
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { PERSONAL_TOKEN_TTL_DAYS, SCOPES, hashPersonalToken } from "@hollware/core";
+//#region src/commands/init.ts
+const INIT_USAGE = [
+	"Usage: hollware init --site <key> [--local | --remote] [--owner-name <name>] [--database <name>] [--url <url>]",
+	"",
+	"Creates a site, its owner and the owner's first personal token in the project's D1 database,",
+	"in one step, and prints the token once, with a link to set up the passkey of the admin (valid",
+	"for 7 days). On a database that has an owner already, it adds the site to that owner, who signs",
+	"in to the admin as before, and prints a token of the new site. It does nothing when the site",
+	"has an owner.",
+	"Run \"hollware migrate\" first: the database needs its tables.",
+	"",
+	"Options:",
+	"  --site <key>         The site, by the key it has in hollware.config.ts (required)",
+	"  --local              Use the local database (the default)",
+	"  --remote             Use the database in Cloudflare",
+	"  --owner-name <name>  The name of the owner",
+	"  --database <name>    The D1 database, by name or binding (default: the binding \"DB\" of wrangler.jsonc)",
+	"  --url <url>          The public URL of Hollware, for the link (default: HOLLWARE_PUBLIC_URL of wrangler.jsonc)",
+	"  --help               Show this help"
+].join("\n");
+/** The label of the token `init` creates. */
+const FIRST_TOKEN_LABEL = "hollware init";
+async function init(argv, io) {
+	const { values } = parseFlags({
+		args: [...argv],
+		allowPositionals: false,
+		options: {
+			site: { type: "string" },
+			local: { type: "boolean" },
+			remote: { type: "boolean" },
+			"owner-name": { type: "string" },
+			database: { type: "string" },
+			url: { type: "string" },
+			help: { type: "boolean" }
+		}
+	});
+	if (values.help === true) {
+		io.out(INIT_USAGE);
+		return 0;
+	}
+	if (values.site === void 0) throw new UsageError("--site is required: name the site, as in hollware.config.ts.");
+	const site = parseSiteKey(values.site);
+	const ownerName = values["owner-name"] === void 0 ? void 0 : parseOwnerName(values["owner-name"]);
+	const target = chooseTarget(values);
+	const database = resolveDatabase(io.cwd, values.database);
+	const url = publicUrlOf(io.cwd, values.url);
+	const [owners = []] = await query(io.wrangler, database, target, ownerQuery());
+	const ofSite = owners.find((owner) => owner["site"] === site);
+	if (ofSite !== void 0) {
+		const id = typeof ofSite["id"] === "string" ? ` (${ofSite["id"]})` : "";
+		throw new CliError(`the site "${site}" already has an owner${id}, so there is nothing to set up. Create another token with "hollware token create --site ${site} --label <text>".`);
+	}
+	const [first] = owners;
+	if (first !== void 0 && typeof first["id"] === "string") return await addSite(io, {
+		site,
+		ownerId: first["id"],
+		database,
+		target
+	});
+	const now = io.now();
+	const timestamp = now.toISOString();
+	const ownerId = newId(io, "user");
+	const tokenId = newId(io, "token");
+	const secret = newPersonalToken(io);
+	const expiresAt = inDays(now, PERSONAL_TOKEN_TTL_DAYS);
+	const setupSecret = newInvitationSecret(io);
+	const setupExpiresAt = inDays(now, 7);
+	const setup = insertInvitation({
+		id: newId(io, "invitation"),
+		site,
+		hash: await hashPersonalToken(setupSecret),
+		role: "owner",
+		userId: ownerId,
+		expiresAt: setupExpiresAt,
+		now: timestamp
+	});
+	const memberId = newId(io, "member");
+	const script = initScript({
+		site,
+		ownerId,
+		memberId,
+		ownerName,
+		token: {
+			id: tokenId,
+			site,
+			userId: ownerId,
+			label: FIRST_TOKEN_LABEL,
+			hash: await hashPersonalToken(secret),
+			scopes: SCOPES,
+			expiresAt,
+			now: timestamp
+		}
+	}).concat(`${setup}\n`);
+	const directory = io.tempDir();
+	try {
+		const file = join(directory, "init.sql");
+		writeFileSync(file, script, { mode: 384 });
+		await runFile(io.wrangler, database, target, file);
+	} finally {
+		rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+	}
+	io.out([
+		`Hollware is ready on ${describeDatabase(target, database)}.`,
+		"",
+		`Site     ${site}`,
+		`Owner    ${ownerId}`,
+		`Token    ${tokenId}`,
+		`Scopes   ${SCOPES.join(" ")}`,
+		`Expires  ${expiresAt} (in ${PERSONAL_TOKEN_TTL_DAYS} days)`,
+		"",
+		"Your personal token. It is shown only once: Hollware keeps just its hash.",
+		"",
+		secret,
+		"",
+		`Set up your passkey for the admin, once, by ${setupExpiresAt}:`,
+		`  ${setupLink(url, setupSecret)}`,
+		"",
+		"Next:",
+		"  Save the token in a file only you can read, then import content:",
+		"    hollware import <directory> --url <your Hollware URL> --token-file <file>",
+		"  An MCP client sends it as the header \"Authorization: Bearer <token>\" to <your Hollware URL>/mcp.",
+		"  More tokens: hollware token create --label <text>"
+	].join("\n"));
+	return 0;
+}
+/** `init` for one more site of a deployment whose owner exists: that owner owns the new site too. */
+async function addSite(io, where) {
+	const { site, ownerId, database, target } = where;
+	const now = io.now();
+	const timestamp = now.toISOString();
+	const tokenId = newId(io, "token");
+	const secret = newPersonalToken(io);
+	const expiresAt = inDays(now, PERSONAL_TOKEN_TTL_DAYS);
+	const script = anotherSiteScript({
+		site,
+		ownerId,
+		memberId: newId(io, "member"),
+		token: {
+			id: tokenId,
+			site,
+			userId: ownerId,
+			label: FIRST_TOKEN_LABEL,
+			hash: await hashPersonalToken(secret),
+			scopes: SCOPES,
+			expiresAt,
+			now: timestamp
+		}
+	});
+	const directory = io.tempDir();
+	try {
+		const file = join(directory, "init.sql");
+		writeFileSync(file, script, { mode: 384 });
+		await runFile(io.wrangler, database, target, file);
+	} finally {
+		rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+	}
+	io.out([
+		`Added the site "${site}" on ${describeDatabase(target, database)}, owned by the owner of the database.`,
+		"",
+		`Site     ${site}`,
+		`Owner    ${ownerId}`,
+		`Token    ${tokenId}`,
+		`Scopes   ${SCOPES.join(" ")}`,
+		`Expires  ${expiresAt} (in ${PERSONAL_TOKEN_TTL_DAYS} days)`,
+		"",
+		"A personal token of the new site. It is shown only once: Hollware keeps just its hash.",
+		"",
+		secret,
+		"",
+		"The owner signs in to the admin as before, with the same passkey, and switches to the site."
+	].join("\n"));
+	return 0;
+}
+//#endregion
+export { init };

package/dist/invite-PpZ5QNLx.mjs

@@ -0,0 +1,88 @@
+import { i as UsageError, r as CliError } from "./format-BpRYEsGB.mjs";
+import { t as parseFlags } from "./args-CljWh-kZ.mjs";
+import { _ as parseSiteKey, c as insertInvitation, d as ownerOfSiteQuery, i as resolveDatabase, p as parseExpiresInDays, r as query, t as chooseTarget, x as sitesQuery } from "./d1-D5A6OVDD.mjs";
+import { n as setupLink, t as publicUrlOf } from "./public-url-DURHzCaC.mjs";
+import { n as newId, r as newInvitationSecret, t as inDays } from "./entropy-5uxirwFD.mjs";
+import { o as WHERE_OPTIONS, s as chooseSite } from "./token-aUnd79vh.mjs";
+import { hashPersonalToken } from "@hollware/core";
+//#region src/commands/invite.ts
+const INVITE_USAGE = [
+	"Usage: hollware invite (--role <editor | author> | --owner) [--days <n>] [--url <url>]",
+	"                       [--site <key>] [--local | --remote] [--database <name>]",
+	"",
+	"Invites a person to the admin (ADR-026): prints a link, valid once and for 7 days by default,",
+	"where they set up a passkey. An editor reads, writes and publishes; an author reads and writes,",
+	"and what an author publishes goes through review. With --owner, the link is for the owner of",
+	"the site, to set up a passkey: on a deployment that was made before the admin existed, or on a",
+	"new device.",
+	"",
+	"Options:",
+	"  --role <role>      editor or author",
+	"  --owner            A setup link for the owner of the site, instead of a new person",
+	"  --days <n>         Days until the link expires, 1 to 365 (default: 7)",
+	"  --url <url>        The public URL of Hollware (default: HOLLWARE_PUBLIC_URL of wrangler.jsonc)",
+	"  --site <key>       The site (default: the only site of the database)",
+	"  --local            Use the local database (the default)",
+	"  --remote           Use the database in Cloudflare",
+	"  --database <name>  The D1 database, by name or binding (default: the binding \"DB\" of wrangler.jsonc)",
+	"  --help             Show this help"
+].join("\n");
+/** The role of `--role`: editor or author, and nothing else. */
+function roleOf(value) {
+	if (value === "editor" || value === "author") return value;
+	throw new UsageError("--role is required, and it is editor or author.");
+}
+async function invite(argv, io) {
+	const { values } = parseFlags({
+		args: [...argv],
+		allowPositionals: false,
+		options: {
+			...WHERE_OPTIONS,
+			role: { type: "string" },
+			owner: { type: "boolean" },
+			days: { type: "string" },
+			url: { type: "string" }
+		}
+	});
+	if (values.help === true) {
+		io.out(INVITE_USAGE);
+		return 0;
+	}
+	const forOwner = values.owner === true;
+	if (forOwner && values.role !== void 0) throw new UsageError("--owner and --role cannot be used together: choose one.");
+	const role = forOwner ? "owner" : roleOf(values.role);
+	const days = values.days === void 0 ? 7 : parseExpiresInDays(values.days);
+	const siteFlag = values.site === void 0 ? void 0 : parseSiteKey(values.site);
+	const target = chooseTarget(values);
+	const database = resolveDatabase(io.cwd, values.database);
+	const url = publicUrlOf(io.cwd, values.url);
+	const [siteRows = []] = await query(io.wrangler, database, target, sitesQuery());
+	const site = chooseSite(siteRows, siteFlag);
+	let userId = null;
+	if (forOwner) {
+		const [owners = []] = await query(io.wrangler, database, target, ownerOfSiteQuery(site));
+		const [owner] = owners;
+		if (owner === void 0 || typeof owner["id"] !== "string") throw new CliError(`the site "${site}" has no owner. Run "hollware init" to make one.`);
+		userId = owner["id"];
+	}
+	const now = io.now();
+	const secret = newInvitationSecret(io);
+	const expiresAt = inDays(now, days);
+	await query(io.wrangler, database, target, insertInvitation({
+		id: newId(io, "invitation"),
+		site,
+		hash: await hashPersonalToken(secret),
+		role,
+		userId,
+		expiresAt,
+		now: now.toISOString()
+	}));
+	io.out([
+		userId === null ? `Invited an ${role} to the site "${site}". The link works once, until ${expiresAt}:` : `A setup link for the owner (${userId}) of the site "${site}", to set up a passkey. It works once, until ${expiresAt}:`,
+		"",
+		`  ${setupLink(url, secret)}`
+	].join("\n"));
+	return 0;
+}
+//#endregion
+export { invite };

package/dist/{migrate-CLHWuUje.mjs → migrate-D6Sgxnwx.mjs}

@@ -1,7 +1,7 @@
 import { r as CliError } from "./format-BpRYEsGB.mjs";
 import { n as failureReason, r as stripAnsi } from "./wrangler-BLIfwbcu.mjs";
 import { t as parseFlags } from "./args-CljWh-kZ.mjs";
-import { i as resolveDatabase, n as describeDatabase, t as chooseTarget } from "./d1-Bd-sdoDd.mjs";
+import { i as resolveDatabase, n as describeDatabase, t as chooseTarget } from "./d1-D5A6OVDD.mjs";
 import { existsSync, mkdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 //#region src/commands/migrate.ts
@@ -10,7 +10,8 @@ const MIGRATE_USAGE = [
 	"",
 	"Applies the D1 migrations the project has not applied yet, with wrangler. Before it applies",
 	"anything to the remote database it exports a backup, and it stops if the backup fails. The",
-	"export can make the database unavailable for a moment; with nothing pending there is no backup.",
+	"export can make the database unavailable for a moment; with nothing pending, or on a new",
+	"database that has none of the migrations yet, there is no backup.",
 	"",
 	"Options:",
 	"  --local            Use the local database (the default)",
@@ -19,6 +20,8 @@ const MIGRATE_USAGE = [
 	"  --database <name>  The D1 database, by name or binding (default: the binding \"DB\" of wrangler.jsonc)",
 	"  --help             Show this help"
 ].join("\n");
+/** The first migration of the server: a database that lacks it has no Hollware tables yet. */
+const FIRST_MIGRATION = "0000_init.sql";
 /** Where the backups before a remote migration go, below the project: wrangler's own, git-ignored folder. */
 const BACKUP_DIRECTORY = join(".wrangler", "hollware-backups");
 async function migrate(argv, io) {
@@ -58,7 +61,8 @@ async function migrate(argv, io) {
 		io.out([`${count} pending on ${where}:`, ...pending.map((name) => `  ${name}`)].join("\n"));
 		throw new CliError(`${count} pending. Run "hollware migrate --${target}" to apply them.`);
 	}
-	const backup = target === "remote" ? await takeBackup(io, database) : void 0;
+	const fresh = pending.includes(FIRST_MIGRATION);
+	const backup = target === "remote" && !fresh ? await takeBackup(io, database) : void 0;
 	const applied = await io.wrangler([
 		"d1",
 		"migrations",
@@ -115,4 +119,4 @@ function timestamp(date) {
 	return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
 }
 //#endregion
-export { migrate };
+export { parsePendingMigrations as a, migrate as i, FIRST_MIGRATION as n, MIGRATE_USAGE as r, BACKUP_DIRECTORY as t };

package/dist/migrate-R7NAXgQT.mjs

@@ -0,0 +1,2 @@
+import { i as migrate } from "./migrate-D6Sgxnwx.mjs";
+export { migrate };

package/dist/public-url-DURHzCaC.mjs

@@ -0,0 +1,32 @@
+import { i as UsageError } from "./format-BpRYEsGB.mjs";
+import { S as parseJsonc } from "./d1-D5A6OVDD.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/public-url.ts
+/**
+* The public URL of the project's Hollware, for the links the CLI prints: `--url` when given,
+* else `vars.HOLLWARE_PUBLIC_URL` of the project's `wrangler.jsonc`, else `undefined`.
+*/
+function publicUrlOf(cwd, flag) {
+	if (flag !== void 0) {
+		if (!URL.canParse(flag)) throw new UsageError(`--url is no URL: ${flag}`);
+		return new URL(flag).origin;
+	}
+	const file = ["wrangler.jsonc", "wrangler.json"].map((name) => join(cwd, name)).find(existsSync);
+	if (file === void 0) return void 0;
+	let config;
+	try {
+		config = parseJsonc(readFileSync(file, "utf8"));
+	} catch {
+		return;
+	}
+	const vars = typeof config === "object" && config !== null && "vars" in config ? config.vars : void 0;
+	const url = typeof vars === "object" && vars !== null && "HOLLWARE_PUBLIC_URL" in vars ? vars.HOLLWARE_PUBLIC_URL : void 0;
+	return typeof url === "string" && URL.canParse(url) ? new URL(url).origin : void 0;
+}
+/** The link that lets a person set up a passkey with an invitation. */
+function setupLink(url, secret) {
+	return `${url ?? "<your Hollware URL>"}/setup?invitation=${secret}`;
+}
+//#endregion
+export { setupLink as n, publicUrlOf as t };

package/dist/token-DeVLRP0z.mjs

@@ -0,0 +1,2 @@
+import { c as token } from "./token-aUnd79vh.mjs";
+export { token };

package/dist/{token-BLkrPLio.mjs → token-aUnd79vh.mjs}

@@ -1,7 +1,7 @@
 import { i as UsageError, n as table, r as CliError, t as printable } from "./format-BpRYEsGB.mjs";
 import { t as parseFlags } from "./args-CljWh-kZ.mjs";
-import { _ as sitesAndOwnerQuery, c as listTokens, d as parseLabel, g as revokeToken, h as parseTokenId, i as resolveDatabase, m as parseSiteKey, p as parseScopes, r as query, s as insertToken, t as chooseTarget, u as parseExpiresInDays, v as sitesQuery } from "./d1-Bd-sdoDd.mjs";
-import { n as newId, r as newPersonalToken, t as inDays } from "./entropy-CIYbTHkj.mjs";
+import { _ as parseSiteKey, b as sitesAndOwnerQuery, g as parseScopes, i as resolveDatabase, l as insertToken, m as parseLabel, p as parseExpiresInDays, r as query, t as chooseTarget, u as listTokens, v as parseTokenId, x as sitesQuery, y as revokeToken } from "./d1-D5A6OVDD.mjs";
+import { a as newReadToken, i as newPersonalToken, n as newId, t as inDays } from "./entropy-5uxirwFD.mjs";
 import { PERSONAL_TOKEN_TTL_DAYS, hashPersonalToken } from "@hollware/core";
 //#region src/commands/token.ts
 const WHERE_FLAGS = [
@@ -22,13 +22,16 @@ const TOKEN_USAGE = [
 	"Run \"hollware token <command> --help\" for the options of a command."
 ].join("\n");
 const TOKEN_CREATE_USAGE = [
-	"Usage: hollware token create --label <text> [--scopes <list>] [--expires-in-days <n>]",
+	"Usage: hollware token create --label <text> [--scopes <list> | --read] [--expires-in-days <n>]",
 	"                             [--site <key>] [--local | --remote] [--database <name>]",
 	"",
 	"Creates a personal token for the site's owner and prints it once; Hollware keeps only its hash.",
+	"With --read, a read token (hw_read_): it reads the published content of the site over the read",
+	"API (GET /v1/...) and nothing else, so a site may use it at build time or in the browser.",
 	"",
 	"Options:",
 	"  --label <text>          What the token is for, 1 to 64 characters (required)",
+	"  --read                  A read token: content:read, published content, the read API only",
 	"  --scopes <list>         Comma-separated: content:read, content:write, content:publish, schema:admin",
 	"                          (default: content:read,content:write)",
 	`  --expires-in-days <n>   Days until it expires, 1 to 365 (default: ${PERSONAL_TOKEN_TTL_DAYS})`,
@@ -80,6 +83,7 @@ async function createToken(argv, io) {
 			...WHERE_OPTIONS,
 			label: { type: "string" },
 			scopes: { type: "string" },
+			read: { type: "boolean" },
 			"expires-in-days": { type: "string" }
 		}
 	});
@@ -87,10 +91,12 @@ async function createToken(argv, io) {
 		io.out(TOKEN_CREATE_USAGE);
 		return 0;
 	}
+	const read = values.read === true;
+	if (read && values.scopes !== void 0) throw new UsageError("--read and --scopes cannot be used together: a read token only reads.");
 	if (values.label === void 0) throw new UsageError("--label is required: say what the token is for, such as \"ci\" or \"claude-code\".");
 	const label = parseLabel(values.label);
 	const siteFlag = values.site === void 0 ? void 0 : parseSiteKey(values.site);
-	const scopes = values.scopes === void 0 ? DEFAULT_SCOPES : parseScopes(values.scopes);
+	const scopes = read ? ["content:read"] : values.scopes === void 0 ? DEFAULT_SCOPES : parseScopes(values.scopes);
 	const days = values["expires-in-days"] === void 0 ? PERSONAL_TOKEN_TTL_DAYS : parseExpiresInDays(values["expires-in-days"]);
 	const target = chooseTarget(values);
 	const database = resolveDatabase(io.cwd, values.database);
@@ -100,9 +106,10 @@ async function createToken(argv, io) {
 	if (ownerId === void 0) throw new CliError("the database has no owner yet. Run \"hollware init --site <key>\" first.");
 	const now = io.now();
 	const id = newId(io, "token");
-	const secret = newPersonalToken(io);
+	const secret = read ? newReadToken(io) : newPersonalToken(io);
 	const expiresAt = inDays(now, days);
 	await query(io.wrangler, database, target, insertToken({
+		...read ? { kind: "read" } : {},
 		id,
 		site,
 		userId: ownerId,
@@ -113,7 +120,7 @@ async function createToken(argv, io) {
 		now: now.toISOString()
 	}));
 	io.out([
-		`Created token ${id} for the site "${site}".`,
+		`Created ${read ? "read token" : "token"} ${id} for the site "${site}".`,
 		"",
 		`Label    ${label}`,
 		`Scopes   ${scopes.join(" ")}`,
@@ -225,4 +232,4 @@ function scopesOf(value) {
 	return printable(value);
 }
 //#endregion
-export { token };
+export { TOKEN_USAGE as a, token as c, TOKEN_REVOKE_USAGE as i, TOKEN_CREATE_USAGE as n, WHERE_OPTIONS as o, TOKEN_LIST_USAGE as r, chooseSite as s, DEFAULT_SCOPES as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hollware",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "The Hollware CLI: init, migrate, token, import and export.",
   "homepage": "https://hollware.com",
   "bugs": {
@@ -31,7 +31,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@hollware/core": "0.2.0",
+    "@hollware/core": "0.4.0",
     "@modelcontextprotocol/client": "2.3.1",
     "zod": "4.6.5"
   },

package/dist/entropy-CIYbTHkj.mjs

@@ -1,17 +0,0 @@
-import { ID_PREFIXES, generatePersonalToken, ulid } from "@hollware/core";
-//#region src/entropy.ts
-/** A new id of a kind, such as `usr_01JAB…`, from the clock and the random source of `io`. */
-function newId(io, kind) {
-	return `${ID_PREFIXES[kind]}_${ulid(io.now().getTime(), io.randomBytes(10))}`;
-}
-/** A new personal token (`hw_pat_` and 52 characters) from the random source of `io`. */
-function newPersonalToken(io) {
-	return generatePersonalToken(io.randomBytes(52));
-}
-const DAY_MS = 864e5;
-/** The moment, in ISO 8601 UTC, that is `days` days after `from`. */
-function inDays(from, days) {
-	return new Date(from.getTime() + days * DAY_MS).toISOString();
-}
-//#endregion
-export { newId as n, newPersonalToken as r, inDays as t };

package/dist/init-Cl9Epsbp.mjs

@@ -1,108 +0,0 @@
-import { i as UsageError, r as CliError } from "./format-BpRYEsGB.mjs";
-import { t as parseFlags } from "./args-CljWh-kZ.mjs";
-import { a as runFile, f as parseOwnerName, i as resolveDatabase, l as ownerQuery, m as parseSiteKey, n as describeDatabase, o as initScript, r as query, t as chooseTarget } from "./d1-Bd-sdoDd.mjs";
-import { n as newId, r as newPersonalToken, t as inDays } from "./entropy-CIYbTHkj.mjs";
-import { rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { PERSONAL_TOKEN_TTL_DAYS, SCOPES, hashPersonalToken } from "@hollware/core";
-//#region src/commands/init.ts
-const INIT_USAGE = [
-	"Usage: hollware init --site <key> [--local | --remote] [--owner-name <name>] [--database <name>]",
-	"",
-	"Creates a site, its owner and the owner's first personal token in the project's D1 database,",
-	"in one step, and prints the token once. It does nothing when the database already has an owner.",
-	"Run \"hollware migrate\" first: the database needs its tables.",
-	"",
-	"Options:",
-	"  --site <key>         The site, by the key it has in hollware.config.ts (required)",
-	"  --local              Use the local database (the default)",
-	"  --remote             Use the database in Cloudflare",
-	"  --owner-name <name>  The name of the owner",
-	"  --database <name>    The D1 database, by name or binding (default: the binding \"DB\" of wrangler.jsonc)",
-	"  --help               Show this help"
-].join("\n");
-/** The label of the token `init` creates. */
-const FIRST_TOKEN_LABEL = "hollware init";
-async function init(argv, io) {
-	const { values } = parseFlags({
-		args: [...argv],
-		allowPositionals: false,
-		options: {
-			site: { type: "string" },
-			local: { type: "boolean" },
-			remote: { type: "boolean" },
-			"owner-name": { type: "string" },
-			database: { type: "string" },
-			help: { type: "boolean" }
-		}
-	});
-	if (values.help === true) {
-		io.out(INIT_USAGE);
-		return 0;
-	}
-	if (values.site === void 0) throw new UsageError("--site is required: name the site, as in hollware.config.ts.");
-	const site = parseSiteKey(values.site);
-	const ownerName = values["owner-name"] === void 0 ? void 0 : parseOwnerName(values["owner-name"]);
-	const target = chooseTarget(values);
-	const database = resolveDatabase(io.cwd, values.database);
-	const [owners = []] = await query(io.wrangler, database, target, ownerQuery());
-	const [existing] = owners;
-	if (existing !== void 0) {
-		const id = typeof existing.id === "string" ? ` (${existing.id})` : "";
-		throw new CliError(`the database already has an owner${id}, so there is nothing to set up. Create another token with "hollware token create --label <text>".`);
-	}
-	const now = io.now();
-	const timestamp = now.toISOString();
-	const ownerId = newId(io, "user");
-	const tokenId = newId(io, "token");
-	const secret = newPersonalToken(io);
-	const expiresAt = inDays(now, PERSONAL_TOKEN_TTL_DAYS);
-	const script = initScript({
-		site,
-		ownerId,
-		ownerName,
-		token: {
-			id: tokenId,
-			site,
-			userId: ownerId,
-			label: FIRST_TOKEN_LABEL,
-			hash: await hashPersonalToken(secret),
-			scopes: SCOPES,
-			expiresAt,
-			now: timestamp
-		}
-	});
-	const directory = io.tempDir();
-	try {
-		const file = join(directory, "init.sql");
-		writeFileSync(file, script, { mode: 384 });
-		await runFile(io.wrangler, database, target, file);
-	} finally {
-		rmSync(directory, {
-			recursive: true,
-			force: true
-		});
-	}
-	io.out([
-		`Hollware is ready on ${describeDatabase(target, database)}.`,
-		"",
-		`Site     ${site}`,
-		`Owner    ${ownerId}`,
-		`Token    ${tokenId}`,
-		`Scopes   ${SCOPES.join(" ")}`,
-		`Expires  ${expiresAt} (in ${PERSONAL_TOKEN_TTL_DAYS} days)`,
-		"",
-		"Your personal token. It is shown only once: Hollware keeps just its hash.",
-		"",
-		secret,
-		"",
-		"Next:",
-		"  Save the token in a file only you can read, then import content:",
-		"    hollware import <directory> --url <your Hollware URL> --token-file <file>",
-		"  An MCP client sends it as the header \"Authorization: Bearer <token>\" to <your Hollware URL>/mcp.",
-		"  More tokens: hollware token create --label <text>"
-	].join("\n"));
-	return 0;
-}
-//#endregion
-export { init };