acrylblends 0.4.0 → 0.4.1

package/dist/index.js

@@ -133,7 +133,7 @@ function copyTemplate(source, target, name) {
 	const written = [];
 	const walk = (from, to, prefix) => {
 		for (const entry of readdirSync(from, { withFileTypes: true })) {
-			if (entry.name === "node_modules" || prefix === "" && (entry.name === "template.json" || entry.name === "upstream.json")) continue;
+			if (entry.name === "node_modules" || prefix === "" && (entry.name === "template.json" || entry.name === "upstream.json" || entry.name === "AGENTS.md")) continue;
 			const sourcePath = join(from, entry.name);
 			const targetName = prefix === "" && (entry.name === "gitignore" || entry.name === "dockerignore") ? `.${entry.name}` : entry.name;
 			const targetPath = join(to, targetName);
@@ -151,7 +151,7 @@ function copyTemplate(source, target, name) {
 	walk(source, target, "");
 	return written;
 }
-/** A template's own manifest, `template.json`: the library plugins it is built from. Never copied (nor is `upstream.json`, the record of what was synced from ACRYL). */
+/** A template's own manifest, `template.json`: the library plugins it is built from. Never copied (nor is `upstream.json`, the record of what was synced from ACRYL, nor the template's `AGENTS.md`, which `writeAgentFiles` joins to the shared core). */
 const TEMPLATE_MANIFEST = "template.json";
 function readTemplatePlugins(templateDir) {
 	const file = join(templateDir, TEMPLATE_MANIFEST);
@@ -173,6 +173,40 @@ function mergeDependencies(appDir, dependencies) {
 	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
 	return added;
 }
+/** The generated app's guide for a coding agent: the shared core, then the template's own part. `CLAUDE.md` is only an import of it. */
+function writeAgentFiles(sharedDir, templateDir, target, name) {
+	const core = readFileSync(join(sharedDir, "AGENTS.core.md"), "utf8");
+	const own = existsSync(join(templateDir, "AGENTS.md")) ? readFileSync(join(templateDir, "AGENTS.md"), "utf8") : "";
+	writeFileSync(join(target, "AGENTS.md"), `${core}${own}`.replaceAll("__APP_NAME__", name));
+	writeFileSync(join(target, "CLAUDE.md"), "@AGENTS.md\n");
+	return ["AGENTS.md", "CLAUDE.md"];
+}
+/**
+* Copy the framework's docs (a generated copy of ACRYL's `docs/framework`, already checked against its digest) into `<app>/docs/framework/`,
+* so a coding agent working in the app reads the API from the folder it is in. The generated-copy notes and the digest record stay behind.
+*
+* @returns the copied files, relative to `target`
+*/
+function copyFrameworkDocs(source, target) {
+	const written = [];
+	const walk = (from, to, prefix) => {
+		for (const entry of readdirSync(from, { withFileTypes: true })) {
+			if (entry.name === "upstream.json" || entry.name === "UPSTREAM.md") continue;
+			const sourcePath = join(from, entry.name);
+			const targetPath = join(to, entry.name);
+			if (entry.isDirectory()) {
+				mkdirSync(targetPath, { recursive: true });
+				walk(sourcePath, targetPath, `${prefix}${entry.name}/`);
+				continue;
+			}
+			cpSync(sourcePath, targetPath);
+			written.push(`docs/framework/${prefix}${entry.name}`);
+		}
+	};
+	mkdirSync(join(target, "docs", "framework"), { recursive: true });
+	walk(source, join(target, "docs", "framework"), "");
+	return written;
+}
 //#endregion
 //#region src/templates.ts
 /** The templates: a blank Cordis app on the router, a todo list built only on the router and state, and the blank app with the offline agent. */
@@ -202,6 +236,24 @@ function templatesRoot() {
 function templateDir(template) {
 	return join(templatesRoot(), template);
 }
+/** The text every generated app's `AGENTS.md` starts with (`shared/`, beside `templates/`). */
+function sharedDir() {
+	return join(dirname(templatesRoot()), "shared");
+}
+/**
+* The framework's docs, as ACRYL wrote them: `docs/framework` of the repository, or the copy `prepack` puts inside the package. The module sits at
+* different depths in source and in the build, so walk up until a `docs/framework` folder holds the README.
+*/
+function frameworkDocsRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const candidate = join(dir, "docs", "framework");
+		if (existsSync(join(candidate, "README.md"))) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("acrylblends cannot find the framework docs (docs/framework)");
+		dir = parent;
+	}
+}
 //#endregion
 //#region src/init.ts
 /** A command line mistake. The CLI prints it with the help text and exits 2. */
@@ -266,6 +318,8 @@ async function init(options, io) {
 	let files;
 	try {
 		files = copyTemplate(templateDir(template), directory, name);
+		files.push(...writeAgentFiles(sharedDir(), templateDir(template), directory, name));
+		files.push(...copyFrameworkDocs(frameworkDocsRoot(), directory));
 	} catch (error) {
 		if (!(error instanceof TargetNotEmptyError)) throw error;
 		io.stderr.write(`error: ${error.message}\n`);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["parse"],"sources":["../src/library.ts","../src/project.ts","../src/templates.ts","../src/init.ts","../src/add.ts","../src/io.ts","../src/cli.ts"],"sourcesContent":["import { cpSync, existsSync, readdirSync, readFileSync } from 'node:fs'\nimport { dirname, join, sep } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n/** One entry of the plugin library: `plugins/<name>/plugin.json` in this repository. */\nexport interface LibraryPlugin {\n  readonly name: string\n  readonly description: string\n  /** Library plugins this one imports; they are copied with it. */\n  readonly requires: readonly string[]\n  /** npm packages an app needs at run time for this plugin. */\n  readonly dependencies: Readonly<Record<string, string>>\n  /** How to mount it, shown after `acrylblends add`. */\n  readonly mount?: string\n  /**\n   * Paths inside the plugin folder that are not copied into an app (for example a React hook an app without React cannot type-check, or colocated test\n   * files). A pattern is an exact path or a glob: `*` matches within one folder name, `**` across folders, `?` one character; `**` followed by a slash also matches no folder.\n   */\n  readonly omit?: readonly string[]\n}\n\n/** A glob as a regular expression: `*` within a name, `**` across folders, `**` plus a slash may match no folder, `?` one character. */\nfunction globToRegExp(glob: string): RegExp {\n  let source = ''\n  for (let i = 0; i < glob.length; i += 1) {\n    const c = glob[i] as string\n    if (c === '*' && glob[i + 1] === '*') {\n      if (glob[i + 2] === '/') {\n        source += '(?:.*/)?'\n        i += 2\n      } else {\n        source += '.*'\n        i += 1\n      }\n    } else if (c === '*') source += '[^/]*'\n    else if (c === '?') source += '[^/]'\n    else source += c.replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&')\n  }\n  return new RegExp(`^${source}$`)\n}\n\n/** Whether a path inside a plugin folder (relative, any separator) is named by one of its `omit` patterns. */\nexport function isOmitted(inside: string, patterns: readonly string[] | undefined): boolean {\n  if (!patterns || patterns.length === 0) return false\n  const path = inside.split(sep).join('/')\n  return patterns.some((pattern) =>\n    /[*?]/.test(pattern) ? globToRegExp(pattern).test(path) : pattern === path,\n  )\n}\n\n/** Files of a library plugin that stay in the repository: its manifest and its tests. */\nconst LIBRARY_ONLY = new Set(['plugin.json', 'test', 'tests'])\n\nexport class LibraryError extends Error {\n  override name = 'LibraryError'\n}\n\n/** The library folder (`plugins/` at the repository root): walk up from this module, in source or in the build. */\nexport function libraryRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url))\n  for (;;) {\n    const candidate = join(dir, 'plugins')\n    if (existsSync(join(candidate, 'instance', 'plugin.json'))) return candidate\n    const parent = dirname(dir)\n    if (parent === dir)\n      throw new LibraryError('acrylblends cannot find its plugin library (plugins/)')\n    dir = parent\n  }\n}\n\n/** Every plugin in the library, by name. */\nexport function readLibrary(root: string = libraryRoot()): Map<string, LibraryPlugin> {\n  const plugins = new Map<string, LibraryPlugin>()\n  for (const entry of readdirSync(root, { withFileTypes: true })) {\n    const manifest = join(root, entry.name, 'plugin.json')\n    if (!entry.isDirectory() || !existsSync(manifest)) continue\n    const plugin = JSON.parse(readFileSync(manifest, 'utf8')) as LibraryPlugin\n    if (plugin.name !== entry.name)\n      throw new LibraryError(`plugins/${entry.name}/plugin.json names \"${plugin.name}\"`)\n    plugins.set(plugin.name, {\n      ...plugin,\n      requires: plugin.requires ?? [],\n      dependencies: plugin.dependencies ?? {},\n    })\n  }\n  return plugins\n}\n\n/** The plugins to copy for `names`: each one after everything it requires, no duplicates. */\nexport function closure(\n  names: readonly string[],\n  library: Map<string, LibraryPlugin>,\n): LibraryPlugin[] {\n  const ordered: LibraryPlugin[] = []\n  const visiting = new Set<string>()\n  const visit = (name: string, trail: string[]) => {\n    if (ordered.some((plugin) => plugin.name === name)) return\n    const plugin = library.get(name)\n    if (!plugin)\n      throw new LibraryError(\n        `no plugin \"${name}\" in the library${trail.length ? ` (required by ${trail.at(-1)})` : ''}`,\n      )\n    if (visiting.has(name))\n      throw new LibraryError(\n        `plugins require each other in a cycle: ${[...trail, name].join(' -> ')}`,\n      )\n    visiting.add(name)\n    for (const required of plugin.requires) visit(required, [...trail, name])\n    visiting.delete(name)\n    ordered.push(plugin)\n  }\n  for (const name of names) visit(name, [])\n  return ordered\n}\n\n/** Copy one library plugin's source into `<app>/src/plugins/<name>/`. Throws when that folder already exists. */\nexport function copyPlugin(\n  plugin: LibraryPlugin,\n  appDir: string,\n  root: string = libraryRoot(),\n): string {\n  const target = join(appDir, 'src', 'plugins', plugin.name)\n  if (existsSync(target))\n    throw new LibraryError(\n      `src/plugins/${plugin.name} already exists; remove it first to copy a fresh one`,\n    )\n  const source = join(root, plugin.name)\n  cpSync(source, target, {\n    recursive: true,\n    filter: (path) => {\n      const inside = path.slice(source.length + 1)\n      return (\n        !(dirname(path) === source && LIBRARY_ONLY.has(inside)) && !isOmitted(inside, plugin.omit)\n      )\n    },\n  })\n  return target\n}\n","import {\n  cpSync,\n  existsSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  statSync,\n  writeFileSync,\n} from 'node:fs'\nimport { join } from 'node:path'\n\n/** Thrown when the target directory exists and is not empty. Nothing has been written. */\nexport class TargetNotEmptyError extends Error {\n  constructor(readonly target: string) {\n    super(\n      `refusing to write into \"${target}\": the directory is not empty. Choose an empty or new directory.`,\n    )\n    this.name = 'TargetNotEmptyError'\n  }\n}\n\n/** A project name npm accepts: lower case letters, digits and dashes, starting with a letter. */\nexport function isValidName(name: string): boolean {\n  return /^[a-z][a-z0-9-]*$/.test(name) && name.length <= 214\n}\n\n/** A valid default project name derived from a directory path. */\nexport function nameFrom(directory: string): string {\n  const base = directory.split(/[\\\\/]/).filter(Boolean).pop() ?? ''\n  const cleaned = base\n    .toLowerCase()\n    .replace(/[^a-z0-9-]+/g, '-')\n    .replace(/^[^a-z]+/, '')\n    .replace(/-+$/, '')\n  return cleaned || 'my-app'\n}\n\n/** Refuse a target that exists and is not an empty directory. A missing target is fine: it is created. */\nexport function assertTargetFree(target: string): void {\n  if (!existsSync(target)) return\n  if (!statSync(target).isDirectory() || readdirSync(target).length > 0)\n    throw new TargetNotEmptyError(target)\n}\n\n/**\n * Copy a template into `target`, replacing `__APP_NAME__` with `name`. Checks the target before writing anything.\n *\n * @returns the copied files, relative to `target`\n */\nexport function copyTemplate(source: string, target: string, name: string): string[] {\n  assertTargetFree(target)\n  mkdirSync(target, { recursive: true })\n  const written: string[] = []\n  const walk = (from: string, to: string, prefix: string) => {\n    for (const entry of readdirSync(from, { withFileTypes: true })) {\n      if (\n        entry.name === 'node_modules' ||\n        (prefix === '' && (entry.name === TEMPLATE_MANIFEST || entry.name === 'upstream.json'))\n      )\n        continue\n      const sourcePath = join(from, entry.name)\n      // npm and git treat a file named .gitignore specially, so templates keep it as `gitignore` (and `dockerignore`).\n      const targetName =\n        prefix === '' && (entry.name === 'gitignore' || entry.name === 'dockerignore')\n          ? `.${entry.name}`\n          : entry.name\n      const targetPath = join(to, targetName)\n      if (entry.isDirectory()) {\n        mkdirSync(targetPath, { recursive: true })\n        walk(sourcePath, targetPath, `${prefix}${entry.name}/`)\n        continue\n      }\n      const text = readFileSync(sourcePath, 'utf8')\n      if (text.includes('__APP_NAME__'))\n        writeFileSync(targetPath, text.replaceAll('__APP_NAME__', name))\n      else cpSync(sourcePath, targetPath)\n      written.push(`${prefix}${targetName}`)\n    }\n  }\n  walk(source, target, '')\n  return written\n}\n\n/** A template's own manifest, `template.json`: the library plugins it is built from. Never copied (nor is `upstream.json`, the record of what was synced from ACRYL). */\nexport const TEMPLATE_MANIFEST = 'template.json'\n\nexport function readTemplatePlugins(templateDir: string): string[] {\n  const file = join(templateDir, TEMPLATE_MANIFEST)\n  if (!existsSync(file)) return []\n  const { plugins } = JSON.parse(readFileSync(file, 'utf8')) as { plugins?: string[] }\n  return plugins ?? []\n}\n\n/** Add run-time dependencies to an app's package.json, keeping what is there and sorting the keys. Returns the names added. */\nexport function mergeDependencies(\n  appDir: string,\n  dependencies: Readonly<Record<string, string>>,\n): string[] {\n  const file = join(appDir, 'package.json')\n  const manifest = JSON.parse(readFileSync(file, 'utf8')) as {\n    dependencies?: Record<string, string>\n  }\n  const current = manifest.dependencies ?? {}\n  const added = Object.keys(dependencies).filter((name) => !(name in current))\n  const merged = { ...dependencies, ...current }\n  manifest.dependencies = Object.fromEntries(\n    Object.entries(merged).sort(([a], [b]) => a.localeCompare(b)),\n  )\n  writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\\n`)\n  return added\n}\n","import { existsSync } from 'node:fs'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n/** The templates: a blank Cordis app on the router, a todo list built only on the router and state, and the blank app with the offline agent. */\nexport const TEMPLATES = ['blank', 'todo', 'agent'] as const\nexport type Template = (typeof TEMPLATES)[number]\n\nexport function isTemplate(value: string): value is Template {\n  return (TEMPLATES as readonly string[]).includes(value)\n}\n\n/**\n * The `templates/` folder of this package. The module sits at different depths in source (`src/`) and in the build\n * (`dist/`), so walk up until a `templates` folder holds the `blank` template.\n */\nexport function templatesRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url))\n  for (;;) {\n    const candidate = join(dir, 'templates')\n    if (existsSync(join(candidate, 'blank'))) return candidate\n    const parent = dirname(dir)\n    if (parent === dir) throw new Error('acrylblends cannot find its templates folder')\n    dir = parent\n  }\n}\n\n/** Absolute path of a template folder. */\nexport function templateDir(template: Template): string {\n  return join(templatesRoot(), template)\n}\n","import { resolve } from 'node:path'\nimport { parseArgs } from 'node:util'\nimport type { Io } from './io'\nimport { closure, copyPlugin, readLibrary } from './library'\nimport {\n  copyTemplate,\n  isValidName,\n  mergeDependencies,\n  nameFrom,\n  readTemplatePlugins,\n  TargetNotEmptyError,\n} from './project'\nimport { isTemplate, TEMPLATES, type Template, templateDir } from './templates'\n\n/** A command line mistake. The CLI prints it with the help text and exits 2. */\nexport class UsageError extends Error {\n  override name = 'UsageError'\n}\n\n/** What `init` was asked for. Anything left undefined is asked for on a terminal, or defaulted. */\nexport interface InitOptions {\n  directory: string | undefined\n  name: string | undefined\n  template: Template | undefined\n  install: boolean | undefined\n  yes: boolean\n}\n\n/** Parse `init [dir] [--template t] [--agent|--no-agent] [--name n] [--install] [-y]`. `--agent` means `--template agent`, `--no-agent` means `--template blank`. */\nexport function parseInitOptions(argv: readonly string[]): InitOptions {\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('init takes at most one directory')\n  if (values.agent && values['no-agent'])\n    throw new UsageError('use --agent or --no-agent, not both')\n  if (values.template !== undefined && !isTemplate(values.template))\n    throw new UsageError(`unknown template \"${values.template}\" (${TEMPLATES.join(', ')})`)\n  const alias: Template | undefined = values.agent\n    ? 'agent'\n    : values['no-agent']\n      ? 'blank'\n      : undefined\n  if (values.template !== undefined && alias !== undefined && values.template !== alias)\n    throw new UsageError(\n      `--template ${values.template} contradicts --${alias === 'agent' ? 'agent' : 'no-agent'}`,\n    )\n  return {\n    directory: positionals[0],\n    name: values.name,\n    template: (values.template as Template | undefined) ?? alias,\n    install: values.install,\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      name: { type: 'string' },\n      template: { type: 'string' },\n      agent: { type: 'boolean' },\n      'no-agent': { type: 'boolean' },\n      install: { type: 'boolean' },\n      yes: { type: 'boolean', short: 'y' },\n    },\n  })\n\nconst yes = (answer: string) => ['y', 'yes'].includes(answer.trim().toLowerCase())\n\nasync function askTemplate(ask: (question: string) => Promise<string>): Promise<Template> {\n  const answer = (await ask(`Template (${TEMPLATES.join(', ')}) [blank]: `)).trim().toLowerCase()\n  if (answer === '') return 'blank'\n  if (isTemplate(answer)) return answer\n  throw new UsageError(`unknown template \"${answer}\" (${TEMPLATES.join(', ')})`)\n}\n\n/** Scaffold a Cordis app. Returns the exit code: 0 done, 1 refused or failed. Never overwrites anything. */\nexport async function init(options: InitOptions, io: Io): Promise<number> {\n  const relative = options.directory ?? '.'\n  const directory = resolve(io.cwd, relative)\n  const ask = options.yes ? undefined : io.ask\n\n  let name = options.name ?? nameFrom(directory)\n  if (options.name === undefined && ask)\n    name = (await ask(`Project name (${name}): `)).trim() || name\n  if (!isValidName(name)) {\n    throw new UsageError(\n      `\"${name}\" is not a valid project name (lower case letters, digits and dashes, starting with a letter)`,\n    )\n  }\n  const template = options.template ?? (ask ? await askTemplate(ask) : 'blank')\n  const install =\n    options.install ?? (ask ? yes(await ask('Install dependencies with npm now? (y/N): ')) : false)\n\n  let files: string[]\n  try {\n    files = copyTemplate(templateDir(template), directory, name)\n  } catch (error) {\n    if (!(error instanceof TargetNotEmptyError)) throw error\n    io.stderr.write(`error: ${error.message}\\n`)\n    return 1\n  }\n  const plugins = closure(readTemplatePlugins(templateDir(template)), readLibrary())\n  for (const plugin of plugins) {\n    copyPlugin(plugin, directory)\n    mergeDependencies(directory, plugin.dependencies)\n  }\n  io.stdout.write(\n    `created ${name} (${template}) in ${directory}: ${files.length} files, plugins ${plugins.map((plugin) => plugin.name).join(', ')}\\n`,\n  )\n\n  if (install && (await io.install(directory)) !== 0) {\n    io.stderr.write('error: npm install failed; run it yourself in the new directory\\n')\n    return 1\n  }\n  const steps = [\n    relative === '.' ? '' : `  cd ${relative}\\n`,\n    install ? '' : '  npm install\\n',\n    '  npm run dev\\n  npm test\\n',\n  ]\n  io.stdout.write(`\\nNext:\\n${steps.join('')}`)\n  return 0\n}\n","import { cpSync, existsSync, readFileSync, statSync } from 'node:fs'\nimport { basename, join, resolve } from 'node:path'\nimport { parseArgs } from 'node:util'\nimport { UsageError } from './init'\nimport type { Io } from './io'\nimport { closure, copyPlugin, type LibraryPlugin, readLibrary } from './library'\nimport { mergeDependencies } from './project'\n\nexport interface AddOptions {\n  readonly names: readonly string[]\n  readonly directory: string | undefined\n}\n\n/** Parse `add <plugin...> [--dir <app>]`. */\nexport function parseAddOptions(argv: readonly string[]): AddOptions {\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  if (parsed.positionals.length === 0)\n    throw new UsageError('add needs at least one plugin name (see \"acrylblends plugins\")')\n  return { names: parsed.positionals, directory: parsed.values.dir }\n}\n\nconst parse = (argv: readonly string[]) =>\n  parseArgs({\n    args: [...argv],\n    allowPositionals: true,\n    strict: true,\n    options: { dir: { type: 'string' } },\n  })\n\nconst present = (appDir: string, name: string) => existsSync(join(appDir, 'src', 'plugins', name))\n\n/**\n * Copy library plugins into an existing app, with the plugins they require, and add their npm packages to its package.json.\n * Refuses a plugin the app already has. Returns the exit code.\n */\nexport async function add(options: AddOptions, io: Io): Promise<number> {\n  const appDir = resolve(io.cwd, options.directory ?? '.')\n  if (!existsSync(join(appDir, 'package.json')) || !existsSync(join(appDir, 'src'))) {\n    io.stderr.write(\n      `error: ${appDir} is not an app (no package.json and src/); run \"acrylblends init\" first\\n`,\n    )\n    return 1\n  }\n  // A path is an external plugin folder; anything else is a library plugin name.\n  const external = options.names.filter((name) => /[\\\\/]/.test(name) || name.startsWith('.'))\n  for (const folder of external) {\n    const code = addExternal(resolve(io.cwd, folder), appDir, io)\n    if (code !== 0) return code\n  }\n  const names = options.names.filter((name) => !external.includes(name))\n  if (names.length === 0) return 0\n  const already = names.filter((name) => present(appDir, name))\n  if (already.length > 0) {\n    io.stderr.write(\n      `error: the app already has ${already.map((name) => `src/plugins/${name}`).join(', ')}\\n`,\n    )\n    return 1\n  }\n  const toCopy: LibraryPlugin[] = closure(names, readLibrary()).filter(\n    (plugin) => !present(appDir, plugin.name),\n  )\n  const addedDependencies: string[] = []\n  for (const plugin of toCopy) {\n    copyPlugin(plugin, appDir)\n    addedDependencies.push(...mergeDependencies(appDir, plugin.dependencies))\n  }\n  io.stdout.write(`added ${toCopy.map((plugin) => plugin.name).join(', ')} to ${appDir}\\n`)\n  if (addedDependencies.length > 0)\n    io.stdout.write(`new dependencies: ${addedDependencies.join(', ')} (run npm install)\\n`)\n  for (const plugin of toCopy.filter((plugin) => names.includes(plugin.name))) {\n    io.stdout.write(\n      `\\n${plugin.name}: ${plugin.mount ?? `import it from './plugins/${plugin.name}/index.ts' and mount it in src/app.ts`}\\n`,\n    )\n  }\n  return 0\n}\n\nconst PLUGIN_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/\n\n/**\n * Bring an external plugin folder (a package made with the builder's package_plugin, or any folder with an index.ts that exports a\n * Cordis plugin) into the app's `extensions/`, where the extensions plugin installs it like any other: checked, staged, started,\n * verified. Its runtime dependencies are not installed here; they are reported so the user adds them deliberately.\n */\nfunction addExternal(folder: string, appDir: string, io: Io): number {\n  if (!existsSync(folder) || !statSync(folder).isDirectory()) {\n    io.stderr.write(`error: ${folder} is not a folder\\n`)\n    return 1\n  }\n  if (!['index.ts', 'index.js', 'index.mjs'].some((entry) => existsSync(join(folder, entry)))) {\n    io.stderr.write(`error: ${folder} has no index.ts that exports a Cordis plugin\\n`)\n    return 1\n  }\n  const manifestFile = join(folder, 'package.json')\n  const manifest = existsSync(manifestFile)\n    ? (JSON.parse(readFileSync(manifestFile, 'utf8')) as {\n        name?: string\n        dependencies?: Record<string, string>\n      })\n    : {}\n  const name = (manifest.name ?? basename(folder)).replace(/^@[^/]+\\//, '')\n  if (!PLUGIN_NAME.test(name)) {\n    io.stderr.write(\n      `error: \"${name}\" is not a plugin name (lowercase letters, digits and dashes)\\n`,\n    )\n    return 1\n  }\n  const target = join(appDir, 'extensions', name)\n  if (existsSync(target)) {\n    io.stderr.write(`error: the app already has extensions/${name}\\n`)\n    return 1\n  }\n  cpSync(folder, target, {\n    recursive: true,\n    filter: (path) => !/[\\\\/](node_modules|\\.git)([\\\\/]|$)/.test(path.slice(folder.length)),\n  })\n  io.stdout.write(\n    `added external plugin ${name} to ${join(appDir, 'extensions')}; it installs at the next start\\n`,\n  )\n  const dependencies = Object.keys(manifest.dependencies ?? {})\n  if (dependencies.length > 0)\n    io.stdout.write(\n      `it uses ${dependencies.join(', ')}: add them to the app with npm install first\\n`,\n    )\n  return 0\n}\n\n/** `acrylblends plugins`: the library, one line per plugin. */\nexport function listPlugins(io: Io): number {\n  for (const plugin of readLibrary().values()) {\n    const requires = plugin.requires.length > 0 ? ` (requires ${plugin.requires.join(', ')})` : ''\n    io.stdout.write(`${plugin.name.padEnd(12)} ${plugin.description}${requires}\\n`)\n  }\n  return 0\n}\n","import { spawn } from 'node:child_process'\nimport { createInterface } from 'node:readline/promises'\n\n/** Everything the CLI touches outside the filesystem. Tests pass their own. */\nexport interface Io {\n  stdout: { write(text: string): unknown }\n  stderr: { write(text: string): unknown }\n  cwd: string\n  /** Ask one question; `undefined` when there is no terminal to ask on. */\n  ask: ((question: string) => Promise<string>) | undefined\n  /** Install dependencies in a directory; resolves to the exit code. */\n  install(directory: string): Promise<number>\n}\n\n/** The real terminal and `npm install`. */\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    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    install: (directory) =>\n      new Promise((done) => {\n        const child = spawn('npm', ['install'], {\n          cwd: directory,\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","import { createRequire } from 'node:module'\nimport { add, listPlugins, parseAddOptions } from './add'\nimport { init, parseInitOptions, UsageError } from './init'\nimport { type Io, processIo } from './io'\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 = `acrylblends ${VERSION} - scaffold Cordis apps\n\nUsage:\n  acrylblends init [dir] [options]       Create a Cordis app in an empty or new directory\n  acrylblends add <plugin...> [--dir d]  Copy library plugins (and what they require) into an app;\n                                      a folder path brings an external plugin into its extensions/\n  acrylblends plugins                    List the plugin library\n\nOptions for init:\n  --template <name>      blank or agent (asked when not given); --agent means --template agent,\n                         --no-agent means --template blank\n  --name <name>          the project name (default: the directory name)\n  --install              run npm install after copying\n  -y, --yes              ask nothing; use defaults (the blank template, no install)\n\n  -h, --help             show this help\n  -v, --version          show the version\n`\n\n/**\n * Run the CLI and return the exit code: 0 done, 1 failed or refused, 2 a usage error. Never calls `process.exit`.\n */\nexport async function runCli(argv: readonly string[], io: Io = processIo()): Promise<number> {\n  const [command, ...args] = argv\n  try {\n    if (command === undefined || command === 'help' || command === '-h' || command === '--help') {\n      io.stdout.write(HELP)\n      return command === undefined ? 2 : 0\n    }\n    if (command === 'version' || command === '-v' || command === '--version') {\n      io.stdout.write(`${VERSION}\\n`)\n      return 0\n    }\n    if (command === 'init') return await init(parseInitOptions(args), io)\n    if (command === 'add') return await add(parseAddOptions(args), io)\n    if (command === 'plugins') return listPlugins(io)\n    throw new UsageError(`unknown command \"${command}\"`)\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 instanceof Error ? error.message : String(error)}\\n`)\n    return 1\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["parse"],"sources":["../src/library.ts","../src/project.ts","../src/templates.ts","../src/init.ts","../src/add.ts","../src/io.ts","../src/cli.ts"],"sourcesContent":["import { cpSync, existsSync, readdirSync, readFileSync } from 'node:fs'\nimport { dirname, join, sep } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n/** One entry of the plugin library: `plugins/<name>/plugin.json` in this repository. */\nexport interface LibraryPlugin {\n  readonly name: string\n  readonly description: string\n  /** Library plugins this one imports; they are copied with it. */\n  readonly requires: readonly string[]\n  /** npm packages an app needs at run time for this plugin. */\n  readonly dependencies: Readonly<Record<string, string>>\n  /** How to mount it, shown after `acrylblends add`. */\n  readonly mount?: string\n  /**\n   * Paths inside the plugin folder that are not copied into an app (for example a React hook an app without React cannot type-check, or colocated test\n   * files). A pattern is an exact path or a glob: `*` matches within one folder name, `**` across folders, `?` one character; `**` followed by a slash also matches no folder.\n   */\n  readonly omit?: readonly string[]\n}\n\n/** A glob as a regular expression: `*` within a name, `**` across folders, `**` plus a slash may match no folder, `?` one character. */\nfunction globToRegExp(glob: string): RegExp {\n  let source = ''\n  for (let i = 0; i < glob.length; i += 1) {\n    const c = glob[i] as string\n    if (c === '*' && glob[i + 1] === '*') {\n      if (glob[i + 2] === '/') {\n        source += '(?:.*/)?'\n        i += 2\n      } else {\n        source += '.*'\n        i += 1\n      }\n    } else if (c === '*') source += '[^/]*'\n    else if (c === '?') source += '[^/]'\n    else source += c.replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&')\n  }\n  return new RegExp(`^${source}$`)\n}\n\n/** Whether a path inside a plugin folder (relative, any separator) is named by one of its `omit` patterns. */\nexport function isOmitted(inside: string, patterns: readonly string[] | undefined): boolean {\n  if (!patterns || patterns.length === 0) return false\n  const path = inside.split(sep).join('/')\n  return patterns.some((pattern) =>\n    /[*?]/.test(pattern) ? globToRegExp(pattern).test(path) : pattern === path,\n  )\n}\n\n/** Files of a library plugin that stay in the repository: its manifest and its tests. */\nconst LIBRARY_ONLY = new Set(['plugin.json', 'test', 'tests'])\n\nexport class LibraryError extends Error {\n  override name = 'LibraryError'\n}\n\n/** The library folder (`plugins/` at the repository root): walk up from this module, in source or in the build. */\nexport function libraryRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url))\n  for (;;) {\n    const candidate = join(dir, 'plugins')\n    if (existsSync(join(candidate, 'instance', 'plugin.json'))) return candidate\n    const parent = dirname(dir)\n    if (parent === dir)\n      throw new LibraryError('acrylblends cannot find its plugin library (plugins/)')\n    dir = parent\n  }\n}\n\n/** Every plugin in the library, by name. */\nexport function readLibrary(root: string = libraryRoot()): Map<string, LibraryPlugin> {\n  const plugins = new Map<string, LibraryPlugin>()\n  for (const entry of readdirSync(root, { withFileTypes: true })) {\n    const manifest = join(root, entry.name, 'plugin.json')\n    if (!entry.isDirectory() || !existsSync(manifest)) continue\n    const plugin = JSON.parse(readFileSync(manifest, 'utf8')) as LibraryPlugin\n    if (plugin.name !== entry.name)\n      throw new LibraryError(`plugins/${entry.name}/plugin.json names \"${plugin.name}\"`)\n    plugins.set(plugin.name, {\n      ...plugin,\n      requires: plugin.requires ?? [],\n      dependencies: plugin.dependencies ?? {},\n    })\n  }\n  return plugins\n}\n\n/** The plugins to copy for `names`: each one after everything it requires, no duplicates. */\nexport function closure(\n  names: readonly string[],\n  library: Map<string, LibraryPlugin>,\n): LibraryPlugin[] {\n  const ordered: LibraryPlugin[] = []\n  const visiting = new Set<string>()\n  const visit = (name: string, trail: string[]) => {\n    if (ordered.some((plugin) => plugin.name === name)) return\n    const plugin = library.get(name)\n    if (!plugin)\n      throw new LibraryError(\n        `no plugin \"${name}\" in the library${trail.length ? ` (required by ${trail.at(-1)})` : ''}`,\n      )\n    if (visiting.has(name))\n      throw new LibraryError(\n        `plugins require each other in a cycle: ${[...trail, name].join(' -> ')}`,\n      )\n    visiting.add(name)\n    for (const required of plugin.requires) visit(required, [...trail, name])\n    visiting.delete(name)\n    ordered.push(plugin)\n  }\n  for (const name of names) visit(name, [])\n  return ordered\n}\n\n/** Copy one library plugin's source into `<app>/src/plugins/<name>/`. Throws when that folder already exists. */\nexport function copyPlugin(\n  plugin: LibraryPlugin,\n  appDir: string,\n  root: string = libraryRoot(),\n): string {\n  const target = join(appDir, 'src', 'plugins', plugin.name)\n  if (existsSync(target))\n    throw new LibraryError(\n      `src/plugins/${plugin.name} already exists; remove it first to copy a fresh one`,\n    )\n  const source = join(root, plugin.name)\n  cpSync(source, target, {\n    recursive: true,\n    filter: (path) => {\n      const inside = path.slice(source.length + 1)\n      return (\n        !(dirname(path) === source && LIBRARY_ONLY.has(inside)) && !isOmitted(inside, plugin.omit)\n      )\n    },\n  })\n  return target\n}\n","import {\n  cpSync,\n  existsSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  statSync,\n  writeFileSync,\n} from 'node:fs'\nimport { join } from 'node:path'\n\n/** Thrown when the target directory exists and is not empty. Nothing has been written. */\nexport class TargetNotEmptyError extends Error {\n  constructor(readonly target: string) {\n    super(\n      `refusing to write into \"${target}\": the directory is not empty. Choose an empty or new directory.`,\n    )\n    this.name = 'TargetNotEmptyError'\n  }\n}\n\n/** A project name npm accepts: lower case letters, digits and dashes, starting with a letter. */\nexport function isValidName(name: string): boolean {\n  return /^[a-z][a-z0-9-]*$/.test(name) && name.length <= 214\n}\n\n/** A valid default project name derived from a directory path. */\nexport function nameFrom(directory: string): string {\n  const base = directory.split(/[\\\\/]/).filter(Boolean).pop() ?? ''\n  const cleaned = base\n    .toLowerCase()\n    .replace(/[^a-z0-9-]+/g, '-')\n    .replace(/^[^a-z]+/, '')\n    .replace(/-+$/, '')\n  return cleaned || 'my-app'\n}\n\n/** Refuse a target that exists and is not an empty directory. A missing target is fine: it is created. */\nexport function assertTargetFree(target: string): void {\n  if (!existsSync(target)) return\n  if (!statSync(target).isDirectory() || readdirSync(target).length > 0)\n    throw new TargetNotEmptyError(target)\n}\n\n/**\n * Copy a template into `target`, replacing `__APP_NAME__` with `name`. Checks the target before writing anything.\n *\n * @returns the copied files, relative to `target`\n */\nexport function copyTemplate(source: string, target: string, name: string): string[] {\n  assertTargetFree(target)\n  mkdirSync(target, { recursive: true })\n  const written: string[] = []\n  const walk = (from: string, to: string, prefix: string) => {\n    for (const entry of readdirSync(from, { withFileTypes: true })) {\n      if (\n        entry.name === 'node_modules' ||\n        (prefix === '' &&\n          (entry.name === TEMPLATE_MANIFEST ||\n            entry.name === 'upstream.json' ||\n            entry.name === 'AGENTS.md'))\n      )\n        continue\n      const sourcePath = join(from, entry.name)\n      // npm and git treat a file named .gitignore specially, so templates keep it as `gitignore` (and `dockerignore`).\n      const targetName =\n        prefix === '' && (entry.name === 'gitignore' || entry.name === 'dockerignore')\n          ? `.${entry.name}`\n          : entry.name\n      const targetPath = join(to, targetName)\n      if (entry.isDirectory()) {\n        mkdirSync(targetPath, { recursive: true })\n        walk(sourcePath, targetPath, `${prefix}${entry.name}/`)\n        continue\n      }\n      const text = readFileSync(sourcePath, 'utf8')\n      if (text.includes('__APP_NAME__'))\n        writeFileSync(targetPath, text.replaceAll('__APP_NAME__', name))\n      else cpSync(sourcePath, targetPath)\n      written.push(`${prefix}${targetName}`)\n    }\n  }\n  walk(source, target, '')\n  return written\n}\n\n/** A template's own manifest, `template.json`: the library plugins it is built from. Never copied (nor is `upstream.json`, the record of what was synced from ACRYL, nor the template's `AGENTS.md`, which `writeAgentFiles` joins to the shared core). */\nexport const TEMPLATE_MANIFEST = 'template.json'\n\nexport function readTemplatePlugins(templateDir: string): string[] {\n  const file = join(templateDir, TEMPLATE_MANIFEST)\n  if (!existsSync(file)) return []\n  const { plugins } = JSON.parse(readFileSync(file, 'utf8')) as { plugins?: string[] }\n  return plugins ?? []\n}\n\n/** Add run-time dependencies to an app's package.json, keeping what is there and sorting the keys. Returns the names added. */\nexport function mergeDependencies(\n  appDir: string,\n  dependencies: Readonly<Record<string, string>>,\n): string[] {\n  const file = join(appDir, 'package.json')\n  const manifest = JSON.parse(readFileSync(file, 'utf8')) as {\n    dependencies?: Record<string, string>\n  }\n  const current = manifest.dependencies ?? {}\n  const added = Object.keys(dependencies).filter((name) => !(name in current))\n  const merged = { ...dependencies, ...current }\n  manifest.dependencies = Object.fromEntries(\n    Object.entries(merged).sort(([a], [b]) => a.localeCompare(b)),\n  )\n  writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\\n`)\n  return added\n}\n\n/** The generated app's guide for a coding agent: the shared core, then the template's own part. `CLAUDE.md` is only an import of it. */\nexport function writeAgentFiles(\n  sharedDir: string,\n  templateDir: string,\n  target: string,\n  name: string,\n): string[] {\n  const core = readFileSync(join(sharedDir, 'AGENTS.core.md'), 'utf8')\n  const own = existsSync(join(templateDir, 'AGENTS.md'))\n    ? readFileSync(join(templateDir, 'AGENTS.md'), 'utf8')\n    : ''\n  writeFileSync(join(target, 'AGENTS.md'), `${core}${own}`.replaceAll('__APP_NAME__', name))\n  writeFileSync(join(target, 'CLAUDE.md'), '@AGENTS.md\\n')\n  return ['AGENTS.md', 'CLAUDE.md']\n}\n\n/**\n * Copy the framework's docs (a generated copy of ACRYL's `docs/framework`, already checked against its digest) into `<app>/docs/framework/`,\n * so a coding agent working in the app reads the API from the folder it is in. The generated-copy notes and the digest record stay behind.\n *\n * @returns the copied files, relative to `target`\n */\nexport function copyFrameworkDocs(source: string, target: string): string[] {\n  const written: string[] = []\n  const walk = (from: string, to: string, prefix: string) => {\n    for (const entry of readdirSync(from, { withFileTypes: true })) {\n      if (entry.name === 'upstream.json' || entry.name === 'UPSTREAM.md') continue\n      const sourcePath = join(from, entry.name)\n      const targetPath = join(to, entry.name)\n      if (entry.isDirectory()) {\n        mkdirSync(targetPath, { recursive: true })\n        walk(sourcePath, targetPath, `${prefix}${entry.name}/`)\n        continue\n      }\n      cpSync(sourcePath, targetPath)\n      written.push(`docs/framework/${prefix}${entry.name}`)\n    }\n  }\n  mkdirSync(join(target, 'docs', 'framework'), { recursive: true })\n  walk(source, join(target, 'docs', 'framework'), '')\n  return written\n}\n","import { existsSync } from 'node:fs'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\n/** The templates: a blank Cordis app on the router, a todo list built only on the router and state, and the blank app with the offline agent. */\nexport const TEMPLATES = ['blank', 'todo', 'agent'] as const\nexport type Template = (typeof TEMPLATES)[number]\n\nexport function isTemplate(value: string): value is Template {\n  return (TEMPLATES as readonly string[]).includes(value)\n}\n\n/**\n * The `templates/` folder of this package. The module sits at different depths in source (`src/`) and in the build\n * (`dist/`), so walk up until a `templates` folder holds the `blank` template.\n */\nexport function templatesRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url))\n  for (;;) {\n    const candidate = join(dir, 'templates')\n    if (existsSync(join(candidate, 'blank'))) return candidate\n    const parent = dirname(dir)\n    if (parent === dir) throw new Error('acrylblends cannot find its templates folder')\n    dir = parent\n  }\n}\n\n/** Absolute path of a template folder. */\nexport function templateDir(template: Template): string {\n  return join(templatesRoot(), template)\n}\n\n/** The text every generated app's `AGENTS.md` starts with (`shared/`, beside `templates/`). */\nexport function sharedDir(): string {\n  return join(dirname(templatesRoot()), 'shared')\n}\n\n/**\n * The framework's docs, as ACRYL wrote them: `docs/framework` of the repository, or the copy `prepack` puts inside the package. The module sits at\n * different depths in source and in the build, so walk up until a `docs/framework` folder holds the README.\n */\nexport function frameworkDocsRoot(): string {\n  let dir = dirname(fileURLToPath(import.meta.url))\n  for (;;) {\n    const candidate = join(dir, 'docs', 'framework')\n    if (existsSync(join(candidate, 'README.md'))) return candidate\n    const parent = dirname(dir)\n    if (parent === dir)\n      throw new Error('acrylblends cannot find the framework docs (docs/framework)')\n    dir = parent\n  }\n}\n","import { resolve } from 'node:path'\nimport { parseArgs } from 'node:util'\nimport type { Io } from './io'\nimport { closure, copyPlugin, readLibrary } from './library'\nimport {\n  copyFrameworkDocs,\n  copyTemplate,\n  isValidName,\n  mergeDependencies,\n  nameFrom,\n  readTemplatePlugins,\n  TargetNotEmptyError,\n  writeAgentFiles,\n} from './project'\nimport {\n  frameworkDocsRoot,\n  isTemplate,\n  sharedDir,\n  TEMPLATES,\n  type Template,\n  templateDir,\n} from './templates'\n\n/** A command line mistake. The CLI prints it with the help text and exits 2. */\nexport class UsageError extends Error {\n  override name = 'UsageError'\n}\n\n/** What `init` was asked for. Anything left undefined is asked for on a terminal, or defaulted. */\nexport interface InitOptions {\n  directory: string | undefined\n  name: string | undefined\n  template: Template | undefined\n  install: boolean | undefined\n  yes: boolean\n}\n\n/** Parse `init [dir] [--template t] [--agent|--no-agent] [--name n] [--install] [-y]`. `--agent` means `--template agent`, `--no-agent` means `--template blank`. */\nexport function parseInitOptions(argv: readonly string[]): InitOptions {\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('init takes at most one directory')\n  if (values.agent && values['no-agent'])\n    throw new UsageError('use --agent or --no-agent, not both')\n  if (values.template !== undefined && !isTemplate(values.template))\n    throw new UsageError(`unknown template \"${values.template}\" (${TEMPLATES.join(', ')})`)\n  const alias: Template | undefined = values.agent\n    ? 'agent'\n    : values['no-agent']\n      ? 'blank'\n      : undefined\n  if (values.template !== undefined && alias !== undefined && values.template !== alias)\n    throw new UsageError(\n      `--template ${values.template} contradicts --${alias === 'agent' ? 'agent' : 'no-agent'}`,\n    )\n  return {\n    directory: positionals[0],\n    name: values.name,\n    template: (values.template as Template | undefined) ?? alias,\n    install: values.install,\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      name: { type: 'string' },\n      template: { type: 'string' },\n      agent: { type: 'boolean' },\n      'no-agent': { type: 'boolean' },\n      install: { type: 'boolean' },\n      yes: { type: 'boolean', short: 'y' },\n    },\n  })\n\nconst yes = (answer: string) => ['y', 'yes'].includes(answer.trim().toLowerCase())\n\nasync function askTemplate(ask: (question: string) => Promise<string>): Promise<Template> {\n  const answer = (await ask(`Template (${TEMPLATES.join(', ')}) [blank]: `)).trim().toLowerCase()\n  if (answer === '') return 'blank'\n  if (isTemplate(answer)) return answer\n  throw new UsageError(`unknown template \"${answer}\" (${TEMPLATES.join(', ')})`)\n}\n\n/** Scaffold a Cordis app. Returns the exit code: 0 done, 1 refused or failed. Never overwrites anything. */\nexport async function init(options: InitOptions, io: Io): Promise<number> {\n  const relative = options.directory ?? '.'\n  const directory = resolve(io.cwd, relative)\n  const ask = options.yes ? undefined : io.ask\n\n  let name = options.name ?? nameFrom(directory)\n  if (options.name === undefined && ask)\n    name = (await ask(`Project name (${name}): `)).trim() || name\n  if (!isValidName(name)) {\n    throw new UsageError(\n      `\"${name}\" is not a valid project name (lower case letters, digits and dashes, starting with a letter)`,\n    )\n  }\n  const template = options.template ?? (ask ? await askTemplate(ask) : 'blank')\n  const install =\n    options.install ?? (ask ? yes(await ask('Install dependencies with npm now? (y/N): ')) : false)\n\n  let files: string[]\n  try {\n    files = copyTemplate(templateDir(template), directory, name)\n    files.push(...writeAgentFiles(sharedDir(), templateDir(template), directory, name))\n    files.push(...copyFrameworkDocs(frameworkDocsRoot(), directory))\n  } catch (error) {\n    if (!(error instanceof TargetNotEmptyError)) throw error\n    io.stderr.write(`error: ${error.message}\\n`)\n    return 1\n  }\n  const plugins = closure(readTemplatePlugins(templateDir(template)), readLibrary())\n  for (const plugin of plugins) {\n    copyPlugin(plugin, directory)\n    mergeDependencies(directory, plugin.dependencies)\n  }\n  io.stdout.write(\n    `created ${name} (${template}) in ${directory}: ${files.length} files, plugins ${plugins.map((plugin) => plugin.name).join(', ')}\\n`,\n  )\n\n  if (install && (await io.install(directory)) !== 0) {\n    io.stderr.write('error: npm install failed; run it yourself in the new directory\\n')\n    return 1\n  }\n  const steps = [\n    relative === '.' ? '' : `  cd ${relative}\\n`,\n    install ? '' : '  npm install\\n',\n    '  npm run dev\\n  npm test\\n',\n  ]\n  io.stdout.write(`\\nNext:\\n${steps.join('')}`)\n  return 0\n}\n","import { cpSync, existsSync, readFileSync, statSync } from 'node:fs'\nimport { basename, join, resolve } from 'node:path'\nimport { parseArgs } from 'node:util'\nimport { UsageError } from './init'\nimport type { Io } from './io'\nimport { closure, copyPlugin, type LibraryPlugin, readLibrary } from './library'\nimport { mergeDependencies } from './project'\n\nexport interface AddOptions {\n  readonly names: readonly string[]\n  readonly directory: string | undefined\n}\n\n/** Parse `add <plugin...> [--dir <app>]`. */\nexport function parseAddOptions(argv: readonly string[]): AddOptions {\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  if (parsed.positionals.length === 0)\n    throw new UsageError('add needs at least one plugin name (see \"acrylblends plugins\")')\n  return { names: parsed.positionals, directory: parsed.values.dir }\n}\n\nconst parse = (argv: readonly string[]) =>\n  parseArgs({\n    args: [...argv],\n    allowPositionals: true,\n    strict: true,\n    options: { dir: { type: 'string' } },\n  })\n\nconst present = (appDir: string, name: string) => existsSync(join(appDir, 'src', 'plugins', name))\n\n/**\n * Copy library plugins into an existing app, with the plugins they require, and add their npm packages to its package.json.\n * Refuses a plugin the app already has. Returns the exit code.\n */\nexport async function add(options: AddOptions, io: Io): Promise<number> {\n  const appDir = resolve(io.cwd, options.directory ?? '.')\n  if (!existsSync(join(appDir, 'package.json')) || !existsSync(join(appDir, 'src'))) {\n    io.stderr.write(\n      `error: ${appDir} is not an app (no package.json and src/); run \"acrylblends init\" first\\n`,\n    )\n    return 1\n  }\n  // A path is an external plugin folder; anything else is a library plugin name.\n  const external = options.names.filter((name) => /[\\\\/]/.test(name) || name.startsWith('.'))\n  for (const folder of external) {\n    const code = addExternal(resolve(io.cwd, folder), appDir, io)\n    if (code !== 0) return code\n  }\n  const names = options.names.filter((name) => !external.includes(name))\n  if (names.length === 0) return 0\n  const already = names.filter((name) => present(appDir, name))\n  if (already.length > 0) {\n    io.stderr.write(\n      `error: the app already has ${already.map((name) => `src/plugins/${name}`).join(', ')}\\n`,\n    )\n    return 1\n  }\n  const toCopy: LibraryPlugin[] = closure(names, readLibrary()).filter(\n    (plugin) => !present(appDir, plugin.name),\n  )\n  const addedDependencies: string[] = []\n  for (const plugin of toCopy) {\n    copyPlugin(plugin, appDir)\n    addedDependencies.push(...mergeDependencies(appDir, plugin.dependencies))\n  }\n  io.stdout.write(`added ${toCopy.map((plugin) => plugin.name).join(', ')} to ${appDir}\\n`)\n  if (addedDependencies.length > 0)\n    io.stdout.write(`new dependencies: ${addedDependencies.join(', ')} (run npm install)\\n`)\n  for (const plugin of toCopy.filter((plugin) => names.includes(plugin.name))) {\n    io.stdout.write(\n      `\\n${plugin.name}: ${plugin.mount ?? `import it from './plugins/${plugin.name}/index.ts' and mount it in src/app.ts`}\\n`,\n    )\n  }\n  return 0\n}\n\nconst PLUGIN_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/\n\n/**\n * Bring an external plugin folder (a package made with the builder's package_plugin, or any folder with an index.ts that exports a\n * Cordis plugin) into the app's `extensions/`, where the extensions plugin installs it like any other: checked, staged, started,\n * verified. Its runtime dependencies are not installed here; they are reported so the user adds them deliberately.\n */\nfunction addExternal(folder: string, appDir: string, io: Io): number {\n  if (!existsSync(folder) || !statSync(folder).isDirectory()) {\n    io.stderr.write(`error: ${folder} is not a folder\\n`)\n    return 1\n  }\n  if (!['index.ts', 'index.js', 'index.mjs'].some((entry) => existsSync(join(folder, entry)))) {\n    io.stderr.write(`error: ${folder} has no index.ts that exports a Cordis plugin\\n`)\n    return 1\n  }\n  const manifestFile = join(folder, 'package.json')\n  const manifest = existsSync(manifestFile)\n    ? (JSON.parse(readFileSync(manifestFile, 'utf8')) as {\n        name?: string\n        dependencies?: Record<string, string>\n      })\n    : {}\n  const name = (manifest.name ?? basename(folder)).replace(/^@[^/]+\\//, '')\n  if (!PLUGIN_NAME.test(name)) {\n    io.stderr.write(\n      `error: \"${name}\" is not a plugin name (lowercase letters, digits and dashes)\\n`,\n    )\n    return 1\n  }\n  const target = join(appDir, 'extensions', name)\n  if (existsSync(target)) {\n    io.stderr.write(`error: the app already has extensions/${name}\\n`)\n    return 1\n  }\n  cpSync(folder, target, {\n    recursive: true,\n    filter: (path) => !/[\\\\/](node_modules|\\.git)([\\\\/]|$)/.test(path.slice(folder.length)),\n  })\n  io.stdout.write(\n    `added external plugin ${name} to ${join(appDir, 'extensions')}; it installs at the next start\\n`,\n  )\n  const dependencies = Object.keys(manifest.dependencies ?? {})\n  if (dependencies.length > 0)\n    io.stdout.write(\n      `it uses ${dependencies.join(', ')}: add them to the app with npm install first\\n`,\n    )\n  return 0\n}\n\n/** `acrylblends plugins`: the library, one line per plugin. */\nexport function listPlugins(io: Io): number {\n  for (const plugin of readLibrary().values()) {\n    const requires = plugin.requires.length > 0 ? ` (requires ${plugin.requires.join(', ')})` : ''\n    io.stdout.write(`${plugin.name.padEnd(12)} ${plugin.description}${requires}\\n`)\n  }\n  return 0\n}\n","import { spawn } from 'node:child_process'\nimport { createInterface } from 'node:readline/promises'\n\n/** Everything the CLI touches outside the filesystem. Tests pass their own. */\nexport interface Io {\n  stdout: { write(text: string): unknown }\n  stderr: { write(text: string): unknown }\n  cwd: string\n  /** Ask one question; `undefined` when there is no terminal to ask on. */\n  ask: ((question: string) => Promise<string>) | undefined\n  /** Install dependencies in a directory; resolves to the exit code. */\n  install(directory: string): Promise<number>\n}\n\n/** The real terminal and `npm install`. */\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    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    install: (directory) =>\n      new Promise((done) => {\n        const child = spawn('npm', ['install'], {\n          cwd: directory,\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","import { createRequire } from 'node:module'\nimport { add, listPlugins, parseAddOptions } from './add'\nimport { init, parseInitOptions, UsageError } from './init'\nimport { type Io, processIo } from './io'\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 = `acrylblends ${VERSION} - scaffold Cordis apps\n\nUsage:\n  acrylblends init [dir] [options]       Create a Cordis app in an empty or new directory\n  acrylblends add <plugin...> [--dir d]  Copy library plugins (and what they require) into an app;\n                                      a folder path brings an external plugin into its extensions/\n  acrylblends plugins                    List the plugin library\n\nOptions for init:\n  --template <name>      blank or agent (asked when not given); --agent means --template agent,\n                         --no-agent means --template blank\n  --name <name>          the project name (default: the directory name)\n  --install              run npm install after copying\n  -y, --yes              ask nothing; use defaults (the blank template, no install)\n\n  -h, --help             show this help\n  -v, --version          show the version\n`\n\n/**\n * Run the CLI and return the exit code: 0 done, 1 failed or refused, 2 a usage error. Never calls `process.exit`.\n */\nexport async function runCli(argv: readonly string[], io: Io = processIo()): Promise<number> {\n  const [command, ...args] = argv\n  try {\n    if (command === undefined || command === 'help' || command === '-h' || command === '--help') {\n      io.stdout.write(HELP)\n      return command === undefined ? 2 : 0\n    }\n    if (command === 'version' || command === '-v' || command === '--version') {\n      io.stdout.write(`${VERSION}\\n`)\n      return 0\n    }\n    if (command === 'init') return await init(parseInitOptions(args), io)\n    if (command === 'add') return await add(parseAddOptions(args), io)\n    if (command === 'plugins') return listPlugins(io)\n    throw new UsageError(`unknown command \"${command}\"`)\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 instanceof Error ? error.message : String(error)}\\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 Framework
+
+Status: 0.4.0 (spec 047, `specs/047-framework-port/plan.md`). The application core in `acryl-router` and the Node adapter in
+`acryl-node-server` are ported from a mature MIT web framework with their test suites; the Cordis plugins around them are ACRYL's own.
+
+The ACRYL Framework is the small, readable layer on top of Cordis that turns "a bunch of DSH packages" into building an agentic app. You
+write an ordinary `App` (routes, a `Context`, middleware with `next()`, validators and helpers on Web-standard `Request` and `Response`),
+and a Cordis plugin mounts it with `ctx.router.route(path, app)`.
+
+## The five rules
+
+1. **Everything extensible is a Cordis plugin.**
+2. **One application, several surfaces** - share capabilities and contracts, not necessarily the transport.
+3. **One declared contract per plugin** - what it provides, needs, and registers (routes, commands, tools, slots).
+4. **Every registration is reversible** - unloading a plugin removes what it owns.
+5. **Conventions are explicit and small** - an ordinary feature needs no knowledge of runtime internals.
+
+## What it gives you
+
+One handler, every surface. A plugin writes a handler once; Web and Desktop reach it over HTTP (Desktop's window talks to the app's own
+loopback server), the terminal UI and tests call it in process with `ctx.router.request(path)`, and a standalone process serves it with
+`acryl-node-server`. The universal entry point is `ctx.router.fetch(request)`.
+
+## Documentation map
+
+| Topic | Page |
+| --- | --- |
+| First application | [Getting started](./getting-started.md) |
+| Every everyday call on one page | [API summary](./api-summary.md) |
+| Framework model | [Core concepts](./concepts.md) |
+| Routes and mounting | [Routing and mounting](./routing.md) |
+| Handler context | [Context](./context.md) |
+| Reading requests | [Request](./request.md) |
+| Cross-cutting behavior, and the built-in list | [Middleware](./middleware.md) |
+| Input checking | [Validation](./validation.md) |
+| Streaming, cookies, testing and the rest | [Helpers](./helpers.md) |
+| Serving without the ACRYL Host | [Node server](./node-server.md) |
+| Cordis ownership and service state | [Plugin lifecycle and disposal](./plugin-lifecycle.md) |
+| The application surfaces | [Surfaces and adapters](./surfaces.md) |
+| Leaving the DSH server | [Migration from the DSH webServer](./migration-from-dsh-webserver.md) |
+| Moving from 0.3 | [Migration from 0.3](./migration-from-0-3.md) |
+
+[ACRYL Blends](https://acrylblends.github.io/) is the product-facing guide for building and publishing complete applications. The
+framework pages here are the API and integration reference behind those guides. The mirrored developer documentation is published at
+[acryl.dev/docs](https://acryl.dev/docs).
+
+## The packages
+
+| Package | What it is |
+| --- | --- |
+| `acryl-router` | `App` and the whole application API; the Cordis `router` service that composes the mounted apps; `acryl-router/middleware`, `acryl-router/helpers`, `acryl-router/client` |
+| `acryl-router-http` | inside the ACRYL Host: `ctx.routerHttp.mount(prefix)` serves a prefix of the router on the Host's web server |
+| `acryl-node-server` | without the Host: one `node:http` server for the whole router, `ctx.nodeServer.url`, and `serveStatic` |
+| `acryl-state` | observable cells shared by every surface, with read-only HTTP and SSE routes and `useCell` for React |
+| `acryl-inspect` | what each plugin requires, provides and mounts, read from the running system |
+
+An app's `tsconfig.json` can extend `acryl-router/tsconfig.app.json` (ES2024 with the DOM types, strict).
+
+## Why this exists
+
+DSH changes fast and stays one optional agent inside ACRYL. Cordis is the lifecycle ACRYL keeps across Web (browser), Desktop (Electron)
+and the terminal UI. HTTP used to go through DSH's `webServer` - a `node:http` route table with no middleware and no Web-standard
+`Request`/`Response` - which the terminal UI cannot reuse. The framework removes that coupling.

package/docs/framework/UPSTREAM.md

@@ -0,0 +1,3 @@
+# Generated copy
+
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `64e7c9d2e787f74b2da82492644fbbb46a601074`, 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/api-summary.md

@@ -0,0 +1,138 @@
+# API summary
+
+One page with the calls an ordinary app uses, each linked to the page that explains it. Imports are from `acryl-router` unless noted.
+
+## A plugin that serves an app
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { App } from 'acryl-router'
+import { trimTrailingSlash } from 'acryl-router/middleware'
+import { schemaValidator, streamSSE, type StandardSchema } from 'acryl-router/helpers'
+import type {} from 'acryl-state'
+
+export const name = 'orders'                 // the package name and the Loader row id
+export const inject = ['router', 'state']    // the plugin waits (PENDING) until both exist
+
+interface Order { id: string, item: string }
+const NewOrder: StandardSchema<{ item: string }> = {
+  '~standard': {
+    validate: value => {
+      const item = (value as { item?: unknown } | null)?.item
+      return typeof item === 'string' && item !== '' ? { value: { item } } : { issues: [{ message: 'item is required', path: ['item'] }] }
+    },
+  },
+}
+
+export function apply(ctx: Context): void {
+  const orders = ctx.state.cell<Order[]>('orders.list', [])
+  const app = new App()
+    .use(trimTrailingSlash())
+    .get('/', c => c.json(orders.get()))
+    .post('/', schemaValidator('json', NewOrder), c => {
+      const order = { id: crypto.randomUUID(), ...c.req.valid('json') }
+      orders.update(list => [...list, order])
+      return c.json(order, 201)
+    })
+    .get('/events', c => streamSSE(c, async stream => {
+      const ended = new Promise<void>(resolve => { stream.onAbort(resolve) })
+      const stop = orders.subscribe(list => { void stream.writeSSE({ data: JSON.stringify(list) }) })
+      await stream.writeSSE({ data: JSON.stringify(orders.get()) })
+      try { await ended } finally { stop() }
+    }))
+  ctx.router.route('/orders', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/orders') })
+}
+```
+
+## `App` ([Routing](./routing.md))
+
+| Call | Does |
+| --- | --- |
+| `new App()` | an application: a route table plus middleware |
+| `.get / .post / .put / .patch / .delete / .options (path, ...handlers)` | a route; handlers before the last are middleware for that route |
+| `.all(path, ...)`, `.on(methods, path, ...)` | any method, or a list of methods |
+| `.use([path], ...middleware)` | middleware for every route below `path` (all routes without it), registered before the routes it wraps |
+| `.route(path, otherApp)` | copy another app's routes below `path` |
+| `.basePath(path)` | the same app with a prefix on every route registered through it |
+| `.onError((err, c) => ...)`, `.notFound(c => ...)` | the app's error and not-found answers |
+| `.request(pathOrRequest, init?)` | call the app in process (tests) |
+| `.fetch(request)` | the app as a fetch handler |
+
+Paths: `/posts/:id` (parameter), `/posts/:id?` (optional), `/files/*` (wildcard), `/:name{[a-z]+}` (pattern). `/a` and `/a/` are different
+paths: see [Trailing slashes](./routing.md#trailing-slashes).
+
+## The handler context `c` ([Context](./context.md))
+
+| Call | Does |
+| --- | --- |
+| `c.json(value, status?, headers?)` | a JSON answer |
+| `c.text(text, status?)`, `c.html(html, status?)` | a text or HTML answer |
+| `c.body(data, status?, headers?)` | a raw answer (`c.body(null, 204)`) |
+| `c.redirect(location, status = 302)` | a redirect |
+| `c.notFound()` | the app's not-found answer |
+| `c.header(name, value)`, `c.status(code)` | set a header or the status (also after `await next()` in middleware) |
+| `c.set(key, value)`, `c.get(key)`, `c.var.key` | values for this request only, passed from middleware to handlers |
+| `c.req.raw.signal` | aborts when the caller leaves, the serving plugin unloads, or the router is disposed |
+| `c.executionCtx.waitUntil(promise)` | keep the request in flight until background work settles |
+| `connectionOf(c)` / `getConnInfo(c)` | the caller's address and the local port, when a transport supplied them |
+| `throw new HTTPException(status, { message })` | stop with that status from anywhere in the chain |
+
+## The request `c.req` ([Request](./request.md))
+
+| Call | Gives |
+| --- | --- |
+| `c.req.param('id')`, `c.req.param()` | route parameters |
+| `c.req.query('page')`, `c.req.query()`, `c.req.queries('tag')` | query string values (`queries` for repeated keys) |
+| `c.req.header('x-name')`, `c.req.header()` | request headers |
+| `await c.req.json()`, `c.req.text()`, `c.req.formData()`, `c.req.parseBody()`, `c.req.arrayBuffer()`, `c.req.blob()` | the body, once |
+| `c.req.valid(target)` | the value a validator checked, typed by its schema |
+| `c.req.method`, `c.req.path`, `c.req.url`, `c.req.raw` | the method, path, full URL and the Web `Request` |
+
+## Validation ([Validation](./validation.md))
+
+```ts
+import { schemaValidator, validator } from 'acryl-router/helpers'
+app.post('/', schemaValidator('json', Schema), c => c.json(c.req.valid('json')))
+```
+
+- Targets: `json`, `form`, `query`, `param`, `header`, `cookie`. `Schema` is any Standard Schema (Schemastery, Zod, Valibot, or an
+  object with `'~standard': { validate }`).
+- A failure is 400 `{ error: 'invalid <target>', issues: [{ message, path }] }`; `path` is dotted, and `""` when the issue has none.
+- The `json` target reads the body only with a JSON `Content-Type`; otherwise the schema sees `{}`.
+- `validator(target, (value, c) => valueOrResponse)` is the same middleware with a function instead of a schema.
+- Put `bodyLimit({ maxSize })` from `acryl-router/middleware` in front on routes open to untrusted callers.
+
+## Streaming ([Helpers](./helpers.md))
+
+| Call | Does |
+| --- | --- |
+| `streamSSE(c, async stream => { ... })` | a server-sent event answer |
+| `stream.writeSSE({ data, event?, id?, retry? })` | send one event (`data` is a string) |
+| `stream.write(text)`, `stream.writeln(text)` | raw bytes or a line (a comment line such as `: keep-alive\n\n` keeps a proxy from closing the stream) |
+| `stream.onAbort(fn)`, `stream.aborted` | the client left or the plugin unloaded: stop work and release subscriptions |
+| `stream(c, ...)`, `streamText(c, ...)` | a byte stream or a text stream instead of events |
+
+Do not start timers inside a handler for keep-alives; let the plugin own one timer and write to the open streams.
+
+## Cordis services
+
+| Call | Service | Does |
+| --- | --- | --- |
+| `ctx.router.route(path, app)` | `router` (`acryl-router`) | serve `app` below `path` for as long as the calling plugin is loaded; returns a function that removes it sooner |
+| `ctx.router.request(path, init?)`, `ctx.router.fetch(request)` | `router` | call the mounted routes in process (terminal UI, tests, other plugins) |
+| `ctx.router.onError(handler)`, `ctx.router.notFound(handler)` | `router` | router-wide error and not-found answers, owned by the caller |
+| `ctx.routerHttp.mount(prefix)` | `routerHttp` (`acryl-router-http`) | inside the ACRYL Host: serve a router prefix on the Host's web server (Web and Desktop). Use it through `ctx.inject(['routerHttp'], ...)` so the app also runs where there is no Host |
+| `ctx.nodeServer.url`, `ctx.nodeServer.port` | `nodeServer` (`acryl-node-server`) | without the Host: one Node server for the whole router; options `hostname` (`127.0.0.1`), `port` (`0`), `scan` (`20`). See [Node server](./node-server.md) |
+| `ctx.state.cell(key, initial)` | `state` (`acryl-state`) | a writable cell owned by the plugin: `get()`, `set(value)`, `update(fn)`, `subscribe(fn)` returning an unsubscribe |
+| `ctx.state.derive(key, [cells], fn)` | `state` | a read-only cell computed from others |
+| `GET /api/state/:key`, `GET /api/state/:key/events` | `state` | each cell over the router, read-only; `useCell(cell)` from `acryl-state/react` in a React page |
+
+Everything a plugin registers this way (mounts, cells, handlers) goes away when the plugin unloads, and comes back once when it reloads:
+see [Plugin lifecycle and disposal](./plugin-lifecycle.md).
+
+## Middleware ([Middleware](./middleware.md))
+
+From `acryl-router/middleware`: `bodyLimit`, `cors`, `csrf`, `secureHeaders`, `etag`, `compress`, `logger`, `requestId`, `timeout`,
+`bearerAuth`, `basicAuth`, `jwt`, `jwk`, `ipRestriction`, `methodNotAllowed`, `trimTrailingSlash`, `appendTrailingSlash`, `some` /
+`every` / `except`, and ACRYL's `loopbackOnly` for private loopback routes.

package/docs/framework/concepts.md

@@ -0,0 +1,105 @@
+# Core concepts
+
+The framework's request-handling model is designed so every extension point belongs to a Cordis plugin. This page explains the pieces
+before the API reference.
+
+## App
+
+An `App` is a self-contained ACRYL application. It owns:
+
+- routes;
+- middleware;
+- an error handler (`app.onError`);
+- a request entry point (`app.fetch`, and `app.request` for tests);
+- sub-applications placed below a path with `app.route(path, sub)`.
+
+An app can be tested without a server:
+
+```ts
+const response = await app.request('/todos/42')
+```
+
+An app is not itself a Cordis service. That separation lets the same app be mounted by different hosts, at different paths, or not
+mounted at all.
+
+## Router service
+
+The Cordis `router` service (`ctx.router`, provided by `acryl-router`) composes the mounted apps into one route space. A plugin builds an
+app and mounts it:
+
+```ts
+ctx.router.route('/todo', app)
+```
+
+The mount copies the app's routes at that call. When any mount is added or removed, the next request composes a fresh app from the mounts
+that are live, in the order they were made; requests already running keep the app they started with. This matches Cordis: plugins can
+load, unload, reload and be replaced while the host stays up. The core's route tables are add-only, so rebuilding is the only correct way
+to remove a route; it costs about 1 ms per 1000 routes, once per change.
+
+The router also takes one router-wide `onError` and one `notFound` (each owned by the plugin that set it), and runs requests in process:
+`ctx.router.fetch(request, connection?)` and `ctx.router.request(path, init?, connection?)`.
+
+## Handler
+
+A handler receives one context object, conventionally named `c`:
+
+```ts
+app.get('/todos/:id', c => {
+  return c.json({ id: c.req.param('id') })
+})
+```
+
+Handlers return a Web `Response`, either directly or through context helpers such as `c.text`, `c.json` and `c.html`.
+
+## Middleware
+
+Middleware wraps handlers and other middleware:
+
+```ts
+app.use('/admin/*', async (c, next) => {
+  if (!isAllowed(c)) return c.text('Forbidden', 403)
+  await next()
+})
+```
+
+Code before `await next()` runs on the way in. Code after it can inspect or change the response (`c.res`) on the way out.
+
+## Surface
+
+A surface is the place a person or another program uses the application:
+
+| Surface | Transport |
+| --- | --- |
+| Web | the ACRYL Host's web server, through `acryl-router-http` |
+| Desktop | the same: the Electron window talks to the app's own loopback web server |
+| Terminal UI | in process: `ctx.router.request(...)`, no server |
+| A standalone process | `acryl-node-server` serves the whole router |
+| Tests | `ctx.router.request(...)` or `app.request(...)` |
+
+Surfaces share capabilities and contracts. They do not need to share a transport or a user interface.
+
+## Plugin contract
+
+Following the ACRYL framework rules, a plugin declares what it:
+
+- provides as services;
+- requires through injection;
+- registers as routes, commands, tools or interface slots;
+- owns until disposal.
+
+The declaration is what lets tooling answer two questions without reading all the code: what does this plugin do, and what disappears
+when it unloads? `acryl-inspect` reads it from the running system: each mount is labeled with its path and has one labeled child per route it serves.
+
+## State
+
+Request state belongs to the context. Application state shared between surfaces belongs in `acryl-state` or an application-owned Cordis
+service. Do not hide shared mutable state in module globals: Cordis can reload plugins and run several surfaces from one host, and a
+module global outlives the plugin that wrote it.
+
+## Design rules
+
+1. Everything extensible is a Cordis plugin.
+2. One application can serve several surfaces.
+3. Each plugin has one declared contract.
+4. Every registration is reversible.
+5. Normal application code should not need runtime internals.