@brendanbank/create-atrium-host 0.15.0

package/LICENCE.md

@@ -0,0 +1,25 @@
+# BSD 2-Clause License
+
+Copyright (c) 2026, Brendan Bank
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,94 @@
+# @brendanbank/create-atrium-host
+
+Scaffolder for a new [atrium](https://github.com/brendanbank/atrium)
+host extension. One command, working repo: backend Python package +
+frontend Vite host bundle + compose stack + CI, all wired against
+atrium's published image and host SDK packages.
+
+## Usage
+
+```sh
+npx @brendanbank/create-atrium-host casa-del-leone
+```
+
+Walks you through a short prompt sequence (Python module name, brand
+display name, primary colour) and emits a git-initialised repo that's
+ready to `make dev-bootstrap`.
+
+For non-interactive use:
+
+```sh
+npx @brendanbank/create-atrium-host test-host --yes-defaults
+```
+
+### Options
+
+| Flag                    | Effect                                                |
+|-------------------------|-------------------------------------------------------|
+| `--yes-defaults`        | Skip prompts; derive everything from the project name |
+| `--no-git`              | Skip `git init` + initial commit                      |
+| `--out <dir>`           | Output directory (default: `./<name>`)                |
+| `--atrium <version>`    | Atrium image / SDK version pin (default: `0.15`)      |
+| `-h`, `--help`          | Show help                                             |
+
+## What it emits
+
+```
+casa-del-leone/
+  Dockerfile           frontend-builder + FROM atrium runtime
+  compose.yaml         api + worker + mysql
+  .env.example         secrets template (copy to .env)
+  Makefile             dev-bootstrap / migrate / seed-* / test
+  backend/             Python host package (`casa_del_leone`)
+    pyproject.toml
+    alembic.ini
+    alembic/           alembic_version_app chain
+    src/casa_del_leone/
+      bootstrap.py     init_app + init_worker
+      models.py        HostBase + demo singleton
+      router.py        /casa_del_leone/state + /casa_del_leone/bump
+      scripts/seed_host_bundle.py
+    tests/             pytest smoke tests
+  frontend/            Vite library project (single main.js)
+    package.json       @brendanbank/atrium-host-bundle-utils + -types + -test-utils
+    vite.config.ts     hostBundleConfig({ entry: 'src/main.tsx' })
+    src/
+      main.tsx         ~10 lines of registry calls — no wrapper element code
+      api.ts           plain fetch with credentials: include
+      queryClient.ts
+      CasaDelLeoneWidget.tsx       home widget + admin tab + page demo
+      CasaDelLeonePage.tsx
+      CasaDelLeoneAdminTab.tsx
+      CasaDelLeoneProfileItem.tsx
+    src/test/          vitest setup + worked example using @brendanbank/atrium-test-utils
+  .github/
+    workflows/ci.yml   typecheck + tests + smoke
+    dependabot.yml     weekly grouped bumps
+```
+
+The seeded BrandConfig (in the first migration) materialises the
+brand name + primary colour into `app_settings[brand]` so the SPA
+renders with the host's identity from the first page load.
+
+## What atrium gives you (don't reimplement)
+
+The host repo's README enumerates this — auth, RBAC, audit, email
+pipeline, scheduled jobs, notifications, admin shell, theme, i18n,
+maintenance mode, account deletion. Atrium ships all of it; the
+scaffolder leaves only the domain-specific surface for you to fill
+in.
+
+## Updating the template
+
+The template lives under `template/` with `__HOST_NAME__`,
+`__HOST_PKG__`, `__BRAND_NAME__`, `__BRAND_PASCAL__`, `__BRAND_PRIMARY__`,
+`__ATRIUM_VERSION__` placeholders. Add a new placeholder by:
+
+1. Use it in template files / paths.
+2. Add a derivation + validator in `src/names.js`.
+3. Add it to the prompt list (or default block) in `src/cli.js`.
+4. Map it to the upper-snake key in `buildVars()`.
+
+The CI smoke target is `pnpm smoke` — it scaffolds `__smoke_test_host__`
+into `/tmp` non-interactively and reports failure if anything in the
+template ends up unparseable.

package/bin/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+
+// Thin shim that forwards into the CLI module. Lives separately so
+// `package.json#bin` can stay pointed at a stable path while the
+// implementation moves.
+import('../src/cli.js').then(({ run }) => run(process.argv.slice(2)));

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@brendanbank/create-atrium-host",
+  "version": "0.15.0",
+  "description": "Scaffolder for new atrium host extensions: backend Python package + frontend Vite bundle + compose stack + CI, all wired against atrium's published image and host SDK packages. Run via `npx @brendanbank/create-atrium-host <name>`.",
+  "license": "BSD-2-Clause",
+  "type": "module",
+  "bin": {
+    "create-atrium-host": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brendanbank/atrium.git",
+    "directory": "packages/create-atrium-host"
+  },
+  "scripts": {
+    "build": "echo 'create-atrium-host is plain ESM JS; no build step.'",
+    "typecheck": "echo 'create-atrium-host is plain ESM JS; no typecheck step.'",
+    "test": "node --test test/names.test.js test/render.test.js",
+    "smoke": "node bin/index.js smoke-test-host --yes-defaults --no-git --out /tmp/atrium-scaffold-smoke && echo 'smoke ok'"
+  }
+}

