wavework 0.0.0-stage → 0.1.1

package/src/config.mjs

@@ -0,0 +1,313 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Location of the config file, relative to the repository root. */
+export const CONFIG_PATH = '.claude/wavework.json';
+
+/** Defaults for every optional field with a default. Never mutated; results get deep copies. */
+export const DEFAULTS = Object.freeze({
+  worktree: Object.freeze({
+    pathPattern: '../{repo}-{unit}',
+    branchPattern: '{prefix}/{unit}-{slug}',
+  }),
+  models: Object.freeze({
+    planning: 'opus',
+    orchestration: 'opus',
+    implementers: Object.freeze({
+      default: 'sonnet',
+      rules: Object.freeze({
+        haiku: 'Small, well-specified, low-risk changes: boilerplate, renames, config tweaks, docs, straightforward tests.',
+        sonnet: 'Everything else: multi-file features, non-trivial logic, debugging, refactors. When unsure, use sonnet.',
+      }),
+    }),
+  }),
+  tracker: Object.freeze({ kind: 'beads' }),
+  findings: Object.freeze({
+    epicTitles: Object.freeze({
+      security: 'Findings: Security & authorization',
+      bugs: 'Findings: Bugs & correctness',
+      tests: 'Findings: Tests & CI stability',
+      quality: 'Findings: Code quality, UI & docs',
+    }),
+  }),
+  attribution: Object.freeze({ allowAiTrailer: false }),
+  dashboard: Object.freeze({ enabled: true, port: 4690 }),
+});
+
+const PATH_PLACEHOLDERS = ['repo', 'unit'];
+const BRANCH_PLACEHOLDERS = ['prefix', 'unit', 'slug'];
+const TRACKER_KINDS = ['beads'];
+
+const clone = (v) => structuredClone(v);
+
+function typeName(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+const isObject = (v) => typeName(v) === 'object';
+const join_ = (base, key) => (base ? `${base}.${key}` : key);
+
+// Each helper returns the validated value (or undefined when invalid/absent) and pushes problems.
+
+function str(v, path, errs) {
+  if (typeof v === 'string' && v.trim() !== '') return v;
+  errs.push(`${path}: expected a non-empty string, got ${typeName(v)}`);
+  return undefined;
+}
+
+function bool(v, path, errs) {
+  if (typeof v === 'boolean') return v;
+  errs.push(`${path}: expected a boolean, got ${typeName(v)}`);
+  return undefined;
+}
+
+function strArray(v, path, errs, { minItems = 0, item = str } = {}) {
+  if (!Array.isArray(v)) {
+    errs.push(`${path}: expected an array, got ${typeName(v)}`);
+    return undefined;
+  }
+  if (v.length < minItems) errs.push(`${path}: must contain at least ${minItems} item(s)`);
+  return v.map((entry, i) => item(entry, `${path}[${i}]`, errs));
+}
+
+function port(v, path, errs) {
+  if (Number.isInteger(v) && v >= 1024 && v <= 65535) return v;
+  errs.push(`${path}: expected an integer from 1024 to 65535, got ${JSON.stringify(v)}`);
+  return undefined;
+}
+
+/** Path prefix relative to the repo root: no leading slash, no `..` segments, no `.` segments; `.` alone means the whole repo. */
+function relativePrefix(v, path, errs) {
+  if (str(v, path, errs) === undefined) return undefined;
+  if (v.startsWith('/')) errs.push(`${path}: must be relative to the repo root (no leading /)`);
+  const segments = v.split(/[\\/]/);
+  if (segments.includes('..')) errs.push(`${path}: must not contain .. segments`);
+  if (v !== '.' && segments.includes('.')) errs.push(`${path}: must not contain "." segments (use "." alone for the whole repo)`);
+  return v;
+}
+
+/** Checks that `v` is an object with only `allowed` keys; returns it or undefined. */
+function obj(v, path, errs, allowed) {
+  if (!isObject(v)) {
+    errs.push(`${path || '(root)'}: expected an object, got ${typeName(v)}`);
+    return undefined;
+  }
+  for (const key of Object.keys(v)) {
+    if (!allowed.includes(key)) errs.push(`${join_(path, key)}: unknown key (allowed: ${allowed.join(', ')})`);
+  }
+  return v;
+}
+
+function pattern(v, path, errs, allowed) {
+  if (str(v, path, errs) === undefined) return undefined;
+  for (const [, name] of v.matchAll(/\{([^{}]*)\}/g)) {
+    if (!allowed.includes(name)) {
+      errs.push(`${path}: unknown placeholder {${name}} (allowed: ${allowed.map((p) => `{${p}}`).join(', ')})`);
+    }
+  }
+  if (/[{}]/.test(v.replace(/\{[^{}]*\}/g, ''))) errs.push(`${path}: unbalanced or stray brace`);
+  if (!v.includes('{unit}')) errs.push(`${path}: must contain {unit}`);
+  return v;
+}
+
+/** Reads `key` of `o`: calls `check` when present, otherwise the default (or "required" error). */
+function field(o, key, path, errs, check, { fallback, required = false } = {}) {
+  if (!(key in o)) {
+    if (required) errs.push(`${join_(path, key)}: required`);
+    return fallback === undefined ? undefined : clone(fallback);
+  }
+  const value = check(o[key], join_(path, key), errs);
+  return value === undefined ? fallback && clone(fallback) : value;
+}
+
+function stringMap(v, path, errs) {
+  if (!obj(v, path, errs, Object.keys(v ?? {}))) return undefined;
+  const out = {};
+  for (const [k, val] of Object.entries(v)) {
+    if (k === '__proto__') {
+      errs.push(`${path}.${k}: reserved key`);
+      continue;
+    }
+    out[k] = str(val, `${path}.${k}`, errs);
+  }
+  return out;
+}
+
+function worktree(v, path, errs) {
+  if (!obj(v, path, errs, ['pathPattern', 'branchPattern'])) return undefined;
+  return {
+    pathPattern: field(v, 'pathPattern', path, errs, (x, p, e) => pattern(x, p, e, PATH_PLACEHOLDERS), { fallback: DEFAULTS.worktree.pathPattern }),
+    branchPattern: field(v, 'branchPattern', path, errs, (x, p, e) => pattern(x, p, e, BRANCH_PLACEHOLDERS), { fallback: DEFAULTS.worktree.branchPattern }),
+  };
+}
+
+function area(v, path, errs) {
+  const keys = ['name', 'dir', 'whenPaths', 'focused', 'full', 'lint', 'build', 'e2e'];
+  if (!obj(v, path, errs, keys)) return undefined;
+  const out = {
+    name: field(v, 'name', path, errs, str, { required: true }),
+    dir: field(v, 'dir', path, errs, relativePrefix, { required: true }),
+    whenPaths: field(v, 'whenPaths', path, errs, (x, p, e) => strArray(x, p, e, { minItems: 1, item: relativePrefix }), { required: true }),
+    focused: field(v, 'focused', path, errs, str, { required: true }),
+    full: field(v, 'full', path, errs, str, { required: true }),
+  };
+  for (const optional of ['lint', 'build', 'e2e']) {
+    if (optional in v) out[optional] = str(v[optional], join_(path, optional), errs);
+  }
+  return out;
+}
+
+function checks(v, path, errs) {
+  if (!Array.isArray(v)) {
+    errs.push(`${path}: expected an array, got ${typeName(v)}`);
+    return undefined;
+  }
+  if (v.length === 0) errs.push(`${path}: must contain at least one area`);
+  const seen = new Set();
+  return v.map((item, i) => {
+    const result = area(item, `${path}[${i}]`, errs);
+    if (result?.name !== undefined) {
+      if (seen.has(result.name)) errs.push(`${path}[${i}].name: duplicate area name "${result.name}"`);
+      seen.add(result.name);
+    }
+    return result;
+  });
+}
+
+function models(v, path, errs) {
+  if (!obj(v, path, errs, ['planning', 'orchestration', 'implementers'])) return undefined;
+  const impl = (x, p, e) => {
+    if (!obj(x, p, e, ['default', 'rules'])) return undefined;
+    return {
+      default: field(x, 'default', p, e, str, { fallback: DEFAULTS.models.implementers.default }),
+      rules: field(x, 'rules', p, e, stringMap, { fallback: DEFAULTS.models.implementers.rules }),
+    };
+  };
+  return {
+    planning: field(v, 'planning', path, errs, str, { fallback: DEFAULTS.models.planning }),
+    orchestration: field(v, 'orchestration', path, errs, str, { fallback: DEFAULTS.models.orchestration }),
+    implementers: field(v, 'implementers', path, errs, impl, { fallback: DEFAULTS.models.implementers }),
+  };
+}
+
+function tracker(v, path, errs) {
+  if (!obj(v, path, errs, ['kind'])) return undefined;
+  const kind = field(v, 'kind', path, errs, (x, p, e) => {
+    if (TRACKER_KINDS.includes(x)) return x;
+    e.push(`${p}: must be ${TRACKER_KINDS.map((k) => `"${k}"`).join(' or ')}, got ${JSON.stringify(x)}`);
+    return undefined;
+  }, { fallback: DEFAULTS.tracker.kind });
+  return { kind };
+}
+
+function codeMap(v, path, errs) {
+  if (!obj(v, path, errs, ['path'])) return undefined;
+  return { path: field(v, 'path', path, errs, relativePrefix, { required: true }) };
+}
+
+function uiSkill(v, path, errs) {
+  if (!obj(v, path, errs, ['name', 'appliesTo'])) return undefined;
+  return {
+    name: field(v, 'name', path, errs, str, { required: true }),
+    appliesTo: field(v, 'appliesTo', path, errs, (x, p, e) => strArray(x, p, e, { minItems: 1, item: relativePrefix }), { required: true }),
+  };
+}
+
+function findings(v, path, errs) {
+  if (!obj(v, path, errs, ['epicTitles'])) return undefined;
+  const titles = field(v, 'epicTitles', path, errs, stringMap);
+  // User-given titles override the defaults per category; other categories keep their default.
+  return { epicTitles: { ...clone(DEFAULTS.findings.epicTitles), ...(titles ?? {}) } };
+}
+
+function attribution(v, path, errs) {
+  if (!obj(v, path, errs, ['allowAiTrailer'])) return undefined;
+  return {
+    allowAiTrailer: field(v, 'allowAiTrailer', path, errs, bool, { fallback: DEFAULTS.attribution.allowAiTrailer }),
+  };
+}
+
+function tokensFile(v, path, errs) {
+  if (relativePrefix(v, path, errs) === undefined) return undefined;
+  if (v.includes('\\')) errs.push(`${path}: must not contain a backslash`);
+  if (!v.endsWith('.css')) errs.push(`${path}: must end in .css`);
+  return v;
+}
+
+function dashboard(v, path, errs) {
+  if (!obj(v, path, errs, ['enabled', 'port', 'tokensFile'])) return undefined;
+  const out = {
+    enabled: field(v, 'enabled', path, errs, bool, { fallback: DEFAULTS.dashboard.enabled }),
+    port: field(v, 'port', path, errs, port, { fallback: DEFAULTS.dashboard.port }),
+  };
+  if ('tokensFile' in v) out.tokensFile = tokensFile(v.tokensFile, join_(path, 'tokensFile'), errs);
+  return out;
+}
+
+const TOP_LEVEL = ['baseBranch', 'worktree', 'checks', 'models', 'tracker', 'codeMap', 'uiSkill', 'findings', 'attribution', 'dashboard'];
+
+/**
+ * Validates a parsed wavework config and fills defaults. Pure: does not touch the file system.
+ * Throws one Error listing every problem as `<json.path>: <reason>`.
+ *
+ * @param {unknown} raw parsed JSON
+ * @returns {object} the config with defaults filled in
+ */
+export function validateConfig(raw) {
+  return validate(raw, undefined);
+}
+
+/** Shared by validateConfig and loadConfig; `file` only decorates the error message. */
+function validate(raw, file) {
+  const errs = [];
+  if (!obj(raw, '', errs, TOP_LEVEL)) throw configError(errs, file);
+
+  const config = {
+    baseBranch: field(raw, 'baseBranch', '', errs, str, { required: true }),
+    worktree: field(raw, 'worktree', '', errs, worktree, { fallback: DEFAULTS.worktree }),
+    checks: field(raw, 'checks', '', errs, checks, { required: true }),
+    models: field(raw, 'models', '', errs, models, { fallback: DEFAULTS.models }),
+    tracker: field(raw, 'tracker', '', errs, tracker, { fallback: DEFAULTS.tracker }),
+    findings: field(raw, 'findings', '', errs, findings, { fallback: { epicTitles: DEFAULTS.findings.epicTitles } }),
+    attribution: field(raw, 'attribution', '', errs, attribution, { fallback: DEFAULTS.attribution }),
+    dashboard: field(raw, 'dashboard', '', errs, dashboard, { fallback: DEFAULTS.dashboard }),
+  };
+  for (const [key, check] of [['codeMap', codeMap], ['uiSkill', uiSkill]]) {
+    if (key in raw) config[key] = check(raw[key], key, errs);
+  }
+
+  if (errs.length > 0) throw configError(errs, file);
+  return config;
+}
+
+function configError(errs, file) {
+  const where = file ? ` in ${file}` : '';
+  const noun = errs.length === 1 ? 'problem' : 'problems';
+  return new Error(`invalid wavework config${where} (${errs.length} ${noun}):\n${errs.map((e) => `  - ${e}`).join('\n')}`);
+}
+
+/**
+ * Loads and validates `<repoRoot>/.claude/wavework.json`.
+ *
+ * @param {string} repoRoot
+ * @returns {object} validated config with defaults
+ */
+export function loadConfig(repoRoot) {
+  const file = join(repoRoot, CONFIG_PATH);
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new Error(`wavework config not found: ${file}`);
+    throw new Error(`cannot read wavework config ${file}: ${e.message}`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`wavework config is not valid JSON: ${file}: ${e.message}`);
+  }
+  return validate(raw, file);
+}

