hollware 0.0.1 → 0.1.0

package/README.md

@@ -3,20 +3,59 @@
 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, not usable yet.** The binary answers `--help` and `--version`; every
-> command prints "not implemented yet" and exits with code 1.
+> **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
+> Windows.
 
-## What it will be
+## Commands
 
-The `hollware` command, with these planned commands:
+| Command   | Purpose                                                                          |
+| --------- | -------------------------------------------------------------------------------- |
+| `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                                          |
+| `import`  | Import Markdown files over MCP, as drafts, and publish them with `--publish`     |
+| `export`  | Export entries as Markdown files (v0.2)                                          |
 
-| Command   | Purpose                               |
-| --------- | ------------------------------------- |
-| `init`    | Set up Hollware in a project          |
-| `migrate` | Apply D1 migrations                   |
-| `token`   | Create, list and revoke access tokens |
-| `import`  | Import Markdown files over MCP        |
-| `export`  | Export entries as Markdown files      |
+Every command answers `--help`. A command that fails prints one message on stderr, with what to
+do, and exits with code 1.
+
+## A first run
+
+In a Hollware project (the starter has the D1 binding `DB` in its `wrangler.jsonc`):
+
+```sh
+hollware migrate                         # create the tables in the local database
+hollware init --site blog                # create the site and its owner; prints a token, once
+hollware token create --label ci --scopes content:read,content:write
+hollware token list                      # never shows a hash
+hollware token revoke tok_01JAB3XQ8ZK4M6N2P5R7S9T0VW
+```
+
+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
+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
+Markdown, laid out as `<collection>/<locale>/<slug>.md`, into a running Hollware:
+
+```sh
+hollware import ./content --url https://cms.example.com --token-file ./token.txt --dry-run
+hollware import ./content --url https://cms.example.com --token-file ./token.txt --publish
+```
+
+`import` validates every file first and writes nothing if one would be refused. Running it
+again changes nothing: every entry answers `unchanged`. With `--publish` it publishes the
+entries that have unpublished changes, and it acknowledges no warning: an entry with warnings is
+reported, and the command exits with code 1. The token never appears in its output.
+
+## How it works
+
+`init`, `migrate` 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`.
 
 ## Links
 

package/dist/args-CljWh-kZ.mjs

@@ -0,0 +1,20 @@
+import { i as UsageError } from "./format-BpRYEsGB.mjs";
+import { parseArgs } from "node:util";
+//#region src/args.ts
+/**
+* `parseArgs` in strict mode: an unknown option, a missing value or a stray argument is a
+* `UsageError` with one short sentence, instead of Node's error with its advice about `--`.
+*/
+function parseFlags(config) {
+	try {
+		return parseArgs(config);
+	} catch (error) {
+		if (error instanceof TypeError && "code" in error && String(error.code).startsWith("ERR_PARSE_ARGS_")) {
+			const [sentence = error.message] = error.message.split(". ");
+			throw new UsageError(`${sentence.charAt(0).toLowerCase()}${sentence.slice(1)}.`);
+		}
+		throw error;
+	}
+}
+//#endregion
+export { parseFlags as t };

package/dist/d1-Bd-sdoDd.mjs