package/src/cli.js

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+
+// CLI entry point.
+//
+//   create-atrium-host <name> [--yes-defaults] [--no-git] [--out <dir>]
+//
+// Without --yes-defaults the user is prompted for the host package
+// name, brand display name, primary colour, and atrium image
+// version. `--yes-defaults` derives everything from the project name
+// and skips prompts (used by CI smoke tests and anyone who just wants
+// the baseline).
+
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve, isAbsolute } from 'node:path';
+import { stat } from 'node:fs/promises';
+
+import kleur from 'kleur';
+import prompts from 'prompts';
+
+import {
+  brandPascal,
+  defaultBrandName,
+  defaultHostPkg,
+  validateBrandName,
+  validateBrandPrimary,
+  validateHostName,
+  validateHostPkg,
+} from './names.js';
+import { ensureEmptyDir, pathExists, renderTemplate } from './render.js';
+import { gitAvailable, initRepo } from './git.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATE_DIR = resolve(__dirname, '..', 'template');
+
+// The atrium image + SDK packages version in lockstep. Bump this when
+// cutting a new atrium release so freshly scaffolded hosts pin against
+// the right line.
+const DEFAULT_ATRIUM_VERSION = '0.15';
+
+const HELP = `
+${kleur.bold('create-atrium-host')} — scaffold a new atrium host extension
+
+Usage:
+  npx @brendanbank/create-atrium-host <name> [options]
+
+Arguments:
+  <name>              Project name (lowercase, dashes; e.g. casa-del-leone)
+
+Options:
+  --yes-defaults      Skip prompts; derive everything from <name>
+  --no-git            Skip ${kleur.cyan('git init')} + initial commit
+  --out <dir>         Output directory (default: ./<name>)
+  --atrium <version>  Atrium image / SDK version pin (default: ${DEFAULT_ATRIUM_VERSION})
+  -h, --help          Show this help
+
+The scaffolder emits a working repo: ${kleur.bold('make dev-bootstrap')} brings up the
+stack, ${kleur.bold('make seed-admin')} + ${kleur.bold('make seed-bundle')} finish wiring it, and
+${kleur.bold('make test')} is green out of the box.
+`;
+
+function parseArgs(argv) {
+  const args = { positional: [], flags: {}, options: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') {
+      args.flags.help = true;
+    } else if (a === '--yes-defaults') {
+      args.flags.yesDefaults = true;
+    } else if (a === '--no-git') {
+      args.flags.noGit = true;
+    } else if (a === '--out') {
+      args.options.out = argv[++i];
+    } else if (a.startsWith('--out=')) {
+      args.options.out = a.slice('--out='.length);
+    } else if (a === '--atrium') {
+      args.options.atrium = argv[++i];
+    } else if (a.startsWith('--atrium=')) {
+      args.options.atrium = a.slice('--atrium='.length);
+    } else if (a.startsWith('--')) {
+      throw new Error(`unknown option: ${a}`);
+    } else {
+      args.positional.push(a);
+    }
+  }
+  return args;
+}
+
+async function gatherAnswers({ hostNameArg, yesDefaults, atriumVersion }) {
+  // Fixed answers regardless of mode — derived from CLI arg so tests
+  // can pass them in deterministically.
+  const fixed = {
+    hostName: hostNameArg,
+    atriumVersion,
+  };
+
+  if (yesDefaults) {
+    const hostPkg = defaultHostPkg(hostNameArg);
+    const brandName = defaultBrandName(hostNameArg);
+    return {
+      ...fixed,
+      hostPkg,
+      brandName,
+      brandPrimary: 'blue',
+    };
+  }
+
+  const responses = await prompts([
+    {
+      type: 'text',
+      name: 'hostPkg',
+      message: 'Python module name',
+      initial: defaultHostPkg(hostNameArg),
+      validate: validateHostPkg,
+    },
+    {
+      type: 'text',
+      name: 'brandName',
+      message: 'Brand display name',
+      initial: defaultBrandName(hostNameArg),
+      validate: validateBrandName,
+    },
+    {
+      type: 'select',
+      name: 'brandPrimary',
+      message: 'Primary colour (Mantine palette)',
+      choices: [
+        { title: 'blue', value: 'blue' },
+        { title: 'teal', value: 'teal' },
+        { title: 'indigo', value: 'indigo' },
+        { title: 'violet', value: 'violet' },
+        { title: 'grape', value: 'grape' },
+        { title: 'pink', value: 'pink' },
+        { title: 'red', value: 'red' },
+        { title: 'orange', value: 'orange' },
+        { title: 'green', value: 'green' },
+        { title: 'gray', value: 'gray' },
+      ],
+      initial: 0,
+    },
+  ], {
+    onCancel: () => {
+      console.error(kleur.red('cancelled.'));
+      process.exit(130);
+    },
+  });
+
+  return { ...fixed, ...responses };
+}
+
+function buildVars({ hostName, hostPkg, brandName, brandPrimary, atriumVersion }) {
+  return {
+    HOST_NAME: hostName,
+    HOST_PKG: hostPkg,
+    BRAND_NAME: brandName,
+    BRAND_PASCAL: brandPascal(brandName),
+    BRAND_PRIMARY: brandPrimary,
+    ATRIUM_VERSION: atriumVersion,
+  };
+}
+
+function printNextSteps({ outDir, hostName }) {
+  const cd = `cd ${outDir}`;
+  console.log();
+  console.log(kleur.green().bold('done.'));
+  console.log();
+  console.log(`Next steps:`);
+  console.log(`  ${kleur.cyan(cd)}`);
+  console.log(`  ${kleur.cyan('cp .env.example .env')}                  # fill in secrets`);
+  console.log(`  ${kleur.cyan('make dev-bootstrap')}                    # build + start + migrate`);
+  console.log(`  ${kleur.cyan(`make seed-admin EMAIL=you@example.com PASSWORD='good-password'`)}`);
+  console.log(`  ${kleur.cyan('make seed-bundle')}                      # point atrium at /host/main.js`);
+  console.log(`  ${kleur.cyan('open http://localhost:8000')}`);
+  console.log();
+  console.log(kleur.dim(`The ${kleur.bold(hostName)} card will appear on the home page after login.`));
+  console.log();
+}
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    console.error(kleur.red(err.message));
+    console.error(HELP);
+    process.exit(2);
+  }
+
+  if (parsed.flags.help || parsed.positional.length === 0) {
+    console.log(HELP);
+    process.exit(parsed.flags.help ? 0 : 2);
+  }
+
+  if (parsed.positional.length > 1) {
+    console.error(kleur.red(`unexpected extra args: ${parsed.positional.slice(1).join(' ')}`));
+    process.exit(2);
+  }
+
+  const hostName = parsed.positional[0];
+  const nameOk = validateHostName(hostName);
+  if (nameOk !== true) {
+    console.error(kleur.red(`invalid project name: ${nameOk}`));
+    process.exit(2);
+  }
+
+  const atriumVersion = parsed.options.atrium ?? DEFAULT_ATRIUM_VERSION;
+
+  const outDirArg = parsed.options.out ?? hostName;
+  const outDir = isAbsolute(outDirArg) ? outDirArg : resolve(process.cwd(), outDirArg);
+
+  if (await pathExists(outDir)) {
+    const info = await stat(outDir);
+    if (!info.isDirectory()) {
+      console.error(kleur.red(`destination exists and is not a directory: ${outDir}`));
+      process.exit(1);
+    }
+    try {
+      await ensureEmptyDir(outDir);
+    } catch {
+      console.error(kleur.red(`destination ${outDir} exists and is not empty.`));
+      console.error(kleur.dim('pick a different --out, or delete the existing tree.'));
+      process.exit(1);
+    }
+  }
+
+  const answers = await gatherAnswers({
+    hostNameArg: hostName,
+    yesDefaults: parsed.flags.yesDefaults === true,
+    atriumVersion,
+  });
+
+  // Re-validate the prompted answers in case a non-interactive caller
+  // passed bad values via stdin (or the user accepted a bad default).
+  for (const [key, validator] of [
+    ['hostPkg', validateHostPkg],
+    ['brandName', validateBrandName],
+    ['brandPrimary', validateBrandPrimary],
+  ]) {
+    const v = validator(answers[key]);
+    if (v !== true) {
+      console.error(kleur.red(`invalid ${key}: ${v}`));
+      process.exit(2);
+    }
+  }
+
+  const vars = buildVars(answers);
+
+  console.log();
+  console.log(kleur.bold(`Scaffolding ${hostName} into ${outDir}`));
+  console.log(kleur.dim(`  python module : ${vars.HOST_PKG}`));
+  console.log(kleur.dim(`  brand name    : ${vars.BRAND_NAME}`));
+  console.log(kleur.dim(`  primary       : ${vars.BRAND_PRIMARY}`));
+  console.log(kleur.dim(`  atrium image  : ghcr.io/brendanbank/atrium:${vars.ATRIUM_VERSION}`));
+  console.log();
+
+  const written = await renderTemplate({
+    templateDir: TEMPLATE_DIR,
+    outDir,
+    vars,
+  });
+
+  console.log(kleur.green(`✓ wrote ${written.length} files`));
+
+  if (!parsed.flags.noGit) {
+    if (await gitAvailable()) {
+      try {
+        await initRepo(outDir);
+        console.log(kleur.green('✓ initialised git, made initial commit'));
+      } catch (err) {
+        console.warn(kleur.yellow(`! git init failed (${err.message.split('\n')[0]}); skipping`));
+      }
+    } else {
+      console.warn(kleur.yellow('! git not on PATH; skipping repo init'));
+    }
+  }
+
+  printNextSteps({ outDir, hostName });
+}

