@erclx/canon 5.79.0 → 5.80.0

package/src/commands/capture.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
@@ -32,6 +32,7 @@ const DEFAULT_SOURCE = 'assets'
 type Renderer = typeof import('@/capture/render')
 type CaptureResult = Awaited<ReturnType<Renderer['captureSources']>>[number]
 type ColorScheme = import('@/capture/render').ColorScheme
+type SectionsResult = import('@/capture/render').SectionsResult
 
 const COLOR_SCHEMES: readonly ColorScheme[] = ['light', 'dark']
 
@@ -56,7 +57,15 @@ export function register(program: Command): void {
       '-o, --out <path>',
       'Output directory for a file source, or the destination PNG for a URL source; defaults beside the source',
     )
-    .option('-s, --selector <selector>', 'Element to capture')
+    .option(
+      '-s, --selector <selector>',
+      'Element to capture, or with --sections the root to split, defaulting to main and then body',
+    )
+    .option(
+      '--sections',
+      'Write one PNG per section of one page into the --out folder, in page order',
+    )
+    .option('--json', 'With --sections, print the result as one JSON record')
     .option(
       '--width <px>',
       'Viewport width in pixels, so a media query resolves at that width',
@@ -69,8 +78,8 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'The selector has no default, since the element to crop to belongs to the',
-        'page. Each element holding text inside it must resolve its first font',
+        'Outside --sections the selector has no default, since the element to',
+        'crop to belongs to the page. Each element holding text inside it must resolve its first font',
         'family, and a generic keyword such as monospace or system-ui fails,',
         'since it resolves differently on each machine. The user agent sets',
         'monospace on pre, code, kbd, and samp, so each needs its own',
@@ -81,6 +90,21 @@ export function register(program: Command): void {
         'a light or dark class on the root, so a stylesheet keyed on any of the',
         'three renders that theme. Run it once per scheme with its own --out.',
         '',
+        '--sections takes one HTML file or URL and needs --out naming a folder.',
+        'It wheels down the page so lazy content loads, hides fixed and sticky',
+        'layers, splits any block taller than 1.6 viewports into its children,',
+        'and joins a block under 400px to the one above. Each shot is cut at',
+        '2400px and writes section-NN.png with its stamp. A generic or missing',
+        'font family is recorded rather than refused. --json prints',
+        '{ source, sections: [{ index, path, top, height }], failed: [{ index,',
+        'reason }], fonts: { generic, missing } }, or { source, reason } when',
+        'the page fails whole.',
+        '',
+        'Examples:',
+        '  canon capture assets --selector .window',
+        '  canon capture https://example.com --sections --out refs/example --width 1440',
+        '  canon capture https://example.com --sections --out refs/example --json',
+        '',
       ].join('\n'),
     )
     .action(
@@ -91,8 +115,20 @@ export function register(program: Command): void {
           selector?: string
           width?: string
           colorScheme?: string
+          sections?: boolean
+          json?: boolean
         },
       ): Promise<void> => {
+        if (opts.json && !opts.sections) {
+          frameError('--json applies to --sections. See canon capture --help.')
+          process.exitCode = 1
+          return
+        }
+        if (opts.sections) {
+          await captureSectionsAction(source, opts)
+          return
+        }
+
         /**
          * Refused rather than defaulted, and refused ahead of every other
          * check, so the message names the invocation rather than whatever the
@@ -176,6 +212,115 @@ export function register(program: Command): void {
     )
 }
 
+interface SectionFlags {
+  out?: string
+  selector?: string
+  width?: string
+  colorScheme?: string
+  json?: boolean
+}
+
+/**
+ * Section mode reads `--out` as a folder for every source kind, so it is
+ * required here even for a file source, and a directory source is refused,
+ * since a section run describes one page.
+ */
+async function captureSectionsAction(
+  source: string,
+  opts: SectionFlags,
+): Promise<void> {
+  const width = parseWidth(opts.width)
+  if (Number.isNaN(width)) {
+    frameError(
+      `--width takes a whole number of pixels of 1 or more, got ${opts.width}.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  const colorScheme = parseColorScheme(opts.colorScheme)
+  if (colorScheme === null) {
+    frameError(
+      `--color-scheme takes ${COLOR_SCHEMES.join(' or ')}, got ${JSON.stringify(opts.colorScheme)}.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  if (!opts.out) {
+    frameError('--sections needs --out naming the folder the shots go in.')
+    process.exitCode = 1
+    return
+  }
+
+  const isUrl = isUrlSource(source)
+  const sourcePath = isUrl ? source : resolve(process.cwd(), source)
+  if (!isUrl && !existsSync(sourcePath)) {
+    frameError(`${source} not found`)
+    process.exitCode = 1
+    return
+  }
+  if (!isUrl && statSync(sourcePath).isDirectory()) {
+    frameError(
+      `--sections takes one HTML file or URL, and ${source} is a directory.`,
+    )
+    process.exitCode = 1
+    return
+  }
+
+  const json = opts.json ?? false
+  if (!json) intro('Capture sections')
+  let result: SectionsResult
+  try {
+    const renderer = await import('@/capture/render')
+    result = await renderer.captureSections(sourcePath, {
+      outDir: resolve(process.cwd(), opts.out),
+      root: opts.selector,
+      width,
+      colorScheme,
+    })
+  } catch (error) {
+    if (json) {
+      logError(error instanceof Error ? error.message : String(error))
+    } else {
+      reportInFrame(error)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  if (result.status === 'failed') {
+    if (json) {
+      process.stdout.write(
+        `${JSON.stringify({ source: result.source, reason: result.reason })}\n`,
+      )
+    }
+    logError(`${displayPath(result.source)}: ${result.reason}`)
+    if (!json) outro()
+    process.exitCode = 1
+    return
+  }
+
+  const { source: page, sections, failed, fonts } = result
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ source: page, sections, failed, fonts })}\n`,
+    )
+  }
+  for (const shot of json ? [] : sections) {
+    logInfo(`${displayPath(shot.path)} top ${shot.top} height ${shot.height}`)
+  }
+  for (const fault of failed) {
+    logError(`section ${fault.index}: ${fault.reason}`)
+  }
+  if (!json && fonts.generic.length) {
+    logWarn(`generic families drawn: ${fonts.generic.join(', ')}`)
+  }
+  if (!json && fonts.missing.length) {
+    logWarn(`families not installed: ${fonts.missing.join(', ')}`)
+  }
+  if (!json) outro()
+  if (failed.length || !sections.length) process.exitCode = 1
+}
+
 /**
  * Undefined for an absent flag and `NaN` for a value that is not a positive
  * integer, so the caller can tell no width from a bad one.

package/src/commands/tooling.ts

@@ -37,6 +37,7 @@ import {
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
+import { scaffoldStack } from '@/tooling/scaffold'
 import { verifyStack } from '@/tooling/verify-stack'
 import {
   intro,
@@ -377,6 +378,77 @@ export function register(program: Command): void {
       })
       process.exitCode = outcome.exitCode
     })
+
+  tooling
+    .command('scaffold')
+    .description("Run a stack's starter command into an empty folder")
+    .argument('<stack>', 'Tooling stack name (e.g. vite-react, astro)')
+    .argument('[target]', 'Target directory, created when missing', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        "Runs the stack's manifest scaffold in a scratch folder, with the",
+        "target's folder name as the project name, then moves the result into",
+        'the target. A target holding anything but .git is refused, and a',
+        'failed command moves nothing and leaves the scratch folder named.',
+        'Run `canon init` or the target-setup skill afterward to sync tooling.',
+        '',
+        'Exit codes:',
+        '  0  scaffolded',
+        '  1  refused: excluded, no-manifest, no-scaffold, not-empty, bad-name,',
+        '     scaffold-failed, or no-output',
+        '',
+        'Examples:',
+        '  canon tooling scaffold vite-react',
+        '  canon tooling scaffold astro my-site --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (stack: string, target: string, opts: ListOptions) => {
+      process.exitCode = await runScaffold(stack, target, opts)
+    })
+}
+
+/**
+ * A `--json` run writes no frame, so a skill reads the record alone, and a
+ * refusal carries its reason on stdout beside the exit 1.
+ */
+async function runScaffold(
+  stack: string,
+  target: string,
+  opts: ListOptions,
+): Promise<number> {
+  const json = opts.json === true
+  if (!json) intro(`canon tooling scaffold ${stack}`)
+
+  const result = await scaffoldStack({ root: PROJECT_ROOT, stack, target })
+
+  if (!result.ok) {
+    logError(result.message)
+    if (result.scratch !== undefined) {
+      if (result.output !== undefined && result.output !== '') {
+        process.stderr.write(
+          `${result.output.split('\n').slice(-20).join('\n')}\n`,
+        )
+      }
+      logInfo(`Kept ${result.scratch}`)
+    }
+    if (json) process.stdout.write(`${JSON.stringify(result)}\n`)
+    else outro()
+    return 1
+  }
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`)
+    return 0
+  }
+  logStep(`Scaffolded ${result.target}`)
+  for (const file of result.files) logAdd(file)
+  outroSuccess('Scaffolded', `Next: canon init ${target}`)
+  return 0
 }
 
 /**

package/src/take/perform.ts

@@ -472,6 +472,12 @@ async function scrollPoint(stage: Stage, target: string): Promise<Point> {
  * innermost element with a size whose whole text is those words, so a hidden
  * copy earlier in the page cannot shadow a visible one, and anything else as a
  * CSS selector.
+ * The document is searched first and every open shadow root after it in tree
+ * order, so a document-tree match wins, except that innermost reads containment
+ * through a shadow root to its host and a `text=` match holding a sized match
+ * inside its subtree's roots gives way to it. A selector matches within one
+ * root and never across a shadow boundary. A closed root and a frame stay
+ * unreachable.
  * It runs inside the page so both routes resolve a target the same way, and a
  * match with no size counts as missing, since a click on it would land on
  * whatever sits behind.
@@ -479,19 +485,38 @@ async function scrollPoint(stage: Stage, target: string): Promise<Point> {
 export function boxExpression(target: string): string {
   return `(() => {
     const target = ${JSON.stringify(target)}
+    const roots = []
+    const collect = (root) => {
+      roots.push(root)
+      for (const node of root.querySelectorAll('*')) {
+        if (node.shadowRoot) collect(node.shadowRoot)
+      }
+    }
+    collect(document)
+    const within = (outer, inner) => {
+      for (let node = inner; node; node = node.parentNode ?? node.host ?? null) {
+        if (node === outer) return true
+      }
+      return false
+    }
     let element = null
     if (target.startsWith('text=')) {
       const want = target.slice(5).trim()
-      const matches = [...document.querySelectorAll('body *')].filter(
-        (node) => node.textContent.trim() === want,
+      const matches = roots.flatMap((root) =>
+        [...root.querySelectorAll(root === document ? 'body *' : '*')].filter(
+          (node) => node.textContent.trim() === want,
+        ),
       )
-      const innermost = matches.filter((node) => !matches.some((other) => other !== node && node.contains(other)))
+      const innermost = matches.filter((node) => !matches.some((other) => other !== node && within(node, other)))
       element = innermost.find((node) => {
         const rect = node.getBoundingClientRect()
         return rect.width > 0 && rect.height > 0
       }) ?? null
     } else {
-      element = document.querySelector(target)
+      for (const root of roots) {
+        element = root.querySelector(target)
+        if (element) break
+      }
     }
     if (!element) return null
     const rect = element.getBoundingClientRect()

package/src/tooling/list.ts

@@ -6,6 +6,8 @@ export interface StackSummary {
   readonly devDeps: number
   readonly scripts: number
   readonly gitignoreGroups: number
+  /** Whether `canon tooling scaffold` can start a project on this stack. */
+  readonly scaffold: boolean
 }
 
 /**
@@ -26,6 +28,7 @@ export function buildStackSummaries(root: string): StackSummary[] {
       devDeps: manifest.devPackages.length,
       scripts: Object.keys(manifest.scripts).length,
       gitignoreGroups: manifest.gitignore.length,
+      scaffold: manifest.scaffold !== undefined,
     })
   }
 

package/src/tooling/scaffold.ts

@@ -0,0 +1,193 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
+import { execa } from 'execa'
+import { isStackExcluded, loadManifest } from '@/tooling/manifest'
+
+export interface ScaffoldOptions {
+  /** Root holding `tooling/<stack>/manifest.toml`. */
+  readonly root: string
+  readonly stack: string
+  readonly target: string
+  /** Parent of the scratch folder the command runs in. Defaults to the OS temp dir. */
+  readonly scratchBase?: string
+}
+
+export type ScaffoldRefusal =
+  | 'excluded'
+  | 'no-manifest'
+  | 'no-scaffold'
+  | 'not-empty'
+  | 'bad-name'
+  | 'scaffold-failed'
+  | 'no-output'
+
+export type ScaffoldResult =
+  | {
+      readonly ok: true
+      readonly stack: string
+      readonly target: string
+      readonly name: string
+      readonly files: readonly string[]
+    }
+  | {
+      readonly ok: false
+      readonly reason: ScaffoldRefusal
+      readonly message: string
+      readonly suggested?: string
+      readonly scratch?: string
+      readonly output?: string
+    }
+
+/**
+ * npm, create-next-app, and composer all refuse a package name with capitals,
+ * spaces, or a leading dot, and the target's basename becomes that name.
+ */
+const PACKAGE_NAME = /^[a-z0-9][a-z0-9._-]*$/
+const MAX_NAME = 214
+
+/** A target holding only `.git` counts as empty, since `git init` first is common. */
+const IGNORED_ENTRIES = new Set(['.git'])
+
+/**
+ * Runs the stack's `manifest.scaffold` in a scratch folder with `{{name}}` set
+ * to the target's basename, then moves what it produced into the target. The
+ * scratch step is what lets a command that opens on `mkdir {{name}} && cd`
+ * land in a folder that already exists.
+ *
+ * Nothing reaches the target unless the command exits 0 and produced its
+ * folder. A failed run leaves the scratch folder in place and names it.
+ */
+export async function scaffoldStack(
+  opts: ScaffoldOptions,
+): Promise<ScaffoldResult> {
+  const { root, stack } = opts
+  const target = resolve(opts.target)
+
+  if (isStackExcluded(stack)) {
+    return refuse('excluded', `Stack '${stack}' is excluded from tooling.`)
+  }
+  const manifest = loadManifest(root, stack)
+  if (manifest === undefined) {
+    return refuse(
+      'no-manifest',
+      `No manifest at tooling/${stack}/manifest.toml`,
+    )
+  }
+  if (manifest.scaffold === undefined) {
+    return refuse(
+      'no-scaffold',
+      `Stack '${stack}' has no scaffold command in its manifest.`,
+    )
+  }
+
+  const held = existsSync(target) ? occupiedEntries(target) : []
+  if (held.length > 0) {
+    return refuse(
+      'not-empty',
+      `${target} is not empty (${held.slice(0, 3).join(', ')}${held.length > 3 ? ', ...' : ''}). Scaffold into an empty folder.`,
+    )
+  }
+
+  const name = basename(target)
+  if (!PACKAGE_NAME.test(name) || name.length > MAX_NAME) {
+    const suggested = suggestName(name)
+    return {
+      ok: false,
+      reason: 'bad-name',
+      message: `Folder name '${name}' is not a valid package name. Use lowercase letters, digits, '.', '_', and '-', such as '${suggested}'.`,
+      suggested,
+    }
+  }
+
+  const scratch = mkdtempSync(
+    join(opts.scratchBase ?? tmpdir(), 'canon-scaffold-'),
+  )
+  // Manifests carry shell syntax (`&&`, `cd`, quoted globs), so the command
+  // runs under a shell rather than as a split argv, as `tooling verify` runs it.
+  const command = manifest.scaffold.replaceAll('{{name}}', name)
+  const run = await execa(command, {
+    cwd: scratch,
+    shell: 'bash',
+    all: true,
+    reject: false,
+    stdin: 'ignore',
+    env: { CI: '1' },
+  })
+  const output = typeof run.all === 'string' ? run.all : ''
+
+  if (run.failed) {
+    return {
+      ok: false,
+      reason: 'scaffold-failed',
+      message: `Scaffold command failed: ${command}`,
+      scratch,
+      output,
+    }
+  }
+  const produced = join(scratch, name)
+  if (!existsSync(produced)) {
+    return {
+      ok: false,
+      reason: 'no-output',
+      message: `Scaffold command exited 0 but produced no ${name}/ folder.`,
+      scratch,
+      output,
+    }
+  }
+
+  mkdirSync(target, { recursive: true })
+  const keepTargetGit = existsSync(join(target, '.git'))
+  const files: string[] = []
+  for (const entry of readdirSync(produced).sort()) {
+    if (entry === '.git' && keepTargetGit) continue
+    move(join(produced, entry), join(target, entry))
+    files.push(entry)
+  }
+  rmSync(scratch, { recursive: true, force: true })
+
+  return { ok: true, stack, target, name, files }
+}
+
+function refuse(reason: ScaffoldRefusal, message: string): ScaffoldResult {
+  return { ok: false, reason, message }
+}
+
+function occupiedEntries(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((entry) => !IGNORED_ENTRIES.has(entry))
+    .sort()
+}
+
+/**
+ * Lowercases the name and turns every run of other characters into one dash,
+ * falling back to `app` when nothing usable is left.
+ */
+export function suggestName(name: string): string {
+  const cleaned = name
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[^a-z0-9]+/, '')
+    .replace(/-+$/, '')
+    .slice(0, MAX_NAME)
+  return cleaned === '' ? 'app' : cleaned
+}
+
+/** The OS temp dir often sits on another filesystem, where a rename fails. */
+function move(from: string, to: string): void {
+  try {
+    renameSync(from, to)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error
+    cpSync(from, to, { recursive: true, preserveTimestamps: true })
+    rmSync(from, { recursive: true, force: true })
+  }
+}

package/tooling/cloudflare/manifest.toml

@@ -2,4 +2,4 @@
 name = "cloudflare"
 extends = ""
 runtime = "bun"
-scaffold = ""
+scaffold = "npm create cloudflare@latest {{name}} -- --type hello-world --lang ts --no-deploy --no-git"

package/tooling/cloudflare/reference.md

@@ -6,6 +6,14 @@ The cloudflare stack ships one parameterized GitHub Actions workflow that deploy
 
 It ships one script, `scripts/delete-previews.sh`, which the cleanup job calls and which overwrites a project's own file of that name on every sync.
 
+## Scaffold
+
+The manifest's scaffold starts a new project as a TypeScript Worker from the `hello-world` template, through `npm create cloudflare@latest` with deploy and git both off. `canon tooling scaffold cloudflare` runs it in an empty folder.
+
+- The starter installs its own dependencies, since `create-cloudflare` runs the install itself.
+- A project already on `astro` or `vite-react` never takes this scaffold. It syncs the stack onto the framework it has.
+- The stack extends nothing and ships no scripts, so `canon tooling verify cloudflare` passes Scaffold and Sync and stops at `lint:fix`. Run `canon init` on the starter to bring in the base scripts.
+
 ## Deploy workflow
 
 ### Job shape