create-acrylblends 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# create-acrylblends
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create an Acryl app with one command.
+
+```sh
+npm create acrylblends@latest my-app
+```
+
+It asks which template you want, creates `my-app`, and prints what to run next. Other package managers work the same way: `pnpm create acrylblends@latest`, `yarn create acrylblends`, `bun create acrylblends@latest`.
+
+## Templates
+
+| Template | What you get |
+| --- | --- |
+| `nodejs` | an Acryl app served with `serve()` from `acrylblends/node-server`, with a test; run with Node.js 22.19 or newer |
+| `bun` (experimental) | the same app for Bun, with `export default app` |
+| `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
+
+Every template includes `AGENTS.md`, `CLAUDE.md` and a copy of the framework documentation in `docs/framework/`, so a coding agent working in the folder reads the API from the folder.
+
+## Non-interactive use
+
+Arguments for the initializer go after `--` with `npm create`:
+
+```sh
+npm create acrylblends@latest my-app -- --template nodejs --install --pm npm
+```
+
+| Option | |
+| --- | --- |
+| `--template <name>` | `nodejs`, `bun` or `acryl-app` |
+| `--install` | install the dependencies after creating the app |
+| `--pm <manager>` | `npm`, `pnpm`, `yarn` or `bun` (default: the one that ran the command) |
+| `-y`, `--yes` | ask nothing: template `nodejs`, directory `acrylblends-app` unless given |
+
+## Then
+
+```sh
+cd my-app
+npm install     # unless you passed --install
+npm run dev     # prints its URL; GET / answers "Acryl!"
+npm test
+```
+
+```ts
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Acryl!'))
+
+export default app
+```
+
+## Links
+
+- Documentation: https://acrylblends.github.io/docs (mirrored at https://acryl.dev/docs)
+- The framework package: https://www.npmjs.com/package/acrylblends
+- Source and issues: https://github.com/acrylblends/acrylblends
+- Blends registry: https://acrylblends.github.io/blends
+- ACRYL: https://acryl.dev
+
+MIT license.

package/bin/create-acrylblends.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCreate } from '../dist/index.js'
+
+process.exitCode = await runCreate(process.argv.slice(2))

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+//#region src/names.d.ts
+/**
+ * The one place this package names the framework. The templates are written with `__PACKAGE__` and `__RANGE__`, and the text of `AGENTS.md` with
+ * `__PACKAGE__`, so a rename (for example to `acryl`) is a change here and in `scripts/lib/names.mjs`, which a test keeps equal.
+ */
+export declare const PACKAGE = "acrylblends";
+export declare const CLASS = "Acryl";
+export declare const CREATE = "create-acrylblends";
+/** The range of the framework package a created app depends on: the first release whose root is the framework. */
+export declare const RANGE = "^0.5.0";
+//#endregion
+//#region src/index.d.ts
+export declare const TEMPLATES: readonly ["nodejs", "bun", "acryl-app"];
+export type Template = (typeof TEMPLATES)[number];
+export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+/** The version of this package. */
+export declare const VERSION: string;
+export declare const HELP: string;
+/** A command line mistake. The command prints it with the help text and exits 2. */
+export declare class UsageError extends Error {
+  name: string;
+}
+export interface Io {
+  stdout: {
+    write(text: string): unknown;
+  };
+  stderr: {
+    write(text: string): unknown;
+  };
+  cwd: string;
+  env: Record<string, string | undefined>;
+  /** Ask one question; `undefined` when there is no terminal to ask on. */
+  ask: ((question: string) => Promise<string>) | undefined;
+  /** Run a program, showing its output; resolves to the exit code. */
+  run(command: string, args: string[], cwd: string): Promise<number>;
+}
+export declare function processIo(): Io;
+export interface CreateOptions {
+  directory: string | undefined;
+  template: Template | undefined;
+  install: boolean;
+  pm: PackageManager | undefined;
+  yes: boolean;
+}
+export declare function isTemplate(value: string): value is Template;
+export declare function parseCreateOptions(argv: readonly string[]): CreateOptions;
+/** A valid package name from a directory name: lower case letters, digits and dashes. */
+export declare function nameFrom(directory: string): string;
+export declare function replacePlaceholders(text: string, name: string): string;
+/** The guide for a coding agent in a created app: where the API is, how to run it, what must pass. */
+export declare function agentsText(template: Exclude<Template, 'acryl-app'>, name: string): string;
+/** Create the app. Returns the exit code: 0 done, 1 refused or failed, 2 a usage error. Never calls `process.exit`. */
+export declare function runCreate(argv: readonly string[], io?: Io): Promise<number>;
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,274 @@
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+//#region src/names.ts
+/**
+* The one place this package names the framework. The templates are written with `__PACKAGE__` and `__RANGE__`, and the text of `AGENTS.md` with
+* `__PACKAGE__`, so a rename (for example to `acryl`) is a change here and in `scripts/lib/names.mjs`, which a test keeps equal.
+*/
+const PACKAGE = "acrylblends";
+const CLASS = "Acryl";
+const CREATE = "create-acrylblends";
+/** The range of the framework package a created app depends on: the first release whose root is the framework. */
+const RANGE = "^0.5.0";
+//#endregion
+//#region src/index.ts
+const TEMPLATES = [
+	"nodejs",
+	"bun",
+	"acryl-app"
+];
+const PACKAGE_MANAGERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+];
+/** The version of this package. */
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+const HELP = `${CREATE} ${VERSION} - create an ${CLASS} app
+
+Usage:
+  npm create ${PACKAGE}@latest [directory] [-- options]
+
+Options:
+  --template <name>   nodejs, bun (experimental), acryl-app (asked when not given)
+  --install           install the dependencies after creating the app
+  --pm <manager>      ${PACKAGE_MANAGERS.join(", ")} (default: the one that ran this command, else npm)
+  -y, --yes           ask nothing: template nodejs unless --template is given, directory ${PACKAGE}-app
+  -h, --help          show this help
+  -v, --version       show the version
+`;
+/** A command line mistake. The command prints it with the help text and exits 2. */
+var UsageError = class extends Error {
+	name = "UsageError";
+};
+function processIo() {
+	const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	return {
+		stdout: process.stdout,
+		stderr: process.stderr,
+		cwd: process.cwd(),
+		env: process.env,
+		ask: interactive ? async (question) => {
+			const rl = createInterface({
+				input: process.stdin,
+				output: process.stdout
+			});
+			try {
+				return await rl.question(question);
+			} finally {
+				rl.close();
+			}
+		} : void 0,
+		run: (command, args, cwd) => new Promise((done) => {
+			const child = spawn(command, args, {
+				cwd,
+				stdio: "inherit",
+				shell: process.platform === "win32"
+			});
+			child.on("error", () => done(1));
+			child.on("exit", (code) => done(code ?? 1));
+		})
+	};
+}
+function isTemplate(value) {
+	return TEMPLATES.includes(value);
+}
+function parseCreateOptions(argv) {
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		throw new UsageError(error.message);
+	}
+	const { values, positionals } = parsed;
+	if (positionals.length > 1) throw new UsageError("takes at most one directory");
+	if (values.template !== void 0 && !isTemplate(values.template)) throw new UsageError(`unknown template "${values.template}" (${TEMPLATES.join(", ")})`);
+	if (values.pm !== void 0 && !PACKAGE_MANAGERS.includes(values.pm)) throw new UsageError(`unknown package manager "${values.pm}" (${PACKAGE_MANAGERS.join(", ")})`);
+	return {
+		directory: positionals[0],
+		template: values.template,
+		install: values.install === true,
+		pm: values.pm,
+		yes: values.yes === true
+	};
+}
+const parse = (argv) => parseArgs({
+	args: [...argv],
+	allowPositionals: true,
+	strict: true,
+	options: {
+		template: { type: "string" },
+		install: { type: "boolean" },
+		pm: { type: "string" },
+		yes: {
+			type: "boolean",
+			short: "y"
+		}
+	}
+});
+/** A valid package name from a directory name: lower case letters, digits and dashes. */
+function nameFrom(directory) {
+	const name = basename(resolve(directory)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^[^a-z]+/, "").replace(/-+$/g, "");
+	return name === "" ? "acryl-app" : name;
+}
+function walkUp(from, test) {
+	let dir = from;
+	for (;;) {
+		const found = test(dir);
+		if (found) return found;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error(`${CREATE} cannot find its files`);
+		dir = parent;
+	}
+}
+const here = dirname(fileURLToPath(import.meta.url));
+const templatesRoot = () => walkUp(here, (d) => existsSync(join(d, "templates", "nodejs")) ? join(d, "templates") : void 0);
+/** The framework docs: the copy `prepack` puts in the package, or `docs/framework` of the repository. */
+const docsRoot = () => walkUp(here, (d) => existsSync(join(d, "docs", "framework", "README.md")) ? join(d, "docs", "framework") : void 0);
+function replacePlaceholders(text, name) {
+	return text.replaceAll("__APP_NAME__", name).replaceAll("__PACKAGE__", PACKAGE).replaceAll("__CLASS__", CLASS).replaceAll("__RANGE__", RANGE);
+}
+/** The guide for a coding agent in a created app: where the API is, how to run it, what must pass. */
+function agentsText(template, name) {
+	const run = {
+		nodejs: "npm run dev",
+		bun: "bun run dev"
+	}[template];
+	const test = {
+		nodejs: "npm test` and `npm run check",
+		bun: "bun test` and `bun run check"
+	}[template];
+	return `# ${name}
+
+An ${CLASS} app (${template}${template === "bun" ? ", experimental" : ""}): handlers over the Web Standard \`Request\` and \`Response\`, from the \`${PACKAGE}\` package.
+
+## The framework's API is in \`docs/framework/\`
+
+Start at \`docs/framework/README.md\`; \`api/summary.md\` is the one-page summary. Import the class from \`'${PACKAGE}'\` and each middleware or helper from its own
+subpath (\`'${PACKAGE}/cors'\`, \`'${PACKAGE}/validator'\`, ...). Parts marked "not yet available" in the docs are not in the package yet.
+
+## This app
+
+Run it with \`${run}\`. The routes are in \`${template === "bun" ? "src/index.ts" : "src/app.ts"}\`; an app is a function from \`Request\` to \`Response\`,
+so test a route with \`await app.request('/path')\` and no server.
+
+## Things that surprise people
+
+- A page mounted at \`/x\` answers \`/x\`, not \`/x/\` (trailing slashes are strict); \`trimTrailingSlash()\` redirects.
+- A \`json\` validator target reads the body only with a JSON \`Content-Type\`; a failure answers 400 with \`{ error, issues: [{ message, path }] }\`.
+- \`throw new HTTPException(404, { message })\` answers an error response (plain text).
+
+## Before you say you are done
+
+\`${test}\` pass.
+`;
+}
+function copyDocs(target) {
+	const filter = (path) => !/(upstream\.json|UPSTREAM\.md)$/.test(path);
+	mkdirSync(join(target, "docs"), { recursive: true });
+	cpSync(docsRoot(), join(target, "docs", "framework"), {
+		recursive: true,
+		filter
+	});
+}
+function copyTemplate(template, target, name) {
+	const written = [];
+	const walk = (from, to, prefix) => {
+		mkdirSync(to, { recursive: true });
+		for (const entry of readdirSync(from, { withFileTypes: true })) {
+			const targetName = prefix === "" && entry.name === "gitignore" ? ".gitignore" : entry.name;
+			if (entry.isDirectory()) walk(join(from, entry.name), join(to, targetName), `${prefix}${entry.name}/`);
+			else {
+				writeFileSync(join(to, targetName), replacePlaceholders(readFileSync(join(from, entry.name), "utf8"), name));
+				written.push(`${prefix}${targetName}`);
+			}
+		}
+	};
+	walk(join(templatesRoot(), template), target, "");
+	writeFileSync(join(target, "AGENTS.md"), agentsText(template, name));
+	writeFileSync(join(target, "CLAUDE.md"), "@AGENTS.md\n");
+	copyDocs(target);
+	return written;
+}
+const isEmpty = (directory) => !existsSync(directory) || readdirSync(directory).length === 0;
+/** The `acrylblends` command of the installed framework package, which creates the `acryl-app` template. */
+function acrylblendsBin() {
+	const pkgFile = createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`);
+	const pkg = JSON.parse(readFileSync(pkgFile, "utf8"));
+	const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[PACKAGE];
+	if (!bin) throw new Error(`${PACKAGE} has no command to create an app with`);
+	return join(dirname(pkgFile), bin);
+}
+/** Create the app. Returns the exit code: 0 done, 1 refused or failed, 2 a usage error. Never calls `process.exit`. */
+async function runCreate(argv, io = processIo()) {
+	try {
+		if (argv.includes("-h") || argv.includes("--help")) {
+			io.stdout.write(HELP);
+			return 0;
+		}
+		if (argv.includes("-v") || argv.includes("--version")) {
+			io.stdout.write(`${VERSION}\n`);
+			return 0;
+		}
+		const options = parseCreateOptions(argv);
+		const ask = options.yes ? void 0 : io.ask;
+		const directory = options.directory ?? (ask ? (await ask(`Project directory (acrylblends-app): `)).trim() || `acrylblends-app` : `acrylblends-app`);
+		const target = resolve(io.cwd, directory);
+		const template = options.template ?? (ask ? await (async () => {
+			const answer = (await ask(`Which template do you want to use? (nodejs, bun (experimental), acryl-app) [nodejs]: `)).trim() || "nodejs";
+			if (!isTemplate(answer)) throw new UsageError(`unknown template "${answer}" (${TEMPLATES.join(", ")})`);
+			return answer;
+		})() : "nodejs");
+		if (!isEmpty(target)) {
+			io.stderr.write(`error: ${target} is not empty; nothing was changed\n`);
+			return 1;
+		}
+		const name = nameFrom(target);
+		if (template === "acryl-app") {
+			if (await io.run(process.execPath, [
+				acrylblendsBin(),
+				"init",
+				target,
+				"--template",
+				"agent",
+				"--name",
+				name,
+				"--yes"
+			], io.cwd) !== 0) return 1;
+		} else {
+			const files = copyTemplate(template, target, name);
+			io.stdout.write(`created ${name} (${template}) in ${target}: ${files.length} files, ${CLASS} docs in docs/framework\n`);
+		}
+		const pm = options.pm ?? PACKAGE_MANAGERS.find((m) => (io.env.npm_config_user_agent ?? "").startsWith(`${m}/`)) ?? "npm";
+		if (options.install) {
+			if (await io.run(pm, ["install"], target) !== 0) {
+				io.stderr.write(`error: ${pm} install failed; run it yourself in ${directory}\n`);
+				return 1;
+			}
+		}
+		const start = {
+			nodejs: `${pm} run dev`,
+			bun: "bun run dev",
+			"acryl-app": `${pm} run dev`
+		}[template];
+		io.stdout.write(`\nNext:\n  cd ${directory}\n${options.install ? "" : `  ${pm} install\n`}  ${start}\n`);
+		return 0;
+	} catch (error) {
+		if (error instanceof UsageError) {
+			io.stderr.write(`error: ${error.message}\n\n${HELP}`);
+			return 2;
+		}
+		io.stderr.write(`error: ${error.message}\n`);
+		return 1;
+	}
+}
+//#endregion
+export { CLASS, CREATE, HELP, PACKAGE, PACKAGE_MANAGERS, RANGE, TEMPLATES, UsageError, VERSION, agentsText, isTemplate, nameFrom, parseCreateOptions, processIo, replacePlaceholders, runCreate };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/names.ts","../src/index.ts"],"sourcesContent":["/**\n * The one place this package names the framework. The templates are written with `__PACKAGE__` and `__RANGE__`, and the text of `AGENTS.md` with\n * `__PACKAGE__`, so a rename (for example to `acryl`) is a change here and in `scripts/lib/names.mjs`, which a test keeps equal.\n */\nexport const PACKAGE = 'acrylblends'\nexport const CLASS = 'Acryl'\nexport const CREATE = 'create-acrylblends'\n/** The range of the framework package a created app depends on: the first release whose root is the framework. */\nexport const RANGE = '^0.5.0'\n","import { spawn } from 'node:child_process'\nimport { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'\nimport { createRequire } from 'node:module'\nimport { basename, dirname, join, resolve } from 'node:path'\nimport { createInterface } from 'node:readline/promises'\nimport { fileURLToPath } from 'node:url'\nimport { parseArgs } from 'node:util'\nimport { CLASS, CREATE, PACKAGE, RANGE } from './names'\n\nexport { CLASS, CREATE, PACKAGE, RANGE }\n\nexport const TEMPLATES = ['nodejs', 'bun', 'acryl-app'] as const\nexport type Template = (typeof TEMPLATES)[number]\nexport const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'] as const\nexport type PackageManager = (typeof PACKAGE_MANAGERS)[number]\n\n/** The version of this package. */\nexport const VERSION: string = (\n  createRequire(import.meta.url)('../package.json') as { version: string }\n).version\n\nexport const HELP = `${CREATE} ${VERSION} - create an ${CLASS} app\n\nUsage:\n  npm create ${PACKAGE}@latest [directory] [-- options]\n\nOptions:\n  --template <name>   nodejs, bun (experimental), acryl-app (asked when not given)\n  --install           install the dependencies after creating the app\n  --pm <manager>      ${PACKAGE_MANAGERS.join(', ')} (default: the one that ran this command, else npm)\n  -y, --yes           ask nothing: template nodejs unless --template is given, directory ${PACKAGE}-app\n  -h, --help          show this help\n  -v, --version       show the version\n`\n\n/** A command line mistake. The command prints it with the help text and exits 2. */\nexport class UsageError extends Error {\n  override name = 'UsageError'\n}\n\nexport interface Io {\n  stdout: { write(text: string): unknown }\n  stderr: { write(text: string): unknown }\n  cwd: string\n  env: Record<string, string | undefined>\n  /** Ask one question; `undefined` when there is no terminal to ask on. */\n  ask: ((question: string) => Promise<string>) | undefined\n  /** Run a program, showing its output; resolves to the exit code. */\n  run(command: string, args: string[], cwd: string): Promise<number>\n}\n\nexport function processIo(): Io {\n  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY)\n  return {\n    stdout: process.stdout,\n    stderr: process.stderr,\n    cwd: process.cwd(),\n    env: process.env,\n    ask: interactive\n      ? async (question) => {\n          const rl = createInterface({ input: process.stdin, output: process.stdout })\n          try {\n            return await rl.question(question)\n          } finally {\n            rl.close()\n          }\n        }\n      : undefined,\n    run: (command, args, cwd) =>\n      new Promise((done) => {\n        const child = spawn(command, args, {\n          cwd,\n          stdio: 'inherit',\n          shell: process.platform === 'win32',\n        })\n        child.on('error', () => done(1))\n        child.on('exit', (code) => done(code ?? 1))\n      }),\n  }\n}\n\nexport interface CreateOptions {\n  directory: string | undefined\n  template: Template | undefined\n  install: boolean\n  pm: PackageManager | undefined\n  yes: boolean\n}\n\nexport function isTemplate(value: string): value is Template {\n  return (TEMPLATES as readonly string[]).includes(value)\n}\n\nexport function parseCreateOptions(argv: readonly string[]): CreateOptions {\n  let parsed: ReturnType<typeof parse>\n  try {\n    parsed = parse(argv)\n  } catch (error) {\n    throw new UsageError((error as Error).message)\n  }\n  const { values, positionals } = parsed\n  if (positionals.length > 1) throw new UsageError('takes at most one directory')\n  if (values.template !== undefined && !isTemplate(values.template))\n    throw new UsageError(`unknown template \"${values.template}\" (${TEMPLATES.join(', ')})`)\n  if (values.pm !== undefined && !(PACKAGE_MANAGERS as readonly string[]).includes(values.pm))\n    throw new UsageError(`unknown package manager \"${values.pm}\" (${PACKAGE_MANAGERS.join(', ')})`)\n  return {\n    directory: positionals[0],\n    template: values.template as Template | undefined,\n    install: values.install === true,\n    pm: values.pm as PackageManager | undefined,\n    yes: values.yes === true,\n  }\n}\n\nconst parse = (argv: readonly string[]) =>\n  parseArgs({\n    args: [...argv],\n    allowPositionals: true,\n    strict: true,\n    options: {\n      template: { type: 'string' },\n      install: { type: 'boolean' },\n      pm: { type: 'string' },\n      yes: { type: 'boolean', short: 'y' },\n    },\n  })\n\n/** A valid package name from a directory name: lower case letters, digits and dashes. */\nexport function nameFrom(directory: string): string {\n  const name = basename(resolve(directory))\n    .toLowerCase()\n    .replace(/[^a-z0-9-]+/g, '-')\n    .replace(/^[^a-z]+/, '')\n    .replace(/-+$/g, '')\n  return name === '' ? 'acryl-app' : name\n}\n\nfunction walkUp(from: string, test: (dir: string) => string | undefined): string {\n  let dir = from\n  for (;;) {\n    const found = test(dir)\n    if (found) return found\n    const parent = dirname(dir)\n    if (parent === dir) throw new Error(`${CREATE} cannot find its files`)\n    dir = parent\n  }\n}\nconst here = dirname(fileURLToPath(import.meta.url))\nconst templatesRoot = () =>\n  walkUp(here, (d) =>\n    existsSync(join(d, 'templates', 'nodejs')) ? join(d, 'templates') : undefined,\n  )\n/** The framework docs: the copy `prepack` puts in the package, or `docs/framework` of the repository. */\nconst docsRoot = () =>\n  walkUp(here, (d) =>\n    existsSync(join(d, 'docs', 'framework', 'README.md'))\n      ? join(d, 'docs', 'framework')\n      : undefined,\n  )\n\nexport function replacePlaceholders(text: string, name: string): string {\n  return text\n    .replaceAll('__APP_NAME__', name)\n    .replaceAll('__PACKAGE__', PACKAGE)\n    .replaceAll('__CLASS__', CLASS)\n    .replaceAll('__RANGE__', RANGE)\n}\n\n/** The guide for a coding agent in a created app: where the API is, how to run it, what must pass. */\nexport function agentsText(template: Exclude<Template, 'acryl-app'>, name: string): string {\n  const run = { nodejs: 'npm run dev', bun: 'bun run dev' }[template]\n  const test = {\n    nodejs: 'npm test` and `npm run check',\n    bun: 'bun test` and `bun run check',\n  }[template]\n  return `# ${name}\n\nAn ${CLASS} app (${template}${template === 'bun' ? ', experimental' : ''}): handlers over the Web Standard \\`Request\\` and \\`Response\\`, from the \\`${PACKAGE}\\` package.\n\n## The framework's API is in \\`docs/framework/\\`\n\nStart at \\`docs/framework/README.md\\`; \\`api/summary.md\\` is the one-page summary. Import the class from \\`'${PACKAGE}'\\` and each middleware or helper from its own\nsubpath (\\`'${PACKAGE}/cors'\\`, \\`'${PACKAGE}/validator'\\`, ...). Parts marked \"not yet available\" in the docs are not in the package yet.\n\n## This app\n\nRun it with \\`${run}\\`. The routes are in \\`${template === 'bun' ? 'src/index.ts' : 'src/app.ts'}\\`; an app is a function from \\`Request\\` to \\`Response\\`,\nso test a route with \\`await app.request('/path')\\` and no server.\n\n## Things that surprise people\n\n- A page mounted at \\`/x\\` answers \\`/x\\`, not \\`/x/\\` (trailing slashes are strict); \\`trimTrailingSlash()\\` redirects.\n- A \\`json\\` validator target reads the body only with a JSON \\`Content-Type\\`; a failure answers 400 with \\`{ error, issues: [{ message, path }] }\\`.\n- \\`throw new HTTPException(404, { message })\\` answers an error response (plain text).\n\n## Before you say you are done\n\n\\`${test}\\` pass.\n`\n}\n\nfunction copyDocs(target: string): void {\n  const filter = (path: string) => !/(upstream\\.json|UPSTREAM\\.md)$/.test(path)\n  mkdirSync(join(target, 'docs'), { recursive: true })\n  cpSync(docsRoot(), join(target, 'docs', 'framework'), { recursive: true, filter })\n}\n\nfunction copyTemplate(\n  template: Exclude<Template, 'acryl-app'>,\n  target: string,\n  name: string,\n): string[] {\n  const written: string[] = []\n  const walk = (from: string, to: string, prefix: string) => {\n    mkdirSync(to, { recursive: true })\n    for (const entry of readdirSync(from, { withFileTypes: true })) {\n      const targetName = prefix === '' && entry.name === 'gitignore' ? '.gitignore' : entry.name\n      if (entry.isDirectory())\n        walk(join(from, entry.name), join(to, targetName), `${prefix}${entry.name}/`)\n      else {\n        writeFileSync(\n          join(to, targetName),\n          replacePlaceholders(readFileSync(join(from, entry.name), 'utf8'), name),\n        )\n        written.push(`${prefix}${targetName}`)\n      }\n    }\n  }\n  walk(join(templatesRoot(), template), target, '')\n  writeFileSync(join(target, 'AGENTS.md'), agentsText(template, name))\n  writeFileSync(join(target, 'CLAUDE.md'), '@AGENTS.md\\n')\n  copyDocs(target)\n  return written\n}\n\nconst isEmpty = (directory: string) => !existsSync(directory) || readdirSync(directory).length === 0\n\n/** The `acrylblends` command of the installed framework package, which creates the `acryl-app` template. */\nfunction acrylblendsBin(): string {\n  const pkgFile = createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`)\n  const pkg = JSON.parse(readFileSync(pkgFile, 'utf8')) as { bin?: string | Record<string, string> }\n  const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[PACKAGE]\n  if (!bin) throw new Error(`${PACKAGE} has no command to create an app with`)\n  return join(dirname(pkgFile), bin)\n}\n\n/** Create the app. Returns the exit code: 0 done, 1 refused or failed, 2 a usage error. Never calls `process.exit`. */\nexport async function runCreate(argv: readonly string[], io: Io = processIo()): Promise<number> {\n  try {\n    if (argv.includes('-h') || argv.includes('--help')) {\n      io.stdout.write(HELP)\n      return 0\n    }\n    if (argv.includes('-v') || argv.includes('--version')) {\n      io.stdout.write(`${VERSION}\\n`)\n      return 0\n    }\n    const options = parseCreateOptions(argv)\n    const ask = options.yes ? undefined : io.ask\n    const directory =\n      options.directory ??\n      (ask\n        ? (await ask(`Project directory (${PACKAGE}-app): `)).trim() || `${PACKAGE}-app`\n        : `${PACKAGE}-app`)\n    const target = resolve(io.cwd, directory)\n    const template: Template =\n      options.template ??\n      (ask\n        ? await (async () => {\n            const answer =\n              (\n                await ask(\n                  `Which template do you want to use? (nodejs, bun (experimental), acryl-app) [nodejs]: `,\n                )\n              ).trim() || 'nodejs'\n            if (!isTemplate(answer))\n              throw new UsageError(`unknown template \"${answer}\" (${TEMPLATES.join(', ')})`)\n            return answer\n          })()\n        : 'nodejs')\n    if (!isEmpty(target)) {\n      io.stderr.write(`error: ${target} is not empty; nothing was changed\\n`)\n      return 1\n    }\n    const name = nameFrom(target)\n    if (template === 'acryl-app') {\n      const code = await io.run(\n        process.execPath,\n        [acrylblendsBin(), 'init', target, '--template', 'agent', '--name', name, '--yes'],\n        io.cwd,\n      )\n      if (code !== 0) return 1\n    } else {\n      const files = copyTemplate(template, target, name)\n      io.stdout.write(\n        `created ${name} (${template}) in ${target}: ${files.length} files, ${CLASS} docs in docs/framework\\n`,\n      )\n    }\n    const pm: PackageManager =\n      options.pm ??\n      ((PACKAGE_MANAGERS as readonly string[]).find((m) =>\n        (io.env.npm_config_user_agent ?? '').startsWith(`${m}/`),\n      ) as PackageManager | undefined) ??\n      'npm'\n    if (options.install) {\n      if ((await io.run(pm, ['install'], target)) !== 0) {\n        io.stderr.write(`error: ${pm} install failed; run it yourself in ${directory}\\n`)\n        return 1\n      }\n    }\n    const start = {\n      nodejs: `${pm} run dev`,\n      bun: 'bun run dev',\n      'acryl-app': `${pm} run dev`,\n    }[template]\n    io.stdout.write(\n      `\\nNext:\\n  cd ${directory}\\n${options.install ? '' : `  ${pm} install\\n`}  ${start}\\n`,\n    )\n    return 0\n  } catch (error) {\n    if (error instanceof UsageError) {\n      io.stderr.write(`error: ${error.message}\\n\\n${HELP}`)\n      return 2\n    }\n    io.stderr.write(`error: ${(error as Error).message}\\n`)\n    return 1\n  }\n}\n"],"mappings":"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"}