package/src/git.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+
+import { spawn } from 'node:child_process';
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...opts,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve({ stdout, stderr });
+      else reject(new Error(`${cmd} ${args.join(' ')} exited ${code}: ${stderr}`));
+    });
+  });
+}
+
+export async function gitAvailable() {
+  try {
+    await run('git', ['--version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function initRepo(cwd) {
+  // -b main so first-time users get the modern default branch name
+  // without having to set init.defaultBranch globally.
+  await run('git', ['init', '-b', 'main'], { cwd });
+  await run('git', ['add', '.'], { cwd });
+  // -n bypasses commit hooks (the freshly scaffolded repo has none
+  // yet, but a parent .gitconfig-installed pre-commit could fire on
+  // any subdirectory). --no-gpg-sign because the user hasn't decided
+  // whether they want signing on this repo yet; they can amend the
+  // initial commit if they do. Both stay non-interactive so the
+  // scaffolder doesn't hang behind a pinentry prompt.
+  await run('git', ['commit', '-n', '--no-gpg-sign', '-m', 'Initial scaffold'], {
+    cwd,
+    env: { ...process.env, GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME ?? process.env.USER ?? 'scaffold', GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL ?? 'scaffold@local', GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME ?? process.env.USER ?? 'scaffold', GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL ?? 'scaffold@local' },
+  });
+}

package/src/names.js

@@ -0,0 +1,91 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+
+// Name derivations and validators.
+//
+// `create-atrium-host casa-del-leone` should give:
+//   hostName    = casa-del-leone     (CLI/image tag, lowercase, dash-separated)
+//   hostPkg     = casa_del_leone     (Python module, lowercase, underscores)
+//   brandName   = Casa Del Leone     (display, title-cased words)
+//   brandPascal = CasaDelLeone       (component prefix in TSX)
+
+const PYTHON_KEYWORDS = new Set([
+  'False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await',
+  'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except',
+  'finally', 'for', 'from', 'global', 'if', 'import', 'in', 'is',
+  'lambda', 'nonlocal', 'not', 'or', 'pass', 'raise', 'return', 'try',
+  'while', 'with', 'yield', 'match', 'case',
+]);
+
+// Atrium owns these top-level names — collisions break import resolution
+// (`app` is the FastAPI app module; the others would shadow stdlib).
+const RESERVED_PKGS = new Set(['app', 'alembic', 'fastapi', 'sqlalchemy', 'pydantic']);
+
+export function validateHostName(name) {
+  if (!name) return 'name is required';
+  if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(name)) {
+    return 'use lowercase letters, digits, and dashes (e.g. casa-del-leone). ' +
+      'must start with a letter and end with a letter or digit.';
+  }
+  if (name.length > 50) return 'name is too long (max 50 chars)';
+  if (name.includes('--')) return 'no consecutive dashes';
+  return true;
+}
+
+export function validateHostPkg(pkg) {
+  if (!pkg) return 'python module name is required';
+  if (!/^[a-z][a-z0-9_]*$/.test(pkg)) {
+    return 'use lowercase letters, digits, and underscores; must start with a letter';
+  }
+  if (PYTHON_KEYWORDS.has(pkg)) return `${pkg} is a Python keyword`;
+  if (RESERVED_PKGS.has(pkg)) {
+    return `${pkg} collides with a reserved name (atrium owns 'app'; others would shadow common libs)`;
+  }
+  return true;
+}
+
+export function validateBrandName(name) {
+  if (!name) return 'brand name is required';
+  if (name.length > 60) return 'brand name is too long (max 60 chars)';
+  return true;
+}
+
+const MANTINE_COLORS = new Set([
+  'dark', 'gray', 'red', 'pink', 'grape', 'violet', 'indigo', 'blue',
+  'cyan', 'teal', 'green', 'lime', 'yellow', 'orange',
+]);
+
+export function validateBrandPrimary(value) {
+  if (!value) return 'primary colour is required';
+  if (!MANTINE_COLORS.has(value)) {
+    return `must be a Mantine palette name (${[...MANTINE_COLORS].join(', ')})`;
+  }
+  return true;
+}
+
+export function defaultHostPkg(hostName) {
+  return hostName.replace(/-/g, '_');
+}
+
+export function defaultBrandName(hostName) {
+  return hostName
+    .split('-')
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+export function brandPascal(brandName) {
+  // Strip non-alphanumeric, capitalize each word, drop spaces. The
+  // brand name is human-friendly ("Casa del Leone") so we have to
+  // re-derive a JSX-safe identifier from it.
+  const cleaned = brandName.replace(/[^A-Za-z0-9 ]/g, ' ');
+  const pascal = cleaned
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+  // Identifier can't start with a digit. Prepend "Host" if it does
+  // (rare — would require a brand name starting with a digit).
+  return /^[A-Za-z]/.test(pascal) ? pascal : `Host${pascal}`;
+}

package/src/render.js

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+
+// Walk the template tree, substitute placeholders in both file paths
+// and file contents, write into the destination.
+//
+// Placeholder convention is `__UPPER_SNAKE__` so a `grep -r __HOST_`
+// inside the emitted repo finds anything we forgot to substitute.
+// Binary files are passed through unchanged.
+
+import { readdir, readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+
+const BINARY_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.woff', '.woff2',
+  '.ttf', '.otf', '.eot', '.pdf',
+]);
+
+function isBinaryPath(path) {
+  const dot = path.lastIndexOf('.');
+  if (dot < 0) return false;
+  return BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+
+export function substitute(text, vars) {
+  let out = text;
+  for (const [key, value] of Object.entries(vars)) {
+    // Match the literal placeholder. Using split+join sidesteps regex
+    // escaping; the placeholder set is tiny so the cost is negligible.
+    out = out.split(`__${key}__`).join(value);
+  }
+  return out;
+}
+
+async function* walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+
+export async function renderTemplate({ templateDir, outDir, vars }) {
+  const written = [];
+  for await (const srcPath of walk(templateDir)) {
+    const relPath = relative(templateDir, srcPath);
+    const renamedRel = substitute(relPath, vars);
+    const destPath = join(outDir, renamedRel);
+    await mkdir(dirname(destPath), { recursive: true });
+    if (isBinaryPath(srcPath)) {
+      // Copy binary as-is.
+      const data = await readFile(srcPath);
+      await writeFile(destPath, data);
+    } else {
+      const content = await readFile(srcPath, 'utf8');
+      await writeFile(destPath, substitute(content, vars));
+    }
+    written.push(renamedRel);
+  }
+  return written;
+}
+
+export async function ensureEmptyDir(dir) {
+  try {
+    const entries = await readdir(dir);
+    if (entries.length > 0) {
+      throw new Error(`destination ${dir} is not empty`);
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      await mkdir(dir, { recursive: true });
+      return;
+    }
+    throw err;
+  }
+}
+
+export async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}