@c9up/ream 0.2.25 → 0.2.27

package/src/profiler/render.ts

@@ -0,0 +1,173 @@
+/**
+ * The profiler's own pages, and the bar injected into yours.
+ *
+ * Plain HTML and one inline stylesheet. A dev tool that needed a build step,
+ * or pulled a framework into the page it is inspecting, would be a worse
+ * neighbour than the problem it reports — and the bar lives in a shadow root
+ * for the same reason: your stylesheet must not reach it, and it must not
+ * reach yours.
+ *
+ * EVERY value that came from a request is escaped. A profiler renders the
+ * URL someone asked for, the SQL a query ran and the message an error carried
+ * — all attacker-reachable in exactly the case you most want to look at, and a
+ * tool that turned a crafted URL into script in your own browser would be a
+ * hole with a friendly face.
+ */
+
+import type { Profile, ProfileSummary } from './types.js'
+
+/** `<`, `&` and the quotes. Everything below goes through it. */
+export function escapeHtml(value: unknown): string {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+}
+
+const STYLE = `
+  :root { color-scheme: dark }
+  body { margin: 0; background: #14161a; color: #e6e6e6;
+         font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace }
+  a { color: #6cb6ff; text-decoration: none }
+  a:hover { text-decoration: underline }
+  header { padding: 16px 20px; border-bottom: 1px solid #262a31 }
+  h1 { margin: 0; font-size: 15px; font-weight: 600 }
+  .meta { color: #8b949e; margin-top: 4px }
+  main { padding: 20px }
+  section { margin-bottom: 28px }
+  h2 { font-size: 13px; text-transform: uppercase; letter-spacing: .08em;
+       color: #8b949e; margin: 0 0 10px }
+  table { width: 100%; border-collapse: collapse }
+  td, th { text-align: left; padding: 6px 10px; border-bottom: 1px solid #21252c;
+           vertical-align: top }
+  th { color: #8b949e; font-weight: 500 }
+  .num { text-align: right; white-space: nowrap; color: #8b949e }
+  .sql { white-space: pre-wrap; word-break: break-word }
+  .slow { color: #f0883e }
+  .bad { color: #ff7b72 }
+  pre { white-space: pre-wrap; word-break: break-word; margin: 0; color: #c9d1d9 }
+  .pill { display: inline-block; padding: 1px 8px; border-radius: 999px;
+          background: #21262d; color: #8b949e; margin-right: 6px }
+`
+
+/** A whole page, so the profiler needs nothing served alongside it. */
+function page(title: string, body: string): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<title>${escapeHtml(title)}</title><style>${STYLE}</style></head><body>${body}</body></html>`
+}
+
+/** The history: what a developer lands on with no token in hand. */
+export function renderProfileList(profiles: readonly ProfileSummary[], missing?: string): string {
+  const warning =
+    missing === undefined
+      ? ''
+      : `<p class="bad">No profile for <code>${escapeHtml(missing)}</code> — it may have aged out.</p>`
+
+  const rows = profiles
+    .map(
+      (profile) => `<tr>
+      <td><a href="/__ream/profiler/${escapeHtml(profile.token)}">${escapeHtml(profile.token)}</a></td>
+      <td>${escapeHtml(profile.method)}</td>
+      <td class="sql">${escapeHtml(profile.url)}</td>
+      <td class="${profile.status >= 500 ? 'bad' : ''}">${escapeHtml(profile.status)}</td>
+      <td class="num">${escapeHtml(profile.duration.toFixed(1))} ms</td>
+      <td>${Object.values(profile.badges)
+        .map((badge) => `<span class="pill">${escapeHtml(badge)}</span>`)
+        .join('')}</td>
+    </tr>`,
+    )
+    .join('')
+
+  return page(
+    'Profiler',
+    `<header><h1>Profiler</h1><div class="meta">${profiles.length} request${
+      profiles.length === 1 ? '' : 's'
+    } kept</div></header><main>${warning}
+     <table><tr><th>Token</th><th>Method</th><th>URL</th><th>Status</th>
+     <th class="num">Time</th><th>Collected</th></tr>${rows}</table></main>`,
+  )
+}
+
+/** One request, every panel. */
+export function renderProfilePage(profile: Profile, badges: Record<string, string>): string {
+  const sections: string[] = []
+
+  const exception = profile.data.exception
+  if (exception !== undefined && typeof exception.message === 'string') {
+    sections.push(`<section><h2 class="bad">Exception</h2>
+      <p class="bad">${escapeHtml(exception.name ?? 'Error')}: ${escapeHtml(exception.message)}</p>
+      ${typeof exception.stack === 'string' ? `<pre>${escapeHtml(exception.stack)}</pre>` : ''}
+    </section>`)
+  }
+
+  sections.push(renderQueries(profile))
+
+  for (const [name, data] of Object.entries(profile.data)) {
+    if (name === 'database' || name === 'exception') continue
+    if (Object.keys(data).length === 0) continue
+    sections.push(`<section><h2>${escapeHtml(name)}</h2>
+      <pre>${escapeHtml(JSON.stringify(data, null, 2))}</pre></section>`)
+  }
+
+  return page(
+    `${profile.method} ${profile.url}`,
+    `<header>
+       <h1>${escapeHtml(profile.method)} ${escapeHtml(profile.url)}</h1>
+       <div class="meta">
+         ${escapeHtml(profile.status)} · ${escapeHtml(profile.duration.toFixed(1))} ms ·
+         ${escapeHtml(new Date(profile.time).toISOString())} ·
+         <a href="/__ream/profiler">all requests</a>
+       </div>
+       <div class="meta">${Object.values(badges)
+         .map((badge) => `<span class="pill">${escapeHtml(badge)}</span>`)
+         .join('')}</div>
+     </header><main>${sections.join('')}</main>`,
+  )
+}
+
+/** The panel the whole thing exists for. */
+function renderQueries(profile: Profile): string {
+  const database = profile.data.database
+  if (database === undefined) return ''
+  const queries = Array.isArray(database.queries) ? database.queries : []
+  const total = typeof database.total === 'number' ? database.total : 0
+
+  if (total === 0) return '<section><h2>Database</h2><p class="meta">No query.</p></section>'
+
+  const rows = queries
+    .map((entry) => {
+      const query = asRecord(entry)
+      const duration = typeof query.duration === 'number' ? query.duration : 0
+      const bindings = Array.isArray(query.bindings) ? query.bindings : []
+      return `<tr>
+        <td class="num ${duration >= 50 ? 'slow' : ''}">${escapeHtml(duration.toFixed(2))} ms</td>
+        <td class="sql">${escapeHtml(query.sql)}${
+          bindings.length === 0
+            ? ''
+            : `<div class="meta">${escapeHtml(JSON.stringify(bindings))}</div>`
+        }${
+          typeof query.error === 'string' ? `<div class="bad">${escapeHtml(query.error)}</div>` : ''
+        }</td>
+        <td class="meta">${escapeHtml(query.model ?? '')}${
+          query.inTransaction === true ? ' <span class="pill">tx</span>' : ''
+        }</td>
+      </tr>`
+    })
+    .join('')
+
+  const capped =
+    database.capped === true
+      ? `<p class="meta">Listing stopped at ${queries.length}; ${escapeHtml(total)} ran.</p>`
+      : ''
+
+  return `<section><h2>Database</h2>${capped}
+    <table><tr><th class="num">Time</th><th>Query</th><th>Model</th></tr>${rows}</table></section>`
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+    ? Object.fromEntries(Object.entries(value))
+    : {}
+}

package/src/profiler/toolbar.ts

@@ -0,0 +1,106 @@
+/**
+ * The bar at the bottom of the page.
+ *
+ * It carries its own token inline rather than reading `X-Debug-Token` off the
+ * response: a script in a page cannot see the headers of the navigation that
+ * delivered it. Symfony injects the token for the same reason.
+ *
+ * Everything lives in a shadow root — your stylesheet must not reach the bar,
+ * and the bar must not reach your page. It fetches its numbers once, on load,
+ * and then does nothing: a dev tool that polls is a dev tool that shows up in
+ * its own history.
+ *
+ * A string rather than a stringified function, as the hot-reload script is:
+ * this package compiles without the DOM library, deliberately — it is a server
+ * — so browser code here is text, and its only inputs are escaped below.
+ *
+ * It styles its nodes through the CSSOM — `node.style.cssText` — rather than
+ * with a `<style>` element. Under a CSP with `style-src 'self'` (or only a
+ * `default-src`, which is the common case) a stylesheet inserted at runtime is
+ * inline style and is dropped, with no error anywhere: the bar renders as a
+ * stack of grey text and nothing says why. Setting properties on an element is
+ * not inline style and is never blocked, which is also how the host below has
+ * always been positioned.
+ */
+
+import { PROFILER_PATH } from './Profiler.js'
+
+/**
+ * The `<script>` to append to an HTML response.
+ *
+ * `token` is generated by the profiler (hex) and `nonce` by the response, so
+ * neither is user input; both are still put through `JSON.stringify` rather
+ * than interpolated raw, because "cannot contain a quote" is an invariant that
+ * holds until someone changes how one of them is made.
+ */
+export function toolbarScript(token: string, nonce?: string): string {
+  const attribute = nonce === undefined ? '' : ` nonce="${nonce.replace(/"/g, '&quot;')}"`
+  const config = JSON.stringify({ token, path: PROFILER_PATH })
+  return `<script${attribute}>(${BAR})(${config})</script>`
+}
+
+/**
+ * The bar, as it runs in the browser.
+ *
+ * Kept on one indented block so what ships is readable in a page's source —
+ * someone will open the inspector and find this, and a minified blob would
+ * tell them nothing about where it came from.
+ */
+const BAR = `function(c){
+  var host=document.createElement('div');
+  host.style.cssText='position:fixed;left:0;right:0;bottom:0;z-index:2147483000';
+  var root=host.attachShadow({mode:'closed'});
+  document.body.appendChild(host);
+  var bar=document.createElement('div');
+  bar.style.cssText='display:flex;align-items:stretch;background:#14161a;color:#e6e6e6;'
+    +'font:12px/1 ui-monospace,Menlo,monospace;border-top:1px solid #262a31;'
+    +'box-shadow:0 -2px 8px rgba(0,0,0,.4)';
+  root.appendChild(bar);
+  var page=c.path+'/'+c.token;
+  var COLOR={bad:'#ff7b72',warn:'#f0883e',ok:'#7ee787'};
+  function cell(label,value,tone,plain){
+    var node=document.createElement('div');
+    node.style.cssText='padding:7px 11px;white-space:nowrap;'
+      +(plain?'flex:1;overflow:hidden;text-overflow:ellipsis;cursor:default'
+             :'border-right:1px solid #21252c;cursor:pointer');
+    if(label){
+      var tag=document.createElement('span');
+      tag.style.cssText='color:#8b949e;margin-right:6px';
+      tag.textContent=label;
+      node.appendChild(tag);
+    }
+    var text=document.createElement('span');
+    if(tone){text.style.color=COLOR[tone];}
+    text.textContent=value;
+    node.appendChild(text);
+    if(!plain){
+      node.addEventListener('mouseenter',function(){node.style.background='#1b1f25'});
+      node.addEventListener('mouseleave',function(){node.style.background=''});
+      node.addEventListener('click',function(){window.open(page,'_blank')});
+    }
+    bar.appendChild(node);
+  }
+  function panel(data,name){
+    var value=data&&data[name];
+    return (value&&typeof value==='object')?value:null;
+  }
+  fetch(page+'.json',{headers:{accept:'application/json'}})
+    .then(function(r){return r.ok?r.json():null})
+    .then(function(p){
+      if(!p){host.remove();return}
+      var status=Number(p.status||0);
+      cell('',String(status),status>=500?'bad':status>=400?'warn':'ok');
+      cell('time',Number(p.duration||0).toFixed(1)+' ms');
+      var db=panel(p.data,'database');
+      if(db){
+        var total=Number(db.total||0);
+        cell('db',total+' \u00b7 '+Number(db.duration||0).toFixed(1)+' ms',total>=50?'warn':'');
+      }
+      var mem=panel(p.data,'memory');
+      if(mem){cell('mem',Number(mem.usedMb||0).toFixed(1)+' MB');}
+      var err=panel(p.data,'exception');
+      if(err&&typeof err.message==='string'){cell('',err.message,'bad');}
+      cell('',String(p.url||''),'',true);
+    })
+    .catch(function(){host.remove()});
+}`

