create-hollware 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { cpSync, existsSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { basename, join, resolve } from "node:path";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
 import { parseArgs } from "node:util";
 //#region src/scaffold.ts
 const USAGE = [
@@ -21,6 +21,12 @@ const USAGE = [
 	"                   Whether the activity log keeps a keyed hash of each address (default: off)",
 	"  --audit-retention-days <n>",
 	"                   Days each line of the activity log is kept, 30 to 3650 (default: forever)",
+	"  --token-file <path>",
+	"                   Write the first token to this file (mode 0600) and print its path, not the token;",
+	"                   a file that exists is refused. Inside the project, it goes into .gitignore",
+	"  --json           One JSON object on stdout and nothing else: dir, then what \"hollware init\" says",
+	"                   (site, ownerId, tokenId, token or tokenFile, expiresAt, setupUrl, mcpUrl,",
+	"                   readApiUrl), the commands to start it and the MCP configuration",
 	"  --pm <npm|pnpm>  The package manager that installs (default: npm)",
 	"  --yes            Take the defaults: <dir> is my-hollware when it is not given",
 	"  --no-install     Do not install, migrate or make the site",
@@ -42,7 +48,6 @@ const WORKER_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const SITE_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** What `@hollware/*` and `hollware` say in the template's package.json. */
 const VERSION_PLACEHOLDER = "HOLLWARE_VERSION";
-const TOKEN = /hw_pat_[0-9a-hjkmnp-tv-z]{52}/;
 /** The choices of a run, from its arguments. */
 function readChoices(argv) {
 	const { values, positionals } = (() => {
@@ -60,7 +65,9 @@ function readChoices(argv) {
 					pm: { type: "string" },
 					yes: { type: "boolean" },
 					"no-install": { type: "boolean" },
-					"no-git": { type: "boolean" }
+					"no-git": { type: "boolean" },
+					"token-file": { type: "string" },
+					json: { type: "boolean" }
 				}
 			});
 		} catch (error) {
@@ -84,6 +91,8 @@ function readChoices(argv) {
 		pm,
 		install: values["no-install"] !== true,
 		git: values["no-git"] !== true,
+		tokenFile: values["token-file"],
+		json: values.json === true,
 		initFlags: [
 			...values.preset === void 0 ? [] : ["--preset", values.preset],
 			...values.locales === void 0 ? [] : ["--locales", values.locales],
@@ -105,6 +114,7 @@ function writeProject(io, target, choices) {
 	replaceIn(join(target, "wrangler.jsonc"), [
 		["\"name\": \"my-hollware\"", `"name": "${choices.name}"`],
 		["\"database_name\": \"my-hollware\"", `"database_name": "${choices.name}"`],
+		["\"bucket_name\": \"my-hollware-media\"", `"bucket_name": "${choices.name}-media"`],
 		["hollware-events", `${choices.name}-events`]
 	]);
 	for (const file of ["README.md"]) replaceIn(join(target, file), [["my-site", choices.site]]);
@@ -127,44 +137,109 @@ async function step(io, what, command, args, cwd) {
 	}
 	return result;
 }
+/** The environment variable that holds the token in an MCP client's configuration. */
+const TOKEN_VARIABLE = "HOLLWARE_TOKEN";
+/** The `.mcp.json` block of a Hollware: the URL of /mcp, and a header that names HOLLWARE_TOKEN. */
+function mcpJson(url) {
+	return JSON.stringify({ mcpServers: { hollware: {
+		type: "http",
+		url: `${url}/mcp`,
+		headers: { Authorization: `Bearer \${${TOKEN_VARIABLE}}` }
+	} } }, null, 2);
+}
+/** The `claude mcp add` line that names HOLLWARE_TOKEN instead of the token. */
+function claudeAddLine(url) {
+	return `claude mcp add --transport http hollware ${url}/mcp --header 'Authorization: Bearer \${${TOKEN_VARIABLE}}'`;
+}
+/** What `hollware init --json` prints, as far as this package reads it. */
+function readInitJson(stdout) {
+	try {
+		const parsed = JSON.parse(stdout);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return Object.fromEntries(Object.entries(parsed));
+	} catch {}
+	throw new CreateError(`"hollware init --json" did not answer with a JSON object:\n${stdout}`);
+}
 /** Makes the project, and everything it needs to run locally. */
 async function create(argv, io) {
 	const choices = readChoices(argv);
 	const target = resolve(io.cwd, choices.dir);
 	if (existsSync(target) && readdirSync(target).length > 0) throw new CreateError(`${target} is not empty: choose a new directory.`);
+	const tokenFile = choices.tokenFile === void 0 ? void 0 : resolve(io.cwd, choices.tokenFile);
+	if (tokenFile !== void 0 && existsSync(tokenFile)) throw new CreateError(`${tokenFile} exists already, and a token is never written over a file: choose another --token-file.`);
+	const say = (message) => {
+		if (!choices.json) io.out(message);
+	};
 	writeProject(io, target, choices);
-	io.out(`Created a Hollware project in ${target}.`);
+	say(`Created a Hollware project in ${target}.`);
+	if (tokenFile !== void 0) {
+		const inside = relative(target, tokenFile);
+		if (inside !== "" && !inside.startsWith("..") && !isAbsolute(inside)) appendFileSync(join(target, ".gitignore"), `\n# The token of "hollware init": never commit it.\n/${inside}\n`);
+	}
 	if (choices.git) await step(io, "git init", "git", ["init", "--quiet"], target);
+	const initArgs = [
+		"init",
+		"--site",
+		choices.site,
+		...choices.initFlags,
+		...tokenFile === void 0 ? [] : ["--token-file", tokenFile]
+	];
 	if (!choices.install) {
+		const next = [
+			`cd ${choices.dir}`,
+			`${choices.pm} install`,
+			`${choices.pm} exec vp fmt`,
+			`${choices.pm} exec hollware migrate --local`,
+			`${choices.pm} exec hollware ${initArgs.join(" ")} --local`
+		];
+		if (choices.json) {
+			io.out(JSON.stringify({
+				dir: target,
+				installed: false,
+				next
+			}));
+			return 0;
+		}
 		io.out([
 			"",
 			"Next:",
-			`  cd ${choices.dir}`,
-			`  ${choices.pm} install`,
-			`  ${choices.pm} exec hollware migrate --local`,
-			`  ${choices.pm} exec hollware init --site ${[choices.site, ...choices.initFlags].join(" ")} --local`
+			...next.map((line) => `  ${line}`)
 		].join("\n"));
 		return 0;
 	}
-	io.out(`Installing with ${choices.pm} ...`);
+	say(`Installing with ${choices.pm} ...`);
 	await step(io, "The install", choices.pm, ["install"], target);
+	await step(io, "The formatting", join(target, "node_modules", ".bin", "vp"), ["fmt"], target);
 	const hollware = join(target, "node_modules", ".bin", "hollware");
 	await step(io, "The migrations", hollware, ["migrate", "--local"], target);
 	const init = await step(io, "Making the site", hollware, [
-		"init",
-		"--site",
-		choices.site,
-		...choices.initFlags,
-		"--local"
+		...initArgs,
+		"--local",
+		...choices.json ? ["--json"] : []
 	], target);
+	const dev = `${choices.pm} exec hollware dev`;
+	if (choices.json) {
+		const made = readInitJson(init.stdout.trim());
+		const url = typeof made["mcpUrl"] === "string" ? made["mcpUrl"].replace(/\/mcp$/, "") : void 0;
+		io.out(JSON.stringify({
+			dir: target,
+			installed: true,
+			...made,
+			devCommand: dev,
+			adminUrl: url === void 0 ? null : `${url}/admin/`,
+			mcpConfig: url === void 0 ? null : {
+				variable: TOKEN_VARIABLE,
+				claudeCode: claudeAddLine(url),
+				json: JSON.parse(mcpJson(url))
+			}
+		}));
+		return 0;
+	}
 	io.out(init.stdout.trim());
-	const token = TOKEN.exec(init.stdout)?.[0] ?? "<the token above>";
 	io.out([
 		"",
-		"Start it, and connect your agent (Claude Code):",
+		"Start it:",
 		`  cd ${choices.dir}`,
-		`  ${choices.pm === "npm" ? "npm run dev" : "pnpm dev"}`,
-		`  claude mcp add --transport http hollware http://localhost:5199/mcp --header "Authorization: Bearer ${token}"`,
+		`  ${dev}`,
 		"",
 		"The admin is at http://localhost:5199/admin/. To deploy, log in to Cloudflare and run:",
 		`  ${choices.pm} exec wrangler login`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-hollware",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "Create a new Hollware project.",
   "homepage": "https://hollware.com",
   "bugs": {

package/template/AGENTS.md

@@ -11,5 +11,10 @@ of the sites live in D1; this repository holds only the Worker.
 - Content is never edited in files here. Write it through the MCP tools (`create_draft`,
   `update_draft`, `validate`, `publish`) of the Hollware at `HOLLWARE_PUBLIC_URL` + `/mcp`.
 - Run `pnpm test` and `pnpm exec wrangler types --check` after a change of `wrangler.jsonc`, and `pnpm exec hollware doctor` when something does not work.
+- To update Hollware, move `hollware`, `@hollware/core`, `@hollware/server` and `@hollware/admin`
+  to one new version together, as exact versions
+  (`pnpm add -E hollware@X @hollware/core@X @hollware/server@X @hollware/admin@X`), read its
+  release notes, run `pnpm test`, then `pnpm exec hollware deploy`: it deploys the Worker and applies
+  the new migrations to the remote database. Migrations only move forward; content stays as it is.
 - Never commit a token. `hollware init` and `hollware token create` print one once.
 - Docs: https://hollware.com

package/template/package.json

@@ -7,6 +7,7 @@
     "dev": "vp dev",
     "build": "vp build",
     "test": "vp test",
+    "check": "vp check",
     "types": "wrangler types",
     "types:check": "wrangler types --check",
     "deploy": "hollware deploy",

package/template/test/worker.workerd.test.ts

@@ -79,6 +79,7 @@ describe('the database', () => {
 
     expect(results.map((row) => row.name)).toEqual([
       '_hollware_meta',
+      'assets',
       'audit_log',
       'auth_challenges',
       'deliveries',

package/template/vite.config.ts

@@ -2,8 +2,20 @@ import { cloudflare } from '@cloudflare/vite-plugin'
 import { adminAssets } from '@hollware/admin'
 import { defineConfig } from 'vite-plus'
 
-export default defineConfig({
-  plugins: [cloudflare()],
+/** Where `vp dev` serves Hollware: the URL of HOLLWARE_PUBLIC_URL before the first deploy. */
+const LOCAL_URL = 'http://localhost:5199'
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    cloudflare({
+      // `hollware deploy` writes the public URL into wrangler.jsonc, and the Worker answers only
+      // the Host of HOLLWARE_PUBLIC_URL: in development it is this machine's, whatever is deployed.
+      config:
+        command === 'serve'
+          ? (config) => ({ vars: { ...config.vars, HOLLWARE_PUBLIC_URL: LOCAL_URL } })
+          : undefined,
+    }),
+  ],
   // The admin's built files: served at /admin/ in development, and copied into the build, where
   // the Worker's static assets hold them.
   publicDir: adminAssets(),
@@ -15,4 +27,14 @@ export default defineConfig({
     // What you deploy is what the size budget of Hollware measures: minified.
     minify: true,
   },
-})
+  // `vp check` formats and lints the project as Hollware writes it. wrangler writes
+  // worker-configuration.d.ts, so neither touches it.
+  fmt: {
+    semi: false,
+    singleQuote: true,
+    ignorePatterns: ['dist/**', '.wrangler/**', 'worker-configuration.d.ts'],
+  },
+  lint: {
+    ignorePatterns: ['dist/**', '.wrangler/**', 'worker-configuration.d.ts'],
+  },
+}))

package/template/vitest.config.ts

@@ -17,8 +17,11 @@ export default defineConfig({
     cloudflareTest(async () => ({
       wrangler: { configPath: './wrangler.jsonc' },
       miniflare: {
-        // Read here in Node and applied inside workerd by the setup file.
         bindings: {
+          // The tests reach the Worker at localhost, whatever public URL `hollware deploy` wrote
+          // into wrangler.jsonc: it answers only the Host of HOLLWARE_PUBLIC_URL.
+          HOLLWARE_PUBLIC_URL: 'http://localhost:5199',
+          // Read here in Node and applied inside workerd by the setup file.
           TEST_MIGRATIONS: await readD1Migrations({
             projectPath: import.meta.dirname,
             migrationsDir,

package/template/worker-configuration.d.ts

@@ -1,11 +1,13 @@
 /* eslint-disable */
-// Generated by Wrangler by running `wrangler types` (hash: 8cce72e181db11068cbc639f31cd25a2)
+// Generated by Wrangler by running `wrangler types` (hash: f943445b38678ab7934813fd9b1a910b)
 // Runtime types generated with workerd@1.20261012.1 2026-10-06 global_fetch_strictly_public,no_nodejs_compat,no_nodejs_compat_v2
 interface __BaseEnv_Env {
 	OAUTH_KV: KVNamespace;
+	MEDIA: R2Bucket;
 	DB: D1Database;
 	EVENTS: Queue;
 	HOLLWARE_RATE_LIMIT: RateLimit;
+	IMAGES: ImagesBinding;
 	ASSETS: Fetcher;
 	HOLLWARE_PUBLIC_URL: "http://localhost:5199";
 }

package/template/wrangler.jsonc

@@ -59,4 +59,9 @@
       "migrations_dir": "node_modules/@hollware/server/migrations",
     },
   ],
+  // The images of the sites (ADR-038): the bucket that keeps them, which the first deploy creates,
+  // and the Images binding that converts each once when it arrives (to WebP by default). Without
+  // the binding, images are kept as they come; without the bucket, upload_asset is unavailable.
+  "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "my-hollware-media" }],
+  "images": { "binding": "IMAGES" },
 }