@erclx/aitk 0.16.0 → 0.17.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents.md

@@ -80,6 +80,7 @@ Full help: `aitk <command> --help`.
 | `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                          |
 | `aitk tasks archive`     | Move a shipped task off the board, clear its ordering row, and regenerate the index            |
 | `aitk comments scan`     | Measure comment density by language and comment kind, with a trend recomputed from git         |
+| `aitk capture [source]`  | Render HTML capture sources to PNG, toolkit-only and absent from an installed package          |
 
 ### Domain commands
 
@@ -301,6 +302,29 @@ aitk tasks archive --pull-request 673 --json | jq -r 'if .ok then .task else .re
 
 For the board format, the `Pull request:` line, and the archive rules, see `.claude/standards/tasks.md`.
 
+## Capture
+
+`aitk capture [source]` renders HTML capture sources to PNG, which is how a committed documentation image regenerates from its committed source. The source defaults to `assets/`, where a directory expands to every `.html` directly inside it, so adding a capture means dropping a file beside the first one and running the same bare command.
+
+```bash
+aitk capture
+aitk capture assets/install.html
+aitk capture assets --out .claude/review/captures
+```
+
+| Option             | Behavior                                          |
+| ------------------ | ------------------------------------------------- |
+| `--out <dir>`      | Write every PNG here instead of beside its source |
+| `--selector <sel>` | Element to capture (default: `.window`)           |
+
+Each source renders at `deviceScaleFactor` 2 with a transparent background, and the success line reports the pixel dimensions the element wrapped to. Size is reported and never asserted. The height of a terminal frame is whatever its text wrapped to at a fixed width, so pinning that number would harden an accident.
+
+What is asserted is the font. The command reads the first family the captured element declares and fails when the browser did not resolve it, because a fallback face rewraps the block and silently changes the output. Sources therefore name a real font rather than relying on `monospace`. A source that cannot render reports its own line and exits 1 without dropping the rest of the batch.
+
+The browser binary installs separately from the package. A fresh clone runs `bunx playwright install chromium` once, and a run that cannot launch one reports the engine's own remediation inside the frame and exits 1 rather than escaping as a stack trace.
+
+The command is toolkit-only. Its render module holds every browser reference in the toolkit and `files` in `package.json` excludes it, so an installed `aitk` carries the command, reports it as absent on one line, and exits 1. Every other command is unaffected, which is the reason the browser import sits behind a dynamic import rather than at a command's top level.
+
 ## Comments
 
 `aitk comments scan [path]` reports comment density for a tree, split by language and by comment kind. It is the only command that parses the target's own source, so its scope stays deliberately narrow: TypeScript and bash, line-oriented, no AST.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -19,6 +19,7 @@
     "tsconfig.json",
     "!scripts/sandbox",
     "!scripts/eval",
+    "!src/capture",
     "!**/*.test.ts"
   ],
   "publishConfig": {

package/src/cli.ts

@@ -14,6 +14,7 @@ import { register as indexes } from '@/commands/indexes'
 import { register as docs } from '@/commands/docs'
 import { register as design } from '@/commands/design'
 import { register as slides } from '@/commands/slides'
+import { register as capture } from '@/commands/capture'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -42,6 +43,7 @@ function showHelp(): void {
     `${GREY}│${NC}    docs [cmd|topic]   ${GREY}# Emit toolkit reference docs (list, <topic>)${NC}`,
     `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render)${NC}`,
     `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
+    `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
@@ -72,6 +74,7 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk design render`,
     `${GREY}│${NC}    aitk slides render`,
     `${GREY}│${NC}    aitk slides list --json`,
+    `${GREY}│${NC}    aitk capture assets/install.html`,
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
@@ -107,6 +110,7 @@ indexes(program)
 docs(program)
 design(program)
 slides(program)
+capture(program)
 feedback(program)
 transcripts(program)
 tasks(program)

package/src/commands/capture.ts

@@ -0,0 +1,133 @@
+import { existsSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { frameError, intro, logError, logInfo, outro, pipeOutput } from '@/ui'
+
+const DEFAULT_SOURCE = 'assets'
+const DEFAULT_SELECTOR = '.window'
+
+/**
+ * Both aliases are type queries rather than imports, so `@/capture/render`
+ * never appears in this module's runtime import list.
+ */
+type Renderer = typeof import('@/capture/render')
+type CaptureResult = Awaited<ReturnType<Renderer['captureSources']>>[number]
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadRenderer`,
+ * because `src/cli.ts` imports this module at startup and the render module is
+ * excluded from the published package.
+ */
+export function register(program: Command): void {
+  program
+    .command('capture')
+    .description('Render HTML capture sources to PNG')
+    .argument('[source]', 'HTML file or a directory of them', DEFAULT_SOURCE)
+    .option('-o, --out <dir>', 'Output directory, defaults beside the source')
+    .option('-s, --selector <selector>', 'Element to capture', DEFAULT_SELECTOR)
+    .action(
+      async (
+        source: string,
+        opts: { out?: string; selector: string },
+      ): Promise<void> => {
+        const renderer = await loadRenderer()
+        if (!renderer) {
+          frameError(
+            'capture is toolkit-only and is absent from an installed aitk',
+          )
+          process.exitCode = 1
+          return
+        }
+
+        const sourcePath = resolve(process.cwd(), source)
+        if (!existsSync(sourcePath)) {
+          frameError(`${source} not found`)
+          process.exitCode = 1
+          return
+        }
+
+        intro('Capture')
+        let results: CaptureResult[]
+        try {
+          results = await renderer.captureSources(sourcePath, {
+            selector: opts.selector,
+            outDir: opts.out ? resolve(process.cwd(), opts.out) : undefined,
+          })
+        } catch (error) {
+          reportInFrame(error)
+          process.exitCode = 1
+          return
+        }
+
+        if (!results.length) {
+          logError(`no .html source under ${source}`)
+          outro()
+          process.exitCode = 1
+          return
+        }
+
+        for (const result of results) {
+          if (result.status === 'rendered') {
+            logInfo(
+              `${displayPath(result.pngPath)} ${result.width}x${result.height}`,
+            )
+          } else {
+            logError(`${displayPath(result.htmlPath)}: ${result.reason}`)
+          }
+        }
+        outro()
+
+        if (results.some((result) => result.status === 'failed')) {
+          process.exitCode = 1
+        }
+      },
+    )
+}
+
+/**
+ * Closes an open frame around a failure the render module raised for the whole
+ * run rather than for one source, such as a browser binary that is not
+ * installed. The engine's own message is readable, so it is passed through
+ * intact instead of being summarized.
+ */
+function reportInFrame(error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error)
+  const [first, ...rest] = message.split('\n')
+  logError(first ?? 'capture failed')
+  if (rest.length) pipeOutput(rest.join('\n'))
+  outro()
+}
+
+/**
+ * Keeps a path clickable in the operator's terminal. A source outside the
+ * project reports absolute, since a relative path to it is a run of `..`
+ * segments no editor resolves.
+ */
+function displayPath(path: string): string {
+  const fromCwd = relative(process.cwd(), path)
+  return fromCwd.startsWith('..') ? path : fromCwd
+}
+
+/**
+ * Reports absence only when the module or its engine cannot be resolved, which
+ * is the published-package case. Any other import failure is a defect inside
+ * the render module and propagates, rather than being reported as a feature
+ * the package left out.
+ */
+async function loadRenderer(): Promise<Renderer | undefined> {
+  try {
+    return await import('@/capture/render')
+  } catch (error) {
+    if (isModuleNotFound(error)) return undefined
+    throw error
+  }
+}
+
+function isModuleNotFound(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_MODULE_NOT_FOUND'
+  )
+}