package/src/context.mjs

@@ -0,0 +1,133 @@
+/**
+ * Turns a validated wavework config (src/config.mjs) into the variables the skill templates use
+ * (src/render.mjs). Repeated structures (check areas, model rules, findings epics) are computed here
+ * as Markdown, so the template engine needs no loops.
+ */
+
+const FINDING_CLASSES = {
+  security: { kind: 'Real', typical: 'auth, permission, token, egress, path, subprocess, secret handling, missing re-authorization' },
+  bugs: { kind: 'Real', typical: 'wrong behaviour, data loss, races, broken UX flows' },
+  tests: { kind: 'Quality', typical: 'flaky tests, missing malicious-case or edge tests, CI gaps' },
+  quality: { kind: 'Quality', typical: 'duplication, dead code, naming, design-system gaps, stale docs' },
+};
+const NUMBER_WORDS = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten'];
+
+const code = (s) => `\`${s}\``;
+const orList = (items) => items.map(code).join(' or ');
+const fill = (pattern, values) => pattern.replace(/\{(\w+)\}/g, (_, key) => values[key]);
+
+function worktreeExpression(pattern, repoName) {
+  const values = { repo: repoName ?? '$(basename "$MAIN")', unit: '<unit-id>' };
+  // `../x` is a sibling of the main checkout; anything else is anchored at the main checkout itself.
+  return pattern.startsWith('../')
+    ? `$(dirname "$MAIN")/${fill(pattern.slice(3), values)}`
+    : `$MAIN/${fill(pattern, values)}`;
+}
+
+function areaSection(area) {
+  const lines = [
+    `## ${area.name}: files under ${area.whenPaths.map(code).join(', ')}`,
+    '',
+    `- **Focused:** ${code(area.focused)}`,
+    `- **Full:** ${code(area.full)}`,
+  ];
+  if (area.lint) lines.push(`- **Lint:** ${code(area.lint)}`);
+  if (area.build) lines.push(`- **Build:** ${code(area.build)}`);
+  if (area.e2e) lines.push(`- **E2E:** ${code(area.e2e)}`);
+  return lines.join('\n');
+}
+
+function findingsRows(epicTitles) {
+  return Object.entries(epicTitles)
+    .map(([slug, title]) => {
+      const { kind, typical } = FINDING_CLASSES[slug] ?? { kind: 'Quality', typical: '' };
+      return `| ${kind} | ${title.replace(/^Findings:\s*/, '')} | ${code(slug)} | ${typical} |`;
+    })
+    .join('\n');
+}
+
+/**
+ * Implementer models in agent order: the default first, then the other rule keys. The default is included
+ * even without a rule of its own (rule is then null).
+ *
+ * @param {object} config validated config
+ * @returns {{model: string, rule: string|null, isDefault: boolean}[]}
+ */
+export function implementerAgents(config) {
+  const { default: fallback, rules } = config.models.implementers;
+  return [fallback, ...Object.keys(rules).filter((m) => m !== fallback)].map((model) => ({
+    model,
+    rule: Object.hasOwn(rules, model) ? rules[model] : null,
+    isDefault: model === fallback,
+  }));
+}
+
+const AREA_KINDS = [['maven', /\bmvnw?\b/], ['vitest', /\bvitest\b/]];
+
+/**
+ * One line per check area for the `AREAS` table of scripts/red-green-check.sh: `'name|kind|dir'`. The kind
+ * (maven, vitest) is guessed from the area's focused command; anything else is `unsupported` and the script
+ * prints `SKIP <name>: unsupported` for it.
+ */
+function redGreenAreas(checks) {
+  return checks.map((a) => {
+    for (const field of [a.name, a.dir]) {
+      if (/[|'\n]/.test(field)) throw new Error(`area "${a.name}": name and dir must not contain "|", "'" or newlines (red-green-check.sh area table)`);
+    }
+    const kind = AREA_KINDS.find(([, re]) => re.test(a.focused))?.[0] ?? 'unsupported';
+    return `'${a.name}|${kind}|${a.dir.replace(/\/+$/, '') || '.'}'`;
+  }).join('\n');
+}
+
+/**
+ * @param {object} config validated config (see validateConfig)
+ * @param {object} [options]
+ * @param {string} [options.repoName] repository directory name for the worktree path; the skill asks the shell when absent
+ * @returns {object} template variables
+ */
+export function buildContext(config, options = {}) {
+  const { repoName } = options;
+  const { worktree, models, checks } = config;
+  const rules = models.implementers.rules;
+  const labels = Object.keys(rules);
+  if (!labels.includes(models.implementers.default)) labels.push(models.implementers.default);
+  const agents = implementerAgents(config).map((a) => a.model);
+  const branch = (values) => fill(worktree.branchPattern, values);
+  const withE2e = checks.filter((a) => a.e2e);
+  const titles = config.findings.epicTitles;
+  const count = Object.keys(titles).length;
+
+  return {
+    baseBranch: config.baseBranch,
+    repoName: repoName ?? '',
+    worktreeExpr: worktreeExpression(worktree.pathPattern, repoName),
+    worktreeExample: fill(worktree.pathPattern, { repo: repoName ?? 'repo', unit: 'shipr-cxk' }),
+    branchExpr: branch({ prefix: '<prefix>', unit: '<unit-id>', slug: '<slug>' }),
+    epicBranch: branch({ prefix: 'epic', unit: '<epic-id>', slug: '<slug>' }),
+    branchGlob: branch({ prefix: '<prefix>', unit: '<unit-id>', slug: '*' }),
+    taskBranchExample: branch({ prefix: 'task', unit: 'shipr-hae', slug: 'event-worker-interrupt' }),
+    models,
+    orchestrationModelName: models.orchestration.charAt(0).toUpperCase() + models.orchestration.slice(1),
+    modelLabelsOr: orList(labels.map((l) => `model:${l}`)),
+    modelLabelPipe: labels.join('|'),
+    implementerModelPipe: agents.join('|'),
+    implementerAgentsPlain: agents.map((a) => `implementer-${a}`).join(' and '),
+    implementerAgentsOr: orList(agents.map((a) => `implementer-${a}`)),
+    modelRules: Object.entries(rules).map(([model, text]) => `- ${code(model)}: ${text}`).join('\n'),
+    areaNamesPipe: checks.map((a) => a.name).join('|'),
+    checksSection: checks.map(areaSection).join('\n\n'),
+    depsSection: checks.map((a) => `- ${code(a.name)} (${code(a.dir)}, only if it exists)`).join('\n'),
+    fullChecksList: checks.map((a) => `- ${code(a.name)}: ${code(a.full)}`).join('\n'),
+    hasLint: checks.some((a) => a.lint),
+    hasE2e: withE2e.length > 0,
+    e2eList: withE2e.map((a) => `- ${code(a.name)}: ${code(a.e2e)}`).join('\n'),
+    codeMap: config.codeMap ?? false,
+    uiSkill: config.uiSkill ?? false,
+    uiPaths: config.uiSkill ? config.uiSkill.appliesTo.map(code).join(', ') : '',
+    findingsEpics: findingsRows(titles),
+    findingsEpicCount: NUMBER_WORDS[count] ?? String(count),
+    redGreenAreas: redGreenAreas(checks),
+    noAttribution: !config.attribution.allowAiTrailer,
+    dashboard: config.dashboard.enabled,
+  };
+}

package/src/render.mjs

@@ -0,0 +1,148 @@
+/**
+ * Minimal template engine for the skill templates. No dependencies, no escaping (output is Markdown).
+ *
+ * Syntax:
+ *   {{path.to.var}}                 value of a context variable (string or number)
+ *   {{#if key}} ... {{/if}}         body when truthy: true, non-empty string, non-empty array, any object
+ *   {{#if key}} ... {{else}} ... {{/if}}
+ *
+ * Rules:
+ *   - Unknown variables (also in `#if`) are errors, so typos never render as empty text.
+ *   - Blocks must balance, also in branches that are not taken.
+ *   - A block tag alone on its line removes the whole line, so blocks leave no blank lines.
+ *   - A variable alone on an indented line indents every line of a multi-line value the same way.
+ *   - There is no escape for a literal `{{` or `}}`; a stray one is an error.
+ */
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const TAG = /\{\{([^{}]*)\}\}/g;
+
+function fail(name, line, message) {
+  return new Error(`template "${name}", line ${line}: ${message}`);
+}
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+/** Splits the template into text and tag tokens; block tags alone on a line swallow the whole line. */
+function tokenize(text, name) {
+  const tokens = [];
+  let pos = 0;
+  const pushText = (end) => {
+    const chunk = text.slice(pos, end);
+    if (/\{\{|\}\}/.test(chunk)) {
+      const at = pos + chunk.search(/\{\{|\}\}/);
+      throw fail(name, lineOf(text, at), `stray "${text.slice(at, at + 2)}" (no escape exists for literal braces)`);
+    }
+    if (chunk) tokens.push({ type: 'text', value: chunk });
+  };
+  for (const match of text.matchAll(TAG)) {
+    const inner = match[1].trim();
+    const line = lineOf(text, match.index);
+    let start = match.index;
+    let end = match.index + match[0].length;
+    let token;
+    if (inner === '') throw fail(name, line, 'empty tag');
+    if (inner.startsWith('#if ')) {
+      const key = inner.slice(4).trim();
+      if (!NAME.test(key)) throw fail(name, line, `invalid tag "{{${inner}}}"`);
+      token = { type: 'if', key, line };
+    } else if (inner === 'else' || inner === '/if') {
+      token = { type: inner, line };
+    } else if (NAME.test(inner)) {
+      token = { type: 'var', key: inner, line };
+    } else {
+      throw fail(name, line, `invalid tag "{{${inner}}}"`);
+    }
+    if (token.type !== 'var') {
+      const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+      const nl = text.indexOf('\n', end);
+      const lineEnd = nl === -1 ? text.length : nl;
+      if (/^[ \t]*$/.test(text.slice(lineStart, start)) && /^[ \t]*$/.test(text.slice(end, lineEnd))) {
+        start = lineStart;
+        end = nl === -1 ? text.length : nl + 1;
+      }
+    }
+    pushText(start);
+    tokens.push(token);
+    pos = end;
+  }
+  pushText(text.length);
+  return tokens;
+}
+
+/** Builds a tree of { type: 'text' | 'var' | 'if', ... } and checks that blocks balance. */
+function parse(tokens, name) {
+  const root = { children: [] };
+  const stack = [{ node: root, list: root.children }];
+  for (const token of tokens) {
+    const top = stack[stack.length - 1];
+    if (token.type === 'text' || token.type === 'var') {
+      top.list.push(token);
+    } else if (token.type === 'if') {
+      const node = { type: 'if', key: token.key, line: token.line, then: [], otherwise: null };
+      top.list.push(node);
+      stack.push({ node, list: node.then });
+    } else if (token.type === 'else') {
+      if (stack.length === 1) throw fail(name, token.line, '{{else}} outside of an {{#if}} block');
+      if (top.node.otherwise !== null) throw fail(name, token.line, 'more than one {{else}} in one {{#if}} block');
+      top.node.otherwise = [];
+      top.list = top.node.otherwise;
+    } else {
+      if (stack.length === 1) throw fail(name, token.line, '{{/if}} without a matching {{#if}}');
+      stack.pop();
+    }
+  }
+  if (stack.length > 1) {
+    const open = stack[stack.length - 1].node;
+    throw fail(name, open.line, `unclosed block {{#if ${open.key}}}`);
+  }
+  return root.children;
+}
+
+function lookup(context, key, name, line) {
+  let value = context;
+  for (const part of key.split('.')) {
+    if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part)) {
+      throw fail(name, line, `unknown variable "${key}"`);
+    }
+    value = value[part];
+  }
+  return value;
+}
+
+function truthy(value) {
+  if (Array.isArray(value) || typeof value === 'string') return value.length > 0;
+  return Boolean(value);
+}
+
+/**
+ * @param {string} template
+ * @param {object} context variables; see src/context.mjs
+ * @param {string} [name] template name for error messages
+ * @returns {string}
+ */
+export function render(template, context, name = '<template>') {
+  const tree = parse(tokenize(template, name), name);
+  let out = '';
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      if (node.type === 'text') {
+        out += node.value;
+      } else if (node.type === 'var') {
+        const value = lookup(context, node.key, name, node.line);
+        if (typeof value !== 'string' && typeof value !== 'number') {
+          throw fail(name, node.line, `variable "${node.key}" is not a string or number`);
+        }
+        const tail = out.slice(out.lastIndexOf('\n') + 1);
+        const indent = /^[ \t]+$/.test(tail) ? tail : '';
+        out += String(value).split('\n').join(`\n${indent}`);
+      } else if (truthy(lookup(context, node.key, name, node.line))) {
+        walk(node.then);
+      } else if (node.otherwise !== null) {
+        walk(node.otherwise);
+      }
+    }
+  };
+  walk(tree);
+  return out;
+}