@erclx/canon 5.14.1 → 5.16.0

package/src/canvas/server.ts

@@ -0,0 +1,471 @@
+import { type FSWatcher, mkdirSync, watch } from 'node:fs'
+import {
+  type ElementAddress,
+  HASH_ATTRIBUTE,
+  TOKENS_ATTRIBUTE,
+} from '@/canvas/address'
+import {
+  type ContentRefused,
+  canvasDir,
+  contentHash,
+  listPages,
+  LOCK_SUFFIX,
+  moveFrame,
+  readSelection,
+  TEMP_SUFFIX,
+  writeSelection,
+} from '@/canvas/content'
+import { resolveFrameTokens, type TokenOptions } from '@/canvas/tokens'
+import { buildDesignCss } from '@/design/css'
+import {
+  bindFirstFree,
+  PORT_ATTEMPTS,
+  respond,
+  SERVE_HOST,
+  type ServeRefusal,
+} from '@/serve/static'
+
+/** Clear of `canon serve`'s default, so a lesson preview and the canvas both open. */
+export const CANVAS_PORT = 8790
+
+/** The URL prefix a frame and the files beside it are served under. */
+export const FRAMES_PREFIX = '/frames/'
+
+/**
+ * How long a burst of watch events for one file waits before it is sent. One
+ * editor save raises several, and each would otherwise reload the frame again.
+ */
+const SETTLE_MS = 40
+
+export interface CanvasStarted {
+  readonly ok: true
+  readonly root: string
+  readonly content: string
+  readonly host: string
+  readonly port: number
+  readonly url: string
+  readonly stop: () => Promise<void>
+}
+
+export interface CanvasRefused {
+  readonly ok: false
+  readonly reason: Extract<ServeRefusal, 'no-port' | 'bind-failed'>
+  readonly detail: string
+}
+
+export type CanvasOutcome = CanvasStarted | CanvasRefused
+
+export interface CanvasOptions {
+  readonly port?: number
+  /**
+   * What answers `/`. The command passes the HTML import of `index.html`, which
+   * `Bun.serve` bundles on request, and a test passes a plain response, since
+   * the test runner cannot load an HTML module.
+   */
+  readonly shell: Bun.HTMLBundle | Response
+  readonly tokens?: TokenOptions
+}
+
+export interface ChangeEvent {
+  readonly page: string
+  /**
+   * The path under the page folder, or empty when the change is to the
+   * top-level entry itself, being a page folder added, renamed, or removed.
+   * An empty file names no frame, so a reader rereads the page list alone.
+   */
+  readonly file: string
+}
+
+/**
+ * Escapes the one sequence that would end the injected element early. The
+ * hash is hex, so it needs no escaping inside the attribute.
+ */
+function styleElement(css: string, hash: string | undefined): string {
+  const stamp = hash === undefined ? '' : ` ${HASH_ATTRIBUTE}="${hash}"`
+  return `<style ${TOKENS_ATTRIBUTE}${stamp}>${css.replaceAll('</style', '<\\/style')}</style>`
+}
+
+/**
+ * Puts the tokens first in the head, so a stylesheet the frame links itself
+ * still wins the cascade. A frame with no head gets the element right after
+ * its doctype, which a browser hoists into the head it builds. A hash stamps
+ * the element even when no tokens resolve, since the shell sends it back with
+ * an element pick.
+ */
+export function injectTokens(html: string, css: string, hash?: string): string {
+  if (css === '' && hash === undefined) return html
+  const element = styleElement(css, hash)
+  const head = html.match(/<head(?:\s[^>]*)?>/i)
+  if (head?.index === undefined) {
+    /* Ahead of a doctype the element would drop the frame into quirks mode. */
+    const doctype = html.match(/^\s*<!doctype[^>]*>/i)?.[0] ?? ''
+    return `${doctype}${element}${html.slice(doctype.length)}`
+  }
+  const at = head.index + head[0].length
+  return `${html.slice(0, at)}${element}${html.slice(at)}`
+}
+
+/**
+ * Whether a request names this server by a loopback name and its own port.
+ * The bind keeps other machines out, and this keeps out a page the operator
+ * visits whose domain was rebound to 127.0.0.1, which reaches the socket with
+ * its own name in the Host header.
+ */
+export function isLoopbackHost(host: string | null, port: number): boolean {
+  return host === `${SERVE_HOST}:${port}` || host === `localhost:${port}`
+}
+
+type Handler = (
+  request: Request,
+  server: Bun.Server<undefined>,
+) => Response | Promise<Response>
+
+function guarded(handler: Handler): Handler {
+  return (request, server) =>
+    isLoopbackHost(request.headers.get('host'), server.port ?? 0)
+      ? handler(request, server)
+      : new Response('Forbidden\n', {
+          status: 403,
+          headers: { 'content-type': 'text/plain; charset=utf-8' },
+        })
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      'cache-control': 'no-store',
+    },
+  })
+}
+
+const REFUSAL_STATUS: Record<ContentRefused['reason'], number> = {
+  'invalid-name': 400,
+  'invalid-size': 400,
+  'invalid-position': 400,
+  'no-page': 404,
+  'no-frame': 404,
+  exists: 409,
+  'malformed-layout': 409,
+  busy: 409,
+  'invalid-address': 400,
+  'address-mismatch': 409,
+  'stale-address': 409,
+}
+
+function refusal(refused: ContentRefused): Response {
+  return json(refused, REFUSAL_STATUS[refused.reason])
+}
+
+function badBody(detail: string): Response {
+  return json({ ok: false, reason: 'invalid-body', detail }, 400)
+}
+
+/**
+ * The Host guard cannot tell the shell from a page on another origin that
+ * reaches this socket, since a browser sends the loopback Host either way. A
+ * write also carries an Origin when a page sent it, so one naming any other
+ * origin is refused, and a JSON content type forces that page through a
+ * preflight this server never answers.
+ */
+function mutation(handler: (body: unknown) => Response): Handler {
+  return async (request, server) => {
+    const origin = request.headers.get('origin')
+    if (origin !== null && !isLoopbackOrigin(origin, server.port ?? 0)) {
+      return new Response('Forbidden\n', { status: 403 })
+    }
+    const type = request.headers.get('content-type') ?? ''
+    if (!type.startsWith('application/json')) {
+      return json(
+        { ok: false, reason: 'invalid-body', detail: 'send application/json' },
+        415,
+      )
+    }
+    let body: unknown
+    try {
+      body = await request.json()
+    } catch {
+      return badBody('the body is not JSON')
+    }
+    return handler(body)
+  }
+}
+
+function isLoopbackOrigin(origin: string, port: number): boolean {
+  return (
+    origin === `http://${SERVE_HOST}:${port}` ||
+    origin === `http://localhost:${port}`
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isAddressShape(value: unknown): value is ElementAddress {
+  return (
+    isRecord(value) &&
+    typeof value.index === 'number' &&
+    typeof value.tag === 'string' &&
+    typeof value.count === 'number' &&
+    (value.hash === undefined || typeof value.hash === 'string')
+  )
+}
+
+async function serveFrame(
+  root: string,
+  content: string,
+  request: Request,
+  tokens: TokenOptions,
+): Promise<Response> {
+  const url = new URL(request.url)
+  url.pathname = `/${url.pathname.slice(FRAMES_PREFIX.length)}`
+  const file = await respond(content, new Request(url))
+
+  const type = file.headers.get('content-type') ?? ''
+  if (file.status !== 200 || !type.startsWith('text/html')) return file
+
+  const { css } = resolveFrameTokens(root, tokens)
+  /*
+   * Hashed over the bytes on disk, the same input `writeSelection` reads,
+   * since decoding to text drops a byte order mark the file still holds.
+   */
+  const bytes = new Uint8Array(await file.arrayBuffer())
+  const html = new TextDecoder().decode(bytes)
+  return new Response(injectTokens(html, css, contentHash(bytes)), {
+    headers: { 'content-type': type, 'cache-control': 'no-store' },
+  })
+}
+
+/**
+ * Fans each change under the canvas folder out to every open shell. The first
+ * segment names the page and the rest names the file within it, so a
+ * top-level entry goes out with an empty file. Only an empty path is skipped.
+ */
+class ChangeStream {
+  private readonly clients = new Set<ReadableStreamDefaultController<string>>()
+  private readonly pending = new Map<string, ReturnType<typeof setTimeout>>()
+  private readonly watcher: FSWatcher
+
+  constructor(content: string) {
+    this.watcher = watch(content, { recursive: true }, (_event, filename) => {
+      if (filename) this.queue(filename.toString())
+    })
+  }
+
+  /**
+   * A one-segment path is kept because the recursive watch reports a page
+   * folder appearing, going, or being renamed under its bare name with nothing
+   * beneath it. A stray file beside the pages goes out the same way, which
+   * costs the shell one page-list reread.
+   */
+  private queue(path: string): void {
+    const [page, ...rest] = path.split(/[\\/]/)
+    if (page === undefined || page === '') return
+    /* A write's staging or lock file, gone a moment later. */
+    if (path.endsWith(TEMP_SUFFIX) || path.endsWith(LOCK_SUFFIX)) return
+    clearTimeout(this.pending.get(path))
+    this.pending.set(
+      path,
+      setTimeout(() => {
+        this.pending.delete(path)
+        this.send({ page, file: rest.join('/') })
+      }, SETTLE_MS),
+    )
+  }
+
+  private send(change: ChangeEvent): void {
+    const frame = `data: ${JSON.stringify(change)}\n\n`
+    for (const client of this.clients) client.enqueue(frame)
+  }
+
+  open(): Response {
+    let self: ReadableStreamDefaultController<string> | undefined
+    const stream = new ReadableStream<string>({
+      start: (controller) => {
+        self = controller
+        this.clients.add(controller)
+        controller.enqueue(': open\n\n')
+      },
+      cancel: () => {
+        if (self) this.clients.delete(self)
+      },
+    })
+    return new Response(stream, {
+      headers: {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+      },
+    })
+  }
+
+  close(): void {
+    this.watcher.close()
+    for (const timer of this.pending.values()) clearTimeout(timer)
+    for (const client of this.clients) {
+      try {
+        client.close()
+      } catch {
+        /* Already closed by the browser going away. */
+      }
+    }
+    this.clients.clear()
+  }
+}
+
+export function startCanvas(
+  root: string,
+  options: CanvasOptions,
+): CanvasOutcome {
+  const content = canvasDir(root)
+  /* Created up front, since the change stream has to watch something. */
+  mkdirSync(content, { recursive: true })
+
+  const tokens = options.tokens ?? {}
+  /*
+   * Fonts embedded, so the chrome renders in its own face on a machine that
+   * never installed it rather than in whatever the fallback stack finds.
+   */
+  const chromeCss = buildDesignCss(undefined, {
+    components: false,
+    embedFonts: true,
+  })
+  const changes = new ChangeStream(content)
+  const first = options.port ?? CANVAS_PORT
+
+  let bound: ReturnType<typeof bindFirstFree>
+  try {
+    bound = bindFirstFree(first, (port) =>
+      Bun.serve({
+        hostname: SERVE_HOST,
+        port,
+        development: false,
+        /* The change stream stays open for as long as the shell does. */
+        idleTimeout: 0,
+        routes: {
+          /*
+           * The shell and the chunks it bundles carry toolkit code and no
+           * project content, so they are the one route left unguarded.
+           */
+          '/': options.shell,
+          '/api/pages': guarded(() => {
+            const resolved = resolveFrameTokens(root, tokens)
+            const { css: _css, ...source } = resolved
+            const selected = readSelection(root)
+            return json({
+              pages: listPages(root),
+              tokens: source,
+              selection: selected && {
+                page: selected.page,
+                frame: selected.frame,
+                ...(selected.element && {
+                  element: {
+                    index: selected.element.index,
+                    tag: selected.element.tag,
+                    stale: selected.element.stale,
+                  },
+                }),
+              },
+            })
+          }),
+          '/api/frames/move': {
+            POST: guarded(
+              mutation((body) => {
+                if (
+                  !isRecord(body) ||
+                  typeof body.page !== 'string' ||
+                  typeof body.frame !== 'string' ||
+                  typeof body.x !== 'number' ||
+                  typeof body.y !== 'number'
+                ) {
+                  return badBody('send page, frame, x, and y')
+                }
+                const outcome = moveFrame(root, body.page, body.frame, {
+                  x: body.x,
+                  y: body.y,
+                })
+                return outcome.ok ? json(outcome) : refusal(outcome)
+              }),
+            ),
+          },
+          '/api/selection': {
+            POST: guarded(
+              mutation((body) => {
+                if (!isRecord(body)) return badBody('send a frame or {}')
+                const { page, frame } = body
+                const target =
+                  typeof page === 'string' && typeof frame === 'string'
+                    ? { page, frame }
+                    : undefined
+                if (target === undefined && (page != null || frame != null)) {
+                  return badBody('send both page and frame, or neither')
+                }
+                const { element } = body
+                if (element != null && target === undefined) {
+                  return badBody('send an element with its page and frame')
+                }
+                if (element != null && !isAddressShape(element)) {
+                  return badBody('send an element as index, tag, and count')
+                }
+                const outcome = writeSelection(
+                  root,
+                  target && element != null ? { ...target, element } : target,
+                )
+                return outcome.ok ? json(outcome) : refusal(outcome)
+              }),
+            ),
+          },
+          '/api/chrome.css': guarded(
+            () =>
+              new Response(chromeCss, {
+                headers: {
+                  'content-type': 'text/css; charset=utf-8',
+                  'cache-control': 'no-store',
+                },
+              }),
+          ),
+          '/api/events': guarded(() => changes.open()),
+        },
+        fetch: guarded((request) => {
+          const { pathname } = new URL(request.url)
+          if (pathname.startsWith(FRAMES_PREFIX)) {
+            return serveFrame(root, content, request, tokens)
+          }
+          return new Response('Not found\n', { status: 404 })
+        }),
+      }),
+    )
+  } catch (error) {
+    changes.close()
+    const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
+    return {
+      ok: false,
+      reason: 'bind-failed',
+      detail: `could not bind ${SERVE_HOST}:${first} (${code})`,
+    }
+  }
+
+  if (!bound) {
+    changes.close()
+    return {
+      ok: false,
+      reason: 'no-port',
+      detail: `no free port between ${first} and ${first + PORT_ATTEMPTS - 1}`,
+    }
+  }
+
+  const { server, port } = bound
+  return {
+    ok: true,
+    root,
+    content,
+    host: SERVE_HOST,
+    port,
+    url: `http://${SERVE_HOST}:${port}/`,
+    stop: async () => {
+      changes.close()
+      await server.stop(true)
+    },
+  }
+}

package/src/canvas/tokens.ts

@@ -0,0 +1,71 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR } from '@/design/adapter'
+import { buildDesignCss } from '@/design/css'
+import { isOwnCheckout } from '@/project-root'
+
+/**
+ * The stylesheet injected into every frame, so a frame drawn with
+ * `var(--color-*)` shows the project's own values. Parsing a `DESIGN.md` into
+ * custom properties is left out, since no such mapping exists, and a frame can
+ * always link a stylesheet of its own.
+ */
+export type FrameTokens =
+  | { readonly source: 'toolkit'; readonly css: string }
+  | {
+      readonly source: 'installed'
+      readonly css: string
+      /** Relative to the root, in the order the stylesheet concatenates them. */
+      readonly files: readonly string[]
+    }
+  | { readonly source: 'none'; readonly css: ''; readonly notice: string }
+
+export interface TokenOptions {
+  /** Overrides the checkout test, which reads this package's own name. */
+  readonly isOwnCheckout?: boolean
+}
+
+const BASE_FILE = 'base.css'
+
+const NONE_NOTICE = `No token stylesheet, so frames render unstyled. Run canon design install to add ${join(DESIGN_INSTALL_DIR, BASE_FILE)}, put overrides under ${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/, or link a stylesheet from the frame.`
+
+/** The installed files in cascade order: the base first, then each override. */
+function installedFiles(root: string): string[] {
+  const files: string[] = []
+  const base = join(DESIGN_INSTALL_DIR, BASE_FILE)
+  if (existsSync(join(root, base))) files.push(base)
+
+  const projectDir = join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)
+  if (existsSync(join(root, projectDir))) {
+    const overrides = readdirSync(join(root, projectDir))
+      .filter((name) => name.endsWith('.css'))
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => join(projectDir, name))
+    files.push(...overrides)
+  }
+  return files
+}
+
+/**
+ * The toolkit's own module where the root is this checkout, else the installed
+ * base plus its project overrides, else nothing with a notice naming where
+ * tokens would come from.
+ */
+export function resolveFrameTokens(
+  root: string,
+  options: TokenOptions = {},
+): FrameTokens {
+  if (options.isOwnCheckout ?? isOwnCheckout(root)) {
+    return { source: 'toolkit', css: buildDesignCss() }
+  }
+
+  const files = installedFiles(root)
+  if (files.length > 0) {
+    const css = files
+      .map((file) => `/* ${file} */\n${readFileSync(join(root, file), 'utf8')}`)
+      .join('\n')
+    return { source: 'installed', css, files }
+  }
+
+  return { source: 'none', css: '', notice: NONE_NOTICE }
+}

package/src/claude/cases/misc.ts

@@ -79,6 +79,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'The same discount rule sits in two files and I need a third variant. Should I extract it, or add a strategy class for the two cases?',
     expect: 'code-craft',
   },
+  {
+    prompt:
+      'Find me the strongest evidence on whether rent control reduces housing supply. Where should I look?',
+    expect: 'search-craft',
+  },
   {
     prompt:
       "I've got the plan approved and it touches the parser, the command, and the docs. How should I build it so I don't end up with one giant diff?",

package/src/claude/seeds.ts

@@ -20,7 +20,6 @@ const HOOKS = 'hooks'
 export const SUBDIRS: readonly string[] = [
   HOOKS,
   'context',
-  'decisions',
   'diagrams',
   'memory',
   'tasks',

package/src/cli.ts

@@ -23,6 +23,7 @@ import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
 import { register as intake } from '@/commands/intake'
 import { register as teach } from '@/commands/teach'
+import { register as canvas } from '@/commands/canvas'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
@@ -84,6 +85,7 @@ transcripts(program)
 tasks(program)
 intake(program)
 teach(program)
+canvas(program)
 comments(program)
 context(program)
 markdown(program)