@erclx/canon 5.78.0 → 5.80.0

package/src/commands/pr.ts

@@ -113,6 +113,7 @@ import {
   type LocalRefusal,
   type LocalRunner,
 } from '@/pr/local'
+import { linkKeyChanges } from '@/pr/links'
 import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
@@ -161,6 +162,7 @@ const GH_TIMEOUT_MS = 30_000
 const UNNAMED_PRINT_LIMIT = 10
 
 interface KeyChangesOptions {
+  readonly link?: boolean
   readonly body?: string
   readonly base?: string
   readonly root?: string
@@ -279,7 +281,7 @@ const LOCAL_REFUSALS: Record<
     'Nothing listening inside this worktree served an HTML page. Start the dev server here and re-run to get a link.',
   unhealthy:
     'A page answered inside this worktree, but a health path it declares failed. Start what the page reaches and re-run to get a link.',
-  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run.`,
+  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run. health takes paths starting with /, and page-only takes folders relative to the repository.`,
   'no-listener-reader':
     'This machine offers neither lsof nor /proc, so no listening socket could be read. Nothing is posted.',
   'gh-failed':
@@ -503,13 +505,17 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option(
       '--body <path>',
-      'Read the body from a file rather than the API, ignoring any number',
+      'Read the body from a file rather than the API, ignoring any number except the one --link needs',
     )
     .option(
       '--base <ref>',
       'Far side of the range when --body supplies the body',
     )
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option(
+      '--link',
+      `Print the body with each ## ${KEY_CHANGES} path linked to its diff, needing a number`,
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -538,6 +544,13 @@ export function register(program: Command): void {
         'points the change at a locative the path does not name. Read the bullet on',
         "the record's preview before filing an unmet path as a stale claim.",
         '',
+        '--link prints the body and nothing else, with every path the section',
+        'names that the diff changes written as a link to its row in the Files',
+        'tab. The anchor is `diff-` and the SHA-256 of the path. Pass the pull',
+        'request number, since the link needs it. It also rewrites the anchor',
+        'of a link opening another file, and a plain run reports that link as',
+        "mislinked when its label is a changed path and its anchor hashes another's.",
+        '',
         'Refusals, read off `reason`:',
         '  no-section          the body carries no `## Key changes` heading, so it',
         '                      claims nothing',
@@ -555,14 +568,18 @@ export function register(program: Command): void {
         '  gh-missing          `gh` is not on the path, so no pull request could be',
         '                      resolved',
         '  gh-failed           `gh` could not answer for this repository or branch',
+        '  no-number           --link was given with no pull request number',
+        '  no-repo-url         --link could not read the repository address',
+        '  link-json           --link was given with --json, though it prints the body',
         '',
         'Exit codes:',
-        '  0  every claimed path is in the diff',
+        '  0  every claimed path is in the diff, and every link opens its own file',
         '  1  refused, with the reason on stderr or in the JSON record',
-        '  2  at least one claimed path is absent from the diff',
+        '  2  a claimed path is absent from the diff, or a link opens another file',
         '',
         'Examples:',
         '  canon pr key-changes',
+        '  canon pr key-changes 1265 --link --body .canon/tmp/body.md',
         '  canon pr key-changes 1265 --json',
         '  canon pr key-changes --body .canon/tmp/body.md --base origin/main',
         '',
@@ -1301,6 +1318,15 @@ export function register(program: Command): void {
         "refusal names the lowest page port's first failing path. An absent",
         'file or an empty list checks the page alone.',
         '',
+        'A page served by a static server answers none of those paths, so',
+        'page-only = ["web"] lists repository-relative folders whose',
+        'listeners skip them and are found on the page probe alone. The match',
+        "reads the listener's working directory on whole path segments, so web",
+        'does not cover webapp, and a server started from the root with a',
+        'working-directory flag still takes the health check. Keep health',
+        'beside page-only until the binary a project runs carries this key,',
+        'since an older one refuses a file holding page-only alone.',
+        '',
         'A process in a sibling worktree, in the main checkout seen from a',
         'linked worktree, or in a linked worktree seen from the main checkout',
         'is never reported, since its server shows another branch. Sockets are',
@@ -1326,8 +1352,9 @@ export function register(program: Command): void {
         '  unhealthy           a page answered but a declared health path did',
         '                      not, with `port`, `path`, and `status`, which',
         '                      is null on a timeout',
-        '  invalid-config      canon/config/local.toml is not valid TOML, or',
-        '                      health is not a list of paths starting with /',
+        '  invalid-config      canon/config/local.toml is not valid TOML,',
+        '                      health is not a list of paths starting with /,',
+        '                      or page-only is not a list of relative folders',
         '  removed             --remove dropped the line',
         '  no-comment          --remove found no marked comment, a no-op',
         '  no-line             --remove found no address line, a no-op',
@@ -1865,6 +1892,8 @@ async function runKeyChanges(
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
 
+  if (opts.link === true) return runKeyChangesLink(number, opts, root)
+
   intro('canon pr key-changes')
 
   const source =
@@ -1949,6 +1978,14 @@ async function runKeyChanges(
     for (const claim of report.unresolved) logInfo(claim.path)
   }
 
+  if (report.mislinked.length > 0) {
+    logStep('Mislinked')
+    logWarn(
+      `${plural(report.mislinked.length, 'link')} open another file's diff than the path they name. Re-run with --link to print the body with them corrected.`,
+    )
+    for (const link of report.mislinked) logWarn(link.path)
+  }
+
   outro()
 
   if (emitJson) {
@@ -1966,11 +2003,71 @@ async function runKeyChanges(
         incidental: report.incidental,
         unresolved: report.unresolved,
         evidenceUnread: report.evidenceUnread,
+        mislinked: report.mislinked,
       })}\n`,
     )
   }
 
-  return report.unmet.length === 0 ? 0 : 2
+  return report.unmet.length === 0 && report.mislinked.length === 0 ? 0 : 2
+}
+
+/**
+ * Prints the body with each changed path in `## Key changes` linked to its
+ * diff, and nothing else, so stdout pipes straight into a body file.
+ *
+ * Skips the frame `intro` opens, which would land in the piped body. Refusals
+ * keep the framed shape on stdout like every other mode.
+ */
+async function runKeyChangesLink(
+  number: string | undefined,
+  opts: KeyChangesOptions,
+  root: string,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (emitJson) {
+    return refuseWith(
+      'link-json',
+      '--link prints the body itself, so it takes no --json record.',
+      emitJson,
+      root,
+    )
+  }
+
+  const source =
+    opts.body === undefined
+      ? await readFromApi(root, number)
+      : await readFromFile(root, process.cwd(), opts.body, opts.base)
+  if (source.kind === 'refused') return refuse(source.reason, emitJson, root)
+
+  const pull = number ?? source.source.number?.toString()
+  if (pull === undefined) {
+    return refuseWith(
+      'no-number',
+      'The link needs the pull request number, so pass it as the argument.',
+      emitJson,
+      root,
+    )
+  }
+
+  const url = await readRepoUrl(root)
+  if (url === undefined) {
+    return refuseWith(
+      'no-repo-url',
+      'gh could not read the repository address, so no link was built.',
+      emitJson,
+      root,
+    )
+  }
+
+  process.stdout.write(
+    linkKeyChanges(
+      source.source.body,
+      source.source.changed,
+      `${url}/pull/${pull}/files`,
+    ),
+  )
+  return 0
 }
 
 type IdentityRead =
@@ -2494,14 +2591,18 @@ interface PullFiles {
   readonly present: ReadonlyMap<string, boolean>
   /** Each path the pull request removed, which a deploy's push filter still counts. */
   readonly removed: readonly string[]
+  /** Each renamed path mapped to the path it sat at before the pull request. */
+  readonly renamedFrom: ReadonlyMap<string, string>
 }
 
 /**
  * The paths a pull request changed, read through the paginated files endpoint
  * so the set is the same from any checkout and never capped at the first
- * view. `renamed` and `copied` count as added, since the new path has no
- * counterpart at the merge base. Returns undefined when the read fails, which
- * refuses rather than rendering a short set.
+ * view. `copied` counts as added, since a copy leaves its source in place and
+ * has no single base. `renamed` counts as added in `present` too, so the
+ * changed set stays the same, and `renamedFrom` carries the old path of each
+ * rename for a reader that compares against the base. Returns undefined when
+ * the read fails, which refuses rather than rendering a short set.
  */
 async function listPullFiles(
   cwd: string,
@@ -2512,18 +2613,22 @@ async function listPullFiles(
     '--paginate',
     `repos/{owner}/{repo}/pulls/${number}/files`,
     '--jq',
-    '.[] | [.status, .filename] | @tsv',
+    '.[] | [.status, .filename, (.previous_filename // "")] | @tsv',
   ])
   if (stdout === null) return undefined
   const present = new Map<string, boolean>()
   const removed: string[] = []
+  const renamedFrom = new Map<string, string>()
   for (const line of stdout.split('\n').filter(Boolean)) {
-    const [status, path] = line.split('\t')
+    const [status, path, previous] = line.split('\t')
     if (status === undefined || path === undefined) continue
     if (status === 'removed') removed.push(path)
     else present.set(path, status !== 'modified' && status !== 'changed')
+    if (status === 'renamed' && previous !== undefined && previous !== '') {
+      renamedFrom.set(path, previous)
+    }
   }
-  return { present, removed }
+  return { present, removed, renamedFrom }
 }
 
 function everyChangedPath(files: PullFiles): string[] {
@@ -2671,13 +2776,14 @@ async function measureItem(
   head: string,
 ): Promise<MeasuredItem> {
   const headRead = await readImage(cwd, item.path, head)
+  const basePath = item.basePath ?? item.path
   const baseRead =
     item.added || base === undefined
       ? undefined
-      : await readImage(cwd, item.path, base)
+      : await readImage(cwd, basePath, base)
   const unread = [
     ...(headRead.kind === 'failed' ? [`head:${item.path}`] : []),
-    ...(baseRead?.kind === 'failed' ? [`base:${item.path}`] : []),
+    ...(baseRead?.kind === 'failed' ? [`base:${basePath}`] : []),
   ]
   const headBytes = headRead.kind === 'read' ? headRead.bytes : undefined
   const baseBytes = baseRead?.kind === 'read' ? baseRead.bytes : undefined
@@ -2691,6 +2797,9 @@ async function measureItem(
       ...(headBytes !== undefined &&
         baseBytes !== undefined && {
           withinTolerance: isWithinTolerance(baseBytes, headBytes),
+          ...(item.basePath !== undefined && {
+            identical: Buffer.from(baseBytes).equals(headBytes),
+          }),
         }),
     },
     unread,
@@ -2811,6 +2920,7 @@ async function runEvidence(
   const grouped = await groupEvidence(
     [...pullFiles.present.keys()],
     async (path) => pullFiles.present.get(path) === false,
+    pullFiles.renamedFrom,
   )
   const uncaptured = readUncaptured(
     everyChangedPath(pullFiles),
@@ -3412,6 +3522,7 @@ async function runLocal(opts: LocalOptions): Promise<number> {
     worktree,
     machineLocalRunner(),
     declaration.kind === 'paths' ? declaration.paths : [],
+    declaration.pageOnly,
   )
   if (result.kind === 'refused' && result.reason === 'unhealthy') {
     const { port, path, status } = result
@@ -4028,6 +4139,18 @@ async function readRepoName(root: string): Promise<string | undefined> {
   }
 }
 
+/** The repository's web address off the REST repository read, for the same reason as `readRepoName`. */
+async function readRepoUrl(root: string): Promise<string | undefined> {
+  const row = await gh(root, ['api', 'repos/{owner}/{repo}'])
+  if (row === null) return undefined
+  try {
+    const url = (JSON.parse(row) as { html_url?: unknown }).html_url
+    return typeof url === 'string' && url !== '' ? url : undefined
+  } catch {
+    return undefined
+  }
+}
+
 async function runFrames(
   number: string | undefined,
   opts: FramesOptions,

package/src/commands/sessions.ts

@@ -11,6 +11,7 @@ import {
   type SessionReport,
   selfOf,
 } from '@/sessions/resolve'
+import { readStop, type StopReading } from '@/sessions/stop'
 import {
   type Behind,
   exportSession,
@@ -32,8 +33,11 @@ interface ListCommandOptions {
   readonly branch?: string
   readonly repository?: string
   readonly self?: boolean
+  readonly stopped?: boolean
 }
 
+type ListedSession = ResolvedSession & StopReading
+
 const REASONS: Record<string, string> = {
   'not-a-repository': 'working outside any git repository',
   'detached-head': 'detached HEAD, so the worktree holds no branch name',
@@ -67,6 +71,7 @@ export function register(program: Command): void {
       '--self',
       "Report the caller's own row, and refuse where the roster holds none",
     )
+    .option('--stopped', 'Report only the sessions a usage limit stopped')
     .addHelpText(
       'after',
       [
@@ -161,12 +166,30 @@ export function register(program: Command): void {
         'framed listing renders the same dwell beside the status, at the',
         'coarsest unit that keeps it a whole number.',
         '',
+        'Each row also carries "stopped" and "stopResets", read from the tail of',
+        'the session transcript. "stopped" is "usage-limit" when the last',
+        'assistant entry is a limit stop, passing over a synthetic entry with no',
+        'error, such as the one a client restart writes. "stopResets" holds the',
+        'text the client wrote after "resets", or null when it wrote none.',
+        '"stopped" is "unknown" when the transcript could not be read or a',
+        'limit-worded entry has another shape, so the row may be stopped, and',
+        'null otherwise. A "busy" row reads',
+        'null without opening its transcript, since a turn is running.',
+        '',
+        '--stopped keeps the "usage-limit" rows after --branch and --self apply.',
+        'It drops "unknown" rows, and "stopsUnread" counts them before it does,',
+        'so a count above zero means a row here may be stopped and is not listed.',
+        '"foreignDead" above zero leaves the same doubt about a session this',
+        'reader could not check, and an empty result says so on stderr.',
+        'An empty result exits 0. "claimed" still reads the whole roster.',
+        '',
         'Examples:',
         '  canon sessions list',
         '  canon sessions list --json',
         '  canon sessions list --branch feat/parser --json',
         '  canon sessions list --branch chore/agents --repository ../caret --json',
         '  canon sessions list --self --json',
+        '  canon sessions list --stopped --json',
         '',
       ].join('\n'),
     )
@@ -477,15 +500,37 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     ? await checkClaim(opts.branch, { cwd: at, resolve: async () => report })
     : null
 
+  const read: readonly ListedSession[] = shown.map((session) => ({
+    ...session,
+    ...readStop(session),
+  }))
+  const stopsUnread = read.filter(
+    (session) => session.stopped === 'unknown',
+  ).length
+  const listed = opts.stopped
+    ? read.filter((session) => session.stopped === 'usage-limit')
+    : read
+
   intro('canon sessions list')
-  reportConfidence(shown, report)
+  reportConfidence(listed, report)
   reportSessions(
-    shown,
+    listed,
     opts.branch,
     repository,
     own !== null,
     report.foreignDead,
+    opts.stopped ? stopsUnread : null,
   )
+  if (opts.stopped && stopsUnread > 0) {
+    logWarn(
+      `${plural(stopsUnread, 'row')} could not be read and may be stopped, so this list can be short.`,
+    )
+  }
+  if (opts.stopped && own === null && report.foreignDead > 0) {
+    logWarn(
+      `${report.foreignDead} records from another pid namespace have no answering socket, so a stopped session may be missing from this list.`,
+    )
+  }
   if (claim) reportClaim(claim)
   outro()
 
@@ -494,8 +539,9 @@ async function runList(opts: ListCommandOptions): Promise<number> {
       `${JSON.stringify({
         dir: report.dir,
         // Over the rows shown, so an unrelated row --branch dropped cannot weaken it.
-        confidence: confidenceOf(shown),
+        confidence: confidenceOf(listed),
         foreignDead: report.foreignDead,
+        stopsUnread,
         branch: opts.branch ?? null,
         repository,
         worktree: claim?.worktree ?? null,
@@ -503,7 +549,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
         claimed: claim?.claimed ?? null,
         sessionsReadable: claim?.sessionsReadable ?? null,
         refsReadable: claim?.refsReadable ?? null,
-        sessions: shown,
+        sessions: listed,
       })}\n`,
     )
   }
@@ -578,11 +624,12 @@ function reportConfidence(
 }
 
 function reportSessions(
-  sessions: readonly ResolvedSession[],
+  sessions: readonly ListedSession[],
   branch: string | undefined,
   repository: string | null,
   scoped: boolean,
   foreignDead: number,
+  stopsUnread: number | null,
 ): void {
   logStep('Sessions')
 
@@ -596,6 +643,11 @@ function reportSessions(
   // was narrowed to one row before the branch filter ran. Reporting the wider
   // answer there would claim a reading this run never took.
   if (sessions.length === 0) {
+    if (stopsUnread !== null) {
+      logInfo(noneStopped(branch, scoped, foreignDead, stopsUnread))
+      return
+    }
+
     if (branch) {
       logInfo(
         scoped
@@ -630,12 +682,42 @@ function reportSessions(
           `unresolved: ${REASONS[session.unresolved ?? ''] ?? 'unknown'}`
         const dwell = formatDwell(session.statusDwellMs)
         const status = dwell ? `${session.status} ${dwell}` : session.status
-        return `${session.name}  ${status}  ${held}\n  ${session.cwd}`
+        return [
+          `${session.name}  ${status}  ${held}`,
+          `  ${session.cwd}`,
+          ...stopLine(session),
+        ].join('\n')
       })
       .join('\n'),
   )
 }
 
+/**
+ * Words an empty `--stopped` result by what was read, since "no session is
+ * stopped" is a claim about the machine that a row this run could not read, or
+ * a record it could not check, leaves open.
+ */
+function noneStopped(
+  branch: string | undefined,
+  scoped: boolean,
+  foreignDead: number,
+  stopsUnread: number,
+): string {
+  if (stopsUnread > 0 || (!scoped && foreignDead > 0)) {
+    return 'No session this reader could check is stopped.'
+  }
+  if (scoped) return 'This session is not stopped.'
+  return branch
+    ? `No session holding ${branch} is stopped.`
+    : 'No session is stopped.'
+}
+
+function stopLine(session: StopReading): string[] {
+  if (session.stopped === null) return []
+  const resets = session.stopResets ? `, resets ${session.stopResets}` : ''
+  return [`  stopped: ${session.stopped}${resets}`]
+}
+
 /**
  * Renders the dwell at the coarsest unit that keeps it a whole number, since a
  * reader scanning a roster wants an age at a glance rather than a millisecond

package/src/commands/tasks.ts

@@ -72,6 +72,7 @@ import {
   type ValidateOutcome,
   validateBoard,
 } from '@/tasks/validate'
+import { liveReaders } from '@/tasks/holders'
 import {
   intro,
   logAdd,
@@ -110,6 +111,7 @@ interface DeclineCommandOptions {
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
+  readonly live?: boolean
 }
 
 interface CitationsCommandOptions {
@@ -323,6 +325,10 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .option(
+      '--live',
+      'Also read the session roster and open pull requests for held rows',
+    )
     .addHelpText(
       'after',
       [
@@ -338,6 +344,12 @@ export function register(program: Command): void {
         `  no Waiting on cell renders past ${WAITING_LIMIT} characters`,
         '  a blocker citing a bare vNNN.N label settles like a linked one',
         '  a file two Run now rows share is listed, never failed',
+        '  with --live, no Up next or Needs a plan row is held by a live session',
+        "  or an open pull request on its plan's branch",
+        '',
+        'The `live` field states each --live source as read, unread, or not-asked.',
+        'A source that fails reads as unread and moves no exit code, so read that',
+        'field rather than taking exit 0 as clean. A run without --live reads neither.',
         '',
         'Refusals, read off `reason`:',
         '  no-board     the repository holds no `.canon/tasks/` board',
@@ -356,6 +368,7 @@ export function register(program: Command): void {
         'Examples:',
         '  canon tasks validate',
         '  canon tasks validate --json',
+        '  canon tasks validate --live --json',
         '',
       ].join('\n'),
     )
@@ -1911,7 +1924,10 @@ function reportNextLabel(
 
 async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await validateBoard(root)
+  const outcome = await validateBoard(
+    root,
+    opts.live ? { live: liveReaders(root) } : {},
+  )
 
   return reportValidation(outcome, opts.json ?? false, root)
 }
@@ -2390,8 +2406,30 @@ function reportValidation(
     } else {
       for (const task of outcome.unplaced) logWarn(describeUnplaced(task))
     }
-    outro()
+
+    if (outcome.live.sessions !== 'not-asked') {
+      logStep('Held rows')
+      if (
+        outcome.live.sessions === 'read' &&
+        outcome.live.pulls === 'read' &&
+        !outcome.findings.some((finding) => finding.kind === 'row-held')
+      ) {
+        logInfo('no row outside run now is held by a session or a pull request')
+      }
+    }
+  }
+
+  // Unread is a warning in both modes, since diagnostics reach stderr with --json too.
+  if (outcome.live.sessions === 'unread') {
+    logWarn('the session roster could not be read, so no session was checked')
   }
+  if (outcome.live.pulls === 'unread') {
+    logWarn(
+      'pull requests could not be read, so a hold may be missed or already merged',
+    )
+  }
+
+  if (!emitJson) outro()
 
   if (emitJson) {
     process.stdout.write(
@@ -2408,6 +2446,7 @@ function reportValidation(
         shared: outcome.shared,
         wide: outcome.wide,
         unplaced: outcome.unplaced,
+        live: outcome.live,
       })}\n`,
     )
   }

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
 }
 
 /**