@@ -0,0 +1,281 @@
+import { i as UsageError, r as CliError, t as printable } from "./format-BpRYEsGB.mjs";
+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";
+//#region src/jsonc.ts
+/**
+* Reads JSON with comments, the format of `wrangler.jsonc`: `//` and `/* *\/` comments and a
+* comma before a closing bracket are dropped, and a comment marker inside a string is left
+* alone. It does nothing else: whatever `JSON.parse` rejects after that is an error.
+*/
+function parseJsonc(text) {
+	return JSON.parse(stripJsonc(text));
+}
+function stripJsonc(text) {
+	const source = text.startsWith("") ? text.slice(1) : text;
+	let out = "";
+	let mode = "code";
+	for (let i = 0; i < source.length; i += 1) {
+		const char = source.charAt(i);
+		const next = source.charAt(i + 1);
+		if (mode === "string") {
+			out += char;
+			if (char === "\\") {
+				out += next;
+				i += 1;
+			} else if (char === "\"") mode = "code";
+		} else if (mode === "line-comment") {
+			if (char === "\n") {
+				out += char;
+				mode = "code";
+			}
+		} else if (mode === "block-comment") {
+			if (char === "*" && next === "/") {
+				i += 1;
+				mode = "code";
+			} else if (char === "\n") out += char;
+		} else if (char === "\"") {
+			out += char;
+			mode = "string";
+		} else if (char === "/" && next === "/") {
+			i += 1;
+			mode = "line-comment";
+		} else if (char === "/" && next === "*") {
+			i += 1;
+			mode = "block-comment";
+		} else out += char;
+	}
+	if (mode === "block-comment") throw new SyntaxError("a /* comment is never closed");
+	return dropTrailingCommas(out);
+}
+/** Drops a comma that only whitespace separates from a closing bracket, outside strings. */
+function dropTrailingCommas(code) {
+	let out = "";
+	let inString = false;
+	for (let i = 0; i < code.length; i += 1) {
+		const char = code.charAt(i);
+		if (inString) {
+			out += char;
+			if (char === "\\") {
+				out += code.charAt(i + 1);
+				i += 1;
+			} else if (char === "\"") inString = false;
+		} else if (char === "\"") {
+			out += char;
+			inString = true;
+		} else if (char === "," && /^\s*[}\]]/.test(code.slice(i + 1))) continue;
+		else out += char;
+	}
+	return out;
+}
+//#endregion
+//#region src/sql.ts
+/**
+* Everything the CLI says to the database. A value a person types is checked first and then
+* enters a statement only as a SQL string literal, `'` doubled, so it cannot become part of the
+* statement; the statements themselves are fixed templates. Nothing else in the package builds
+* SQL.
+*/
+/** A SQL string literal: the value in single quotes, with every single quote doubled. */
+function quote(value) {
+	if (value.includes("\0")) throw new TypeError("a SQL string cannot hold a NUL character");
+	return `'${value.replaceAll("'", "''")}'`;
+}
+/** A value a person typed, quoted and escaped for a message; invisible characters become `?`. */
+function shown(value) {
+	return printable(JSON.stringify(value));
+}
+/** A site key: lowercase letters and digits joined by single hyphens, like a slug. */
+function parseSiteKey(value) {
+	if (!isSiteKey(value)) throw new UsageError(`invalid --site ${shown(value)}: a site key is lowercase letters and digits joined by single hyphens, up to ${SITE_KEY_MAX_LENGTH} characters, such as "blog" or "my-site".`);
+	return value;
+}
+const LABEL_MAX = 64;
+const OWNER_NAME_MAX = 100;
+const FORBIDDEN_IN_TEXT = /[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/u;
+function parseText(value, flag, max) {
+	const text = value.trim();
+	const length = Array.from(text).length;
+	if (length < 1 || length > max || FORBIDDEN_IN_TEXT.test(text)) throw new UsageError(`invalid ${flag} ${shown(value)}: use 1 to ${max} characters, with no control or invisible formatting characters.`);
+	return text;
+}
+/** The label of a token: 1 to 64 characters, trimmed, with nothing that a terminal would act on. */
+function parseLabel(value) {
+	return parseText(value, "--label", LABEL_MAX);
+}
+/** The name of the owner: the same rules as a label, up to 100 characters. */
+function parseOwnerName(value) {
+	return parseText(value, "--owner-name", OWNER_NAME_MAX);
+}
+/** The scopes of `--scopes`: a comma-separated list of known scopes, without repeats. */
+function parseScopes(value) {
+	const names = value.split(",").map((name) => name.trim());
+	const scopes = [];
+	for (const name of names) {
+		if (!isScope(name)) throw new UsageError(`invalid --scopes: ${shown(name)} is not a scope. Choose from ${SCOPES.join(", ")}.`);
+		if (!scopes.includes(name)) scopes.push(name);
+	}
+	return scopes;
+}
+/** The days of `--expires-in-days`: a whole number from 1 to 365. */
+function parseExpiresInDays(value) {
+	const days = /^[0-9]{1,4}$/.test(value) ? Number(value) : 0;
+	if (days < 1 || days > 365) throw new UsageError(`invalid --expires-in-days ${shown(value)}: use a whole number of days from 1 to 365.`);
+	return days;
+}
+/** The id of a token, `tok_` and 26 characters, as `token list` shows it. */
+function parseTokenId(value) {
+	if (!isId("tok", value)) throw new UsageError(`invalid token id ${shown(value)}: a token id is tok_ followed by 26 characters. "hollware token list" shows them.`);
+	return value;
+}
+const DATABASE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+/** A D1 database, by name or by binding, as wrangler takes it. It never starts with a hyphen. */
+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. */
+function ownerQuery() {
+	return "SELECT id FROM users WHERE role = 'owner' LIMIT 1";
+}
+/** 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;";
+}
+/** The sites of the database. */
+function sitesQuery() {
+	return "SELECT id FROM sites ORDER BY id;";
+}
+/** 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)});`;
+}
+/**
+* What `init` writes, in one script: the site (left alone if it is already there), its owner
+* and the owner's first token.
+*/
+function initScript({ site, ownerId, 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)});`,
+		insertToken(token),
+		""
+	].join("\n");
+}
+/** 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;`;
+}
+/**
+* Revokes a token that is not revoked yet and tells what is stored for the id afterwards: the
+* first statement returns the id when it revoked the token, the second the row, if there is one.
+*/
+function revokeToken(id, site, now) {
+	const scope = site === void 0 ? "" : ` AND site_id = ${quote(site)}`;
+	return `UPDATE tokens SET revoked_at = ${quote(now)}, updated_at = ${quote(now)} WHERE id = ${quote(id)}${scope} AND revoked_at IS NULL RETURNING id; SELECT id, revoked_at FROM tokens WHERE id = ${quote(id)}${scope};`;
+}
+//#endregion
+//#region src/d1.ts
+/** The two flags that choose a target. A command without either works on the local database. */
+function chooseTarget(flags) {
+	if (flags.local === true && flags.remote === true) throw new UsageError("--local and --remote cannot be used together: choose one.");
+	return flags.remote === true ? "remote" : "local";
+}
+/** Where a command ran, for the messages: `the remote database "DB"`. */
+function describeDatabase(target, database) {
+	return `the ${target} database "${database}"`;
+}
+const CONFIG_FILES = ["wrangler.jsonc", "wrangler.json"];
+const WranglerConfig = z.looseObject({ d1_databases: z.array(z.looseObject({ binding: z.string() })).optional() });
+/**
+* The D1 database a command works on, as wrangler takes it (a name or a binding). `--database`
+* says it. Without it, it is the binding `DB` of the project's `wrangler.jsonc`, which the CLI
+* reads, as JSON with comments, and checks; it never loads `hollware.config.ts`.
+*/
+function resolveDatabase(cwd, database) {
+	if (database !== void 0) return parseDatabase(database);
+	const file = CONFIG_FILES.map((name) => join(cwd, name)).find((path) => existsSync(path));
+	if (file === void 0) {
+		const hint = existsSync(join(cwd, "wrangler.toml")) ? " (wrangler.toml is not read)" : "";
+		throw new CliError(`there is no wrangler.jsonc in ${cwd}${hint}. Run hollware from the project directory, or name the D1 database with --database <name>.`);
+	}
+	const bindings = readBindings(file);
+	if (bindings.includes("DB")) return "DB";
+	throw new CliError(bindings.length === 0 ? `${file} has no D1 database. Add a D1 binding named "DB" (the starter has one), or name the database with --database <name>.` : `${file} has no D1 binding named "DB" (it has ${bindings.join(", ")}). Rename the binding, or choose one with --database <name or binding>.`);
+}
+function readBindings(file) {
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch (error) {
+		throw new CliError(`could not read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	let json;
+	try {
+		json = parseJsonc(text);
+	} catch (error) {
+		throw new CliError(`${file} is not valid JSON with comments: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const config = WranglerConfig.safeParse(json);
+	if (!config.success) {
+		const [issue] = config.error.issues;
+		throw new CliError(`${file} has an unexpected shape at "${issue?.path.join(".") ?? ""}": ${issue?.message ?? "invalid"}`);
+	}
+	return (config.data.d1_databases ?? []).map((entry) => entry.binding);
+}
+const Answer = z.array(z.object({
+	results: z.array(z.record(z.string(), z.unknown())),
+	success: z.boolean()
+}));
+/**
+* Runs SQL through `wrangler d1 execute --json` and returns the rows of each statement, in
+* order. A database without the Hollware tables is reported with the command that creates them.
+*/
+async function query(wrangler, database, target, sql) {
+	return readAnswer(await wrangler([
+		"d1",
+		"execute",
+		database,
+		`--${target}`,
+		"--json",
+		"--command",
+		sql
+	]), database, target);
+}
+/** Runs the SQL of a file in one `wrangler d1 execute --json`: all of it, or none. */
+async function runFile(wrangler, database, target, file) {
+	readAnswer(await wrangler([
+		"d1",
+		"execute",
+		database,
+		`--${target}`,
+		"--json",
+		"--file",
+		file
+	]), database, target);
+}
+function readAnswer(result, database, target) {
+	if (result.code !== 0) {
+		const reason = failureReason(result);
+		if (reason.includes("no such table")) {
+			const flag = database === "DB" ? "" : ` --database ${database}`;
+			throw new CliError(`the database has no Hollware tables yet. Run "hollware migrate --${target}${flag}" first.`);
+		}
+		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 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);
+}
+//#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 };

package/dist/entropy-CIYbTHkj.mjs

@@ -0,0 +1,17 @@
+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/format-BpRYEsGB.mjs

@@ -0,0 +1,38 @@
+//#region src/errors.ts
+/**
+* An error the person at the keyboard can act on. `main` prints its message on stderr, behind
+* the name of the command, and exits with code 1. Anything that is not a `CliError` is a bug or
+* a broken install, and escapes with its stack trace.
+*/
+var CliError = class extends Error {
+	name = "CliError";
+};
+/**
+* A mistake in the arguments: an unknown option, a missing or a malformed value. `main` adds a
+* pointer to the help of the command after the message.
+*/
+var UsageError = class extends CliError {
+	name = "UsageError";
+};
+//#endregion
+//#region src/format.ts
+/**
+* Text for the terminal: a value that came from the database or from a server is made safe to
+* print, and rows are laid out in aligned columns.
+*/
+const UNSAFE_FOR_TERMINAL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu;
+/** `text` with every control or invisible formatting character replaced by `?`. */
+function printable(text) {
+	return text.replace(UNSAFE_FOR_TERMINAL, "?");
+}
+/** Rows of cells in columns as wide as their widest cell, separated by two spaces. */
+function table(header, rows) {
+	const all = [header, ...rows];
+	const widths = header.map((_, column) => Math.max(...all.map((row) => Array.from(row[column] ?? "").length)));
+	return all.map((row) => row.map((cell, column) => {
+		const padding = " ".repeat((widths[column] ?? 0) - Array.from(cell).length);
+		return column === row.length - 1 ? cell : `${cell}${padding}`;
+	}).join("  ")).join("\n");
+}
+//#endregion
+export { UsageError as i, table as n, CliError as r, printable as t };