package/src/profiler/types.ts

@@ -0,0 +1,75 @@
+/**
+ * What the profiler keeps about one request.
+ *
+ * Shaped after Symfony's profiler rather than Laravel's debugbar, which is a
+ * decision about where the data lives: a token per request, an endpoint that
+ * serves it, and a history. Inlining it in the page is simpler until the
+ * request you need to look at was a POST that redirected — and then the data
+ * is gone, which is exactly when you wanted it.
+ */
+
+/** One collector's contribution to a profile. Plain data: it crosses a wire. */
+export type CollectedData = Record<string, unknown>
+
+/**
+ * Everything kept about one request.
+ *
+ * `token` identifies it. It travels back on `X-Debug-Token`, so a client — the
+ * toolbar, curl, a test — can ask for the profile of a request it just made.
+ */
+export interface Profile {
+  token: string
+  /** When the request arrived, epoch milliseconds. */
+  time: number
+  method: string
+  url: string
+  status: number
+  /** Wall-clock milliseconds, first middleware to serialised response. */
+  duration: number
+  /** Keyed by collector name. */
+  data: Record<string, CollectedData>
+}
+
+/** A profile without its data — what a listing shows. */
+export type ProfileSummary = Omit<Profile, 'data'> & {
+  /** The headline each collector wants on the bar: `{ database: '12 queries' }`. */
+  badges: Record<string, string>
+}
+
+/**
+ * What a collector is handed while a request runs.
+ *
+ * Deliberately not the HttpContext: a collector observes, and handing it the
+ * context would let it answer the request. What it needs is a place to put
+ * what it saw and the ability to know when the request ends.
+ */
+export interface CollectionScope {
+  token: string
+  /** Called by the framework when the request is done. */
+  readonly startedAt: number
+}
+
+/**
+ * A source of data about a request.
+ *
+ * `start` runs when the request begins and answers a bag the collector will
+ * fill; `finish` turns that bag into what is stored. Two methods rather than
+ * one, because the interesting collectors — queries, logs, events — are fed by
+ * things happening DURING the request, not by looking at it afterwards.
+ */
+export interface ProfilerCollector<Bag = unknown> {
+  /** Unique. It keys the data and names the panel. */
+  readonly name: string
+  /** Shown on the bar, or nothing when there is nothing worth a badge. */
+  badge?: (data: CollectedData) => string | undefined
+  start(scope: CollectionScope): Bag
+  finish(bag: Bag, scope: CollectionScope): CollectedData
+}
+
+/** Where profiles are kept. Bounded: a dev session is not an archive. */
+export interface ProfileStore {
+  save(profile: Profile): void
+  find(token: string): Profile | undefined
+  recent(limit?: number): ProfileSummary[]
+  clear(): void
+}

