@erclx/canon 5.78.0 → 5.80.0

package/src/tasks/holders.ts

@@ -0,0 +1,198 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git/env'
+import {
+  repositoryOf,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+
+/**
+ * Bounds the one network read `canon tasks validate --live` takes, shorter than
+ * the archive's own, since the sweep waits on it and a slow answer reads the
+ * same as no answer.
+ */
+const GH_TIMEOUT_MS = 5_000
+
+/** `gh pr list` caps at 30 by default, and a truncated list would read as clean. */
+const PULL_LIMIT = 1_000
+
+/**
+ * Who holds each branch, named for a person reading the report. `undefined`
+ * means the source could not be read, which has to stay apart from an empty map:
+ * an unreachable source that degraded to "nobody holds it" would report a held
+ * row as clean.
+ */
+export type HolderReader = () => Promise<
+  ReadonlyMap<string, string> | undefined
+>
+
+/** Whether a merged pull request names a branch, `undefined` when GitHub could not say. */
+export type MergedReader = (branch: string) => Promise<boolean | undefined>
+
+export interface LiveReaders {
+  readonly sessions: HolderReader
+  readonly pulls: HolderReader
+  readonly merged: MergedReader
+}
+
+export interface SessionHolderOptions {
+  readonly resolve?: () => Promise<SessionReport>
+  readonly repository?: (root: string) => Promise<string | null>
+}
+
+/**
+ * Reads the roster scoped to `root`'s repository, since a branch name says
+ * nothing across a machine and another project's worker on the same name holds
+ * nothing here. Two rows leave the liveness undecided, a foreign record whose
+ * socket is gone and a row resting only on a socket file a crash can leave, so
+ * either reads the whole roster as unread rather than as a hold or as clear.
+ */
+export function sessionHolders(
+  root: string,
+  opts: SessionHolderOptions = {},
+): HolderReader {
+  const resolve = opts.resolve ?? resolveSessions
+  const repository = opts.repository ?? repositoryOf
+
+  return async () => {
+    try {
+      const [report, repo] = await Promise.all([resolve(), repository(root)])
+      if (
+        report.kind !== 'resolved' ||
+        report.foreignDead > 0 ||
+        report.sessions.some((session) => session.via === 'socket') ||
+        !repo
+      ) {
+        return undefined
+      }
+
+      return new Map(
+        report.sessions.flatMap((session) =>
+          session.repository === repo && session.branch
+            ? [[session.branch, `session ${session.name}`] as const]
+            : [],
+        ),
+      )
+    } catch {
+      return undefined
+    }
+  }
+}
+
+export type GhRunner = (
+  cwd: string,
+  args: readonly string[],
+) => Promise<string | undefined>
+
+const runGh: GhRunner = async (cwd, args) => {
+  if (Bun.which('gh') === null) return undefined
+
+  try {
+    // `gh` resolves its repository through git, so a hook's resolution
+    // variables would point it at another repository than `cwd`.
+    const result = await execa('gh', [...args], {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.stdout
+  } catch {
+    return undefined
+  }
+}
+
+interface ListedPull {
+  readonly number: number
+  readonly headRefName: string
+  readonly isCrossRepository: boolean
+}
+
+function isListedPull(value: unknown): value is ListedPull {
+  if (typeof value !== 'object' || value === null) return false
+  const pull = value as Record<string, unknown>
+
+  return (
+    typeof pull.number === 'number' &&
+    typeof pull.headRefName === 'string' &&
+    typeof pull.isCrossRepository === 'boolean'
+  )
+}
+
+function parsePulls(stdout: string): readonly ListedPull[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(stdout)
+    return Array.isArray(parsed) && parsed.every(isListedPull)
+      ? parsed
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reads open pull requests off GitHub. A list reaching the limit may have cut
+ * off the one that holds a row, so it reads as unread. A fork's head names a
+ * branch in another repository, which holds nothing here however it is spelled.
+ */
+export function pullHolders(root: string, run: GhRunner = runGh): HolderReader {
+  return async () => {
+    const stdout = await run(root, [
+      'pr',
+      'list',
+      '--state',
+      'open',
+      '--limit',
+      String(PULL_LIMIT),
+      '--json',
+      'number,headRefName,isCrossRepository',
+    ])
+    if (stdout === undefined) return undefined
+
+    const pulls = parsePulls(stdout)
+    if (!pulls || pulls.length >= PULL_LIMIT) return undefined
+
+    return new Map(
+      pulls
+        .filter((pull) => !pull.isCrossRepository)
+        .map((pull) => [pull.headRefName, `pull request #${pull.number}`]),
+    )
+  }
+}
+
+/**
+ * Asks about one branch at a time rather than listing merged pull requests,
+ * since a list long enough to reach an old merge costs every run, and only a
+ * branch a session already holds against a row takes this read.
+ */
+export function mergedBranches(
+  root: string,
+  run: GhRunner = runGh,
+): MergedReader {
+  return async (branch) => {
+    const stdout = await run(root, [
+      'pr',
+      'list',
+      '--state',
+      'merged',
+      '--head',
+      branch,
+      '--limit',
+      String(PULL_LIMIT),
+      '--json',
+      'number,headRefName,isCrossRepository',
+    ])
+    if (stdout === undefined) return undefined
+
+    const pulls = parsePulls(stdout)
+    return pulls?.some((pull) => !pull.isCrossRepository)
+  }
+}
+
+export function liveReaders(root: string): LiveReaders {
+  return {
+    sessions: sessionHolders(root),
+    pulls: pullHolders(root),
+    merged: mergedBranches(root),
+  }
+}

package/src/tasks/validate.ts

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
+import { readFrontmatterSource } from '@/indexes/frontmatter'
 import { codeSpans, unbrokenRun } from '@/markdown/tables'
 import {
   archiveDir,
@@ -21,6 +22,8 @@ import {
   renderedLength,
   WAITING_LIMIT,
 } from '@/tasks/board'
+import { branchOfPlan } from '@/tasks/branch'
+import type { HolderReader, LiveReaders, MergedReader } from '@/tasks/holders'
 import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
 
 const ORDERING_FILE = 'priority.md'
@@ -61,6 +64,7 @@ export const FINDING_KINDS = [
   'row-untabled',
   'row-misordered',
   'row-unranked',
+  'row-held',
   'touches-unstated',
   'touches-stale',
   'columns-mismatched',
@@ -69,6 +73,7 @@ export const FINDING_KINDS = [
   'blocker-unresolved',
   'blocker-declined',
   'sessions-misshapen',
+  'frontmatter-invalid',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -177,6 +182,18 @@ export interface BoardRow {
   readonly cells: readonly string[]
 }
 
+/**
+ * What each source behind the held-row check answered. `unread` is a source the
+ * run asked and could not read, so a board carrying no `row-held` finding beside
+ * it is untested rather than clean. `not-asked` is a run without the live read.
+ */
+export type LiveState = 'read' | 'unread' | 'not-asked'
+
+export interface LiveReading {
+  readonly sessions: LiveState
+  readonly pulls: LiveState
+}
+
 export interface ValidateReport {
   readonly ok: true
   readonly rows: number
@@ -189,6 +206,7 @@ export interface ValidateReport {
   readonly shared: readonly SharedFiles[]
   readonly wide: readonly WideToken[]
   readonly unplaced: readonly Unplaced[]
+  readonly live: LiveReading
 }
 
 export interface ValidateRefused {
@@ -877,6 +895,34 @@ async function checkSessions(
   return found.filter((finding): finding is Finding => finding !== undefined)
 }
 
+/**
+ * Reports a task file whose frontmatter block will not parse, which the index
+ * regeneration would otherwise surface only after the row was placed. A file
+ * with no block is left alone, since the index walker owns that report.
+ */
+async function checkFrontmatter(
+  stems: readonly string[],
+  dir: string,
+): Promise<Finding[]> {
+  const found = await Promise.all(
+    stems.map(async (stem): Promise<Finding | undefined> => {
+      const reading = readFrontmatterSource(
+        await readFile(join(dir, `${stem}.md`), 'utf8'),
+      )
+      if (reading.kind !== 'invalid') return undefined
+
+      return {
+        kind: 'frontmatter-invalid',
+        group: undefined,
+        subject: stem,
+        message: `frontmatter is not valid YAML: ${reading.message}. Double any apostrophe inside the single-quoted title.`,
+      }
+    }),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
 /**
  * Tests the claim a group name makes about a plan. `## Needs a plan` says none
  * is live and `## Up next` says one is written, and neither group has a `Plan`
@@ -1611,6 +1657,95 @@ export async function groupRuleFindings(
   ]
 }
 
+/**
+ * Reports a row outside `## Run now` whose task a live session or an open pull
+ * request holds, tied through the branch each live plan on its `Plan:` line
+ * derives. A row whose worker renamed its branch has nothing to match, and an
+ * archived plan's branch is finished work, so neither is reported.
+ *
+ * A session outlives its merge, so a session still on a branch a merged pull
+ * request names is finished work too, until the merge reaches this clone and the
+ * hook archives the row. A merged read that fails leaves the hold standing, since
+ * the session is still there, and reads `pulls` as unread, since that hold may be
+ * finished work the open list could not rule out.
+ */
+async function checkHeld(
+  rows: readonly BoardRow[],
+  live: LiveRead,
+  dir: string,
+  root: string,
+): Promise<{ readonly findings: Finding[]; readonly mergedUnread: boolean }> {
+  let mergedUnread = false
+
+  const holdersOf = async (branch: string): Promise<string[]> => {
+    const session = live.sessions?.get(branch)
+    const merged = session ? await live.merged?.(branch) : false
+    if (merged === undefined) mergedUnread = true
+
+    return [session && !merged ? session : undefined, live.pulls?.get(branch)]
+      .filter((name): name is string => name !== undefined)
+      .map((name) => `${name} on ${branch}`)
+  }
+
+  const found = await Promise.all(
+    rows.map(async (row): Promise<Finding | undefined> => {
+      if (row.group === 'Run now' || !row.stem) return undefined
+      const file = join(dir, `${row.stem}.md`)
+      if (!existsSync(file)) return undefined
+
+      const targets = readPlanTargets(await readFile(file, 'utf8'))
+      const branches = targets.flatMap((target) => {
+        const path = target.split('#')[0] || target
+        return resolveLivePlan(path, dir, root) === undefined
+          ? []
+          : [branchOfPlan(path)]
+      })
+      const held = (await Promise.all(branches.map(holdersOf))).flat()
+      if (held.length === 0) return undefined
+
+      return {
+        kind: 'row-held',
+        group: row.group,
+        subject: row.stem,
+        message: `sits under ${row.group} and is held by ${held.join(' and ')}. A row with a worker belongs under Run now.`,
+      }
+    }),
+  )
+
+  return {
+    findings: found.filter(
+      (finding): finding is Finding => finding !== undefined,
+    ),
+    mergedUnread,
+  }
+}
+
+/** What each source answered, `undefined` where it was not asked or failed. */
+interface LiveRead {
+  readonly reading: LiveReading
+  readonly sessions?: Awaited<ReturnType<HolderReader>>
+  readonly pulls?: Awaited<ReturnType<HolderReader>>
+  readonly merged?: MergedReader
+}
+
+/** Takes each source once, since a failed read answers undefined rather than throws. */
+async function readLive(live: LiveReaders | undefined): Promise<LiveRead> {
+  if (!live) {
+    return { reading: { sessions: 'not-asked', pulls: 'not-asked' } }
+  }
+
+  const stateOf = (read: Awaited<ReturnType<HolderReader>>): LiveState =>
+    read ? 'read' : 'unread'
+  const [sessions, pulls] = await Promise.all([live.sessions(), live.pulls()])
+
+  return {
+    reading: { sessions: stateOf(sessions), pulls: stateOf(pulls) },
+    sessions,
+    pulls,
+    merged: live.merged,
+  }
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -1618,6 +1753,12 @@ function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
 export interface ValidateOptions {
   /** Overridden by tests, which supply the trunk rather than reaching for git. */
   readonly trunk?: TrunkReader
+  /**
+   * The roster and GitHub reads behind the held-row check. Absent by default,
+   * since the board's write hook runs this on every edit and a network read
+   * there costs every write.
+   */
+  readonly live?: LiveReaders
 }
 
 /**
@@ -1668,6 +1809,8 @@ export async function validateBoard(
     ? await listTaskStems(declinedPath)
     : []
   const parked = await checkParked(rows, root, trunk)
+  const live = await readLive(options.live)
+  const held = await checkHeld(rows, live, dir, root)
 
   const findings = [
     ...shapeFindings,
@@ -1675,10 +1818,12 @@ export async function validateBoard(
     ...(await groupRuleFindings(rows, root)),
     ...(await checkPlanAgreement(rows, dir, root)),
     ...(await checkSessions(rows, dir)),
+    ...(await checkFrontmatter(stems, dir)),
     ...(await checkStaleTouches(rows, root)),
     ...checkCellWidth(rows),
     ...checkOrdering(rows),
     ...parked.findings,
+    ...held.findings,
   ]
 
   return {
@@ -1693,5 +1838,8 @@ export async function validateBoard(
     shared: checkSharedFiles(rows),
     wide: checkWideTokens(rows),
     unplaced: checkUnplaced(rows, backlog, stems),
+    live: held.mergedUnread
+      ? { ...live.reading, pulls: 'unread' }
+      : live.reading,
   }
 }

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