package/docs/framework/LICENSE

@@ -0,0 +1,23 @@
+The pages in this folder are adapted in part from the Hono documentation (https://github.com/honojs/website), used under this license:
+
+MIT License
+
+Copyright (c) 2021 - present, Yusuke Wada and Hono contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/framework/README.md

@@ -0,0 +1,63 @@
+# Acryl
+
+Acryl is a small web framework built on Web Standards. You write handlers over the standard `Request` and `Response`, and the same application runs on Node.js (and, experimentally, Bun), and inside a Cordis app as a plugin that an agent can extend while it runs.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+
+app.get('/', (c) => c.text('Acryl!'))
+
+export default app
+```
+
+## Quick Start
+
+```sh
+npm create acrylblends@latest my-app
+```
+
+Other package managers work the same way: `pnpm create acrylblends@latest`, `yarn create acrylblends`, `bun create acrylblends@latest`.
+The starter asks which template you want (`nodejs`, `bun` (experimental), or `acryl-app`, a Cordis app with an agent). See [Getting started](getting-started/basic.md).
+
+## What is in the box
+
+- **Routing** with several routers behind one API: `RegExpRouter`, `TrieRouter`, `SmartRouter` (the default, which chooses between them), `LinearRouter` and `PatternRouter`.
+  See [Routers](concepts/routers.md) and [Routing](api/routing.md).
+- **Web Standards only.** Handlers receive a `Context` over `Request` and return `Response`, with no runtime-specific objects. See [Web Standards](concepts/web-standard.md).
+- **Built-in middleware** for authentication, CORS, CSRF, compression, ETag, logging, request ids, secure headers, timeouts and more.
+  See [Built-in middleware](middleware/builtin/basic-auth.md) and [Middleware](concepts/middleware.md).
+- **Helpers** for cookies, streaming and server-sent events, content negotiation, HTML templates, WebSockets and testing. See [Helpers](guides/helpers.md).
+- **Typed routes and a typed client.** Route types flow from the server to `acrylblends/client`. See [RPC](guides/rpc.md).
+- **Validation** with a validator function or any Standard Schema library. See [Validation](guides/validation.md).
+- **A Cordis plugin around it.** A plugin mounts an app with `ctx.router.route`, the mount goes away when the plugin unloads, and a coding agent can write such plugins
+  into a running app. See [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md) and [Agents](agents/index.md).
+
+## Runtimes
+
+Verified: Node.js. Bun is experimental. The other runtimes the framework could target are listed on [Other runtimes](getting-started/other-runtimes.md) as not yet verified.
+
+## Not yet available
+
+Some parts of the documented API surface are not part of the package yet, and their pages say so at the top: the JSX packages, static site generation, the CSS helper, the
+`proxy`, `dev` and `cache` pieces, the `quick` and `tiny` presets and the adapters of the runtimes other than Node.js. They are enabled as they are ported.
+
+## Where to read next
+
+| I want to | Read |
+| --- | --- |
+| Run something in five minutes | [Getting started](getting-started/basic.md) |
+| Look up a call | [API](api/index.md), [Routing](api/routing.md), [Context](api/context.md), [Request](api/request.md), [API summary](api/summary.md) |
+| Understand the design | [Concepts](concepts/motivation.md) |
+| Copy a pattern | [Guides](guides/best-practices.md), [Validation](guides/validation.md), [Testing](guides/testing.md) |
+| Use Acryl inside a Cordis app | [Acryl in a Cordis app](cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](cordis/plugin-lifecycle.md), [Mounting](cordis/mounting.md) |
+| Move from the 0.3 router calls | [Migration from 0.3](cordis/migration-from-0-3.md) |
+| Move from the 0.4 names (`App`) | [Migration from 0.4](cordis/migration-from-0-4.md) |
+
+The license of these pages and of the framework source they describe is in [LICENSE](LICENSE).
+
+## TypeScript in a Cordis app
+
+An app's `tsconfig.json` can extend `acryl-router/tsconfig.app.json` (ES2024 with the DOM types, strict). The DOM types are optional: every
+entry point's types also stand with only `"lib": ["ES2024"]` and `"types": ["node"]`, the setting a Host-only plugin uses so browser globals
+do not typecheck in server code (the router's `tests/no-dom` fixture checks this on every typecheck).

package/docs/framework/UPSTREAM.md

@@ -0,0 +1,3 @@
+# Generated copy
+
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `5743482e4199ded676a77f594bce15fd4aa0ca2f`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.

package/docs/framework/agents/index.md

@@ -0,0 +1,24 @@
+# Agents
+
+A coding agent (Claude Code, Codex, OpenCode, Copilot and others) builds on Acryl best when the documentation is in the folder it works in. A project created with
+`npm create acrylblends@latest` (and one made with `npx acrylblends init`) therefore contains:
+
+- `docs/framework/`: these pages. Start at `README.md`; `api/summary.md` is the one-page summary of the API.
+- `AGENTS.md`: where the API is, how a feature is built (an `Acryl` app mounted with `ctx.router.route`, a plugin registered in `src/app.ts` and `blend.yaml`, a state cell),
+  the things that surprise people, and what must pass before a task is done (`npm test` and `npm run check`).
+- `CLAUDE.md`: one line, `@AGENTS.md`, so tools that read `CLAUDE.md` read the same guide.
+
+## What an agent can do inside a running app
+
+The `acryl-app` template (a Cordis app) also lets an agent change the app while it runs:
+
+1. The agent writes a plugin into `extensions/<name>/index.ts`. The plugin may import `acrylblends` and the other subpaths by name.
+2. The app installs it as a child plugin, runs its `check(ctx)` with the plugin's own context, and keeps the previous version if the new one fails to start or to pass its check.
+3. A plugin's routes are an `Acryl` app mounted with `ctx.router.route`, so removing the plugin removes its routes.
+
+See [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](../cordis/plugin-lifecycle.md) and [Mounting](../cordis/mounting.md).
+
+## Checking that an agent can use the docs
+
+The repository has a manual gate: it creates a fresh app, starts a headless coding agent inside it with a one-line task (for example "add a /customers/count route with a test"),
+and checks that the app's tests and type-check pass afterwards and that the route answers.