package/src/router/Router.ts

@@ -1361,6 +1361,22 @@ export class Router extends Macroable {
     return manifest
   }
 
+  /**
+   * Every NAMED route with its path pattern AND the HTTP methods it answers,
+   * e.g. `{ 'users.update': { path: '/users/:id', methods: ['PUT'] } }` — what
+   * a client needs to follow a route by name and pick its verb, the way
+   * AdonisJS's Tuyau registry gives `route` + `methods`. `namedManifest()`
+   * stays the lighter name → path map.
+   */
+  namedRoutes(): Record<string, { path: string; methods: string[] }> {
+    if (this.#indexDirty) this.#buildIndex()
+    const routes: Record<string, { path: string; methods: string[] }> = {}
+    for (const [name, route] of this.#nameIndex) {
+      routes[name] = { path: route.path, methods: [route.method] }
+    }
+    return routes
+  }
+
   /**
    * Generate a TypeScript source string typing every named route and its
    * params (AdonisJS `generateTypes`) — a `RouteName` union plus a

package/src/stubs/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@c9up/ream/stubs` — the stub engine, and where this package keeps its own.
+ *
+ * Every Ream package exports a `stubsRoot` from this subpath: it is what
+ * `codemods.makeUsingStub(stubsRoot, 'make/controller.stub')` takes, and what
+ * `ream eject --pkg` reads to copy a template into the application.
+ */
+
+import * as path from 'node:path'
+
+export * from './template.js'
+
+/** `<package>/stubs` — resolved from this file, so it survives the build. */
+export const stubsRoot = path.join(import.meta.dirname, '..', '..', 'stubs')

package/src/stubs/template.ts

@@ -0,0 +1,262 @@
+/**
+ * The stub template engine.
+ *
+ * A port of the one upstream uses (tempura), grammar for grammar: comments,
+ * declared props, inline variables, conditionals, loops, custom blocks, and
+ * the two interpolation forms. A template is compiled into a JavaScript
+ * function once and then called — the same design, for the same reason: a
+ * tree-walking interpreter re-reads the template on every render, and a stub
+ * is rendered in a loop by the generators.
+ *
+ *     {{! a comment }}
+ *     {{#expect name, entity }}
+ *     {{#var plural = name + 's' }}
+ *     {{#if entity.isModel }}…{{#elif entity.isView }}…{{#else}}…{{/if}}
+ *     {{#each items as item, index }}…{{/each}}
+ *     {{ name }}      the value
+ *     {{{ name }}}    the value, unescaped
+ *
+ * NAMED DEVIATION — upstream escapes HTML in `{{ }}` and leaves `{{{ }}}`
+ * raw, because its templates are web pages. Ours are SOURCE FILES: escaping
+ * `"` into `"` there produces code that does not parse, and the mistake
+ * is silent. So `{{ }}` does not escape by default, `{{{ }}}` is accepted as
+ * the same thing (a stub written for upstream keeps working), and an `escape`
+ * option turns it back on for anyone templating markup.
+ *
+ * `new Function` compiles the result. That is how upstream does it too, and
+ * the trust boundary is the same: a stub ships inside a package whose
+ * `configure` hook is already executing.
+ */
+
+/** What a template may read. Scalars, lists and nested records. */
+export type StubValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | StubValue[]
+  | { [key: string]: StubValue }
+
+export type StubState = Record<string, StubValue>
+
+/** A custom block — `{{#myBlock key=value }}` calls it with those arguments. */
+export type StubBlock = (args: Record<string, StubValue>) => string
+
+export interface TemplateOptions {
+  /** Names the template may read even when the state does not carry them. */
+  props?: string[]
+  /** Custom `{{#name}}` blocks. */
+  blocks?: Record<string, StubBlock>
+  /** Applied to every `{{ }}`. Identity by default — see the header. */
+  escape?: (value: unknown) => string
+}
+
+/** Raised when a template cannot be read, naming what is wrong with it. */
+export class StubSyntaxError extends Error {
+  readonly code = 'E_REAM_STUB_SYNTAX'
+  constructor(message: string) {
+    super(message)
+    this.name = 'StubSyntaxError'
+  }
+}
+
+/** HTML escaping, for a stub that does template markup. */
+export function escapeHtml(value: unknown): string {
+  const text = value === null || value === undefined ? '' : String(value)
+  return text.replace(/[&"<>]/g, (char) => {
+    if (char === '&') return '&amp;'
+    if (char === '"') return '&quot;'
+    if (char === '<') return '&lt;'
+    return '&gt;'
+  })
+}
+
+/** The default: a source file wants its quotes and its angle brackets back. */
+function asIs(value: unknown): string {
+  return value === null || value === undefined ? '' : String(value)
+}
+
+const CURLY = /{{{?\s*([\s\S]*?)\s*}}}?/g
+const BLOCK = /^#\s*(\w[\w\d]*)\s*([\s\S]*)/
+const ARGS = /([a-zA-Z$_][^\s=]*)\s*=\s*((["`'])(?:(?=(\\?))\4.)*?\3|{[^}]*}|\[[^\]]*]|\S+)/g
+
+/**
+ * Compile a template into the body of a function.
+ *
+ * Kept separate from `compile` so a test can read what a template became —
+ * the generated source is the only place a subtle mistake shows itself.
+ */
+export function generate(input: string, options: TemplateOptions = {}): string {
+  const blocks = options.blocks ?? {}
+  const declared = new Set<string>(options.props ?? [])
+  const stack: string[] = []
+
+  let body = ''
+  let literal = ''
+  let last = 0
+  CURLY.lastIndex = 0
+
+  /** Flush the literal text collected since the last tag. */
+  const flush = (): void => {
+    if (literal.length > 0) {
+      body += `${body ? 'x+=' : '='}\`${literal}\`;`
+    } else if (body.length === 0) {
+      body = '="";'
+    }
+    literal = ''
+  }
+
+  let match: RegExpExecArray | null = CURLY.exec(input)
+  while (match !== null) {
+    literal += escapeForTemplate(input.slice(last, match.index))
+    last = match.index + match[0].length
+
+    const inner = (match[1] ?? '').trim()
+    const first = inner.charAt(0)
+
+    if (first === '!') {
+      // A comment. It leaves no trace in the output.
+    } else if (first === '#') {
+      flush()
+      const parsed = BLOCK.exec(inner)
+      if (parsed === null) {
+        throw new StubSyntaxError(`Unreadable block: {{${inner}}}`)
+      }
+      const action = parsed[1] ?? ''
+      const rest = (parsed[2] ?? '').trim()
+      body += openBlock(action, rest, stack, declared, blocks)
+    } else if (first === '/') {
+      const closing = inner.slice(1).trim()
+      const opened = stack.pop()
+      flush()
+      if (opened === undefined) {
+        throw new StubSyntaxError(`Closed "${closing}" with nothing open.`)
+      }
+      if (opened !== closing) {
+        throw new StubSyntaxError(`Expected to close "${opened}"; closed "${closing}" instead.`)
+      }
+      body += '}'
+    } else {
+      // Both forms interpolate the same way — see the header.
+      literal += `\${$$e(${inner})}`
+    }
+
+    match = CURLY.exec(input)
+  }
+
+  if (stack.length > 0) {
+    throw new StubSyntaxError(`Unterminated "${stack.pop()}" block.`)
+  }
+  if (last < input.length) {
+    literal += escapeForTemplate(input.slice(last))
+  }
+  flush()
+
+  const bindings = declared.size > 0 ? `{${[...declared].join()}}=$$s,x` : ' x'
+  return `var${bindings}${body}return x`
+}
+
+function openBlock(
+  action: string,
+  rest: string,
+  stack: string[],
+  declared: Set<string>,
+  blocks: Record<string, StubBlock>,
+): string {
+  if (action === 'expect') {
+    // Names the template reads. Declaring them is what lets an unknown one
+    // fail as `x is not defined` rather than as `undefined` in the output.
+    for (const key of rest.split(/[\n\r\s\t]*,[\n\r\s\t]*/g)) {
+      if (key !== '') declared.add(key)
+    }
+    return ''
+  }
+
+  if (action === 'var') {
+    const at = rest.indexOf('=')
+    if (at === -1) {
+      throw new StubSyntaxError(`{{#var}} needs an assignment: {{#var ${rest}}}`)
+    }
+    const name = rest.slice(0, at).trim()
+    const value = rest
+      .slice(at + 1)
+      .trim()
+      .replace(/;$/, '')
+    return `var ${name}=${value};`
+  }
+
+  if (action === 'each') {
+    stack.push(action)
+    const at = rest.indexOf(' as ')
+    if (at === -1) {
+      return `for(var i=0,$$a=${rest};i<$$a.length;i++){`
+    }
+    const list = rest.slice(0, at).trim()
+    const [item = 'item', index = 'i'] = rest
+      .slice(at + 4)
+      .trim()
+      .replace(/[()\s]/g, '')
+      .split(',')
+    return `for(var ${index}=0,${item},$$a=${list};${index}<$$a.length;${index}++){${item}=$$a[${index}];`
+  }
+
+  if (action === 'if') {
+    stack.push(action)
+    return `if(${rest}){`
+  }
+  if (action === 'elif') return `}else if(${rest}){`
+  if (action === 'else') return '}else{'
+
+  if (action in blocks) {
+    // `{{#note tone="warn" }}` — the arguments become one object.
+    const args: string[] = []
+    let found: RegExpExecArray | null = ARGS.exec(rest)
+    while (found !== null) {
+      args.push(`${found[1]}:${found[2]}`)
+      found = ARGS.exec(rest)
+    }
+    ARGS.lastIndex = 0
+    return `x+=$$b.${action}(${args.length > 0 ? `{${args.join()}}` : '{}'});`
+  }
+
+  throw new StubSyntaxError(
+    `Unknown "${action}" block. Known: expect, var, if, elif, else, each${
+      Object.keys(blocks).length > 0 ? `, ${Object.keys(blocks).join(', ')}` : ''
+    }.`,
+  )
+}
+
+/** Protect the literal text from the template literal it is about to live in. */
+function escapeForTemplate(text: string): string {
+  return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+}
+
+/** Compile a template into a render function. */
+export function compile(
+  input: string,
+  options: TemplateOptions = {},
+): (state: StubState) => string {
+  const source = generate(input, options)
+  let render: (escaper: (value: unknown) => string, blocks: unknown, state: StubState) => string
+  try {
+    // eslint-disable-next-line no-new-func -- the whole point of a compiler
+    render = new Function('$$e', '$$b', '$$s', source) as typeof render
+  } catch (error) {
+    throw new StubSyntaxError(
+      `This stub does not compile: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+  const escaper = options.escape ?? asIs
+  const blocks = options.blocks ?? {}
+  return (state: StubState) => render(escaper, blocks, state)
+}
+
+/** Compile and render in one go. */
+export function render(
+  input: string,
+  state: StubState = {},
+  options: TemplateOptions = {},
+): string {
+  return compile(input, { props: Object.keys(state), ...options })(state)
+}

package/stubs/make/command.stub

@@ -0,0 +1,29 @@
+---
+to: commands/{{ fileName }}.ts
+---
+import { BaseCommand, flags } from '@c9up/ream/console'
+import type { CommandOptions } from '@c9up/ream/console'
+
+export default class {{ className }} extends BaseCommand {
+  static commandName = '{{ name }}'
+  static description = 'TODO describe what this command does'
+
+  /**
+   * `startApp` boots providers and the container before `run()`. Off by
+   * default: a command that only touches the filesystem has no
+   * reason to open a database connection. Turn it on to reach `this.app`.
+   */
+  static options: CommandOptions = { startApp: false }
+
+  @flags.boolean({ description: 'Report what would happen without doing it' })
+  declare dryRun: boolean
+
+  async run(): Promise<void> {
+    if (this.dryRun) {
+      this.logger.info('Dry run — nothing was changed.')
+      return
+    }
+
+    this.logger.success('{{ name }} ran.')
+  }
+}