@erclx/canon 5.25.0 → 5.27.0

package/src/commands/sandbox.ts

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
-import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   assertedPercent,
@@ -26,6 +25,8 @@ import {
   type RunEnvelope,
   type Verdict,
 } from '@/sandbox/expect'
+import { runHeadless } from '@/sandbox/headless/run'
+import { runSandbox } from '@/sandbox/provision'
 import { sandboxTree } from '@/sandbox/tree'
 import {
   frameError,
@@ -36,6 +37,7 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
@@ -69,11 +71,39 @@ function reportAbsentScenarioTree(): boolean {
   return true
 }
 
+/** Holds fixture content for scenarios rather than scenarios of its own. */
+const FIXTURES_DIR = 'fixtures'
+
 /**
- * Holds fixture content for scenarios rather than scenarios of its own.
- * Twin of the `-not -name fixtures` filter in `scripts/manage-sandbox.sh`.
+ * The provision verb takes positional words rather than options, since `reset`
+ * and `clean` share its slot with a target, so its usage is written out here
+ * rather than generated by commander.
  */
-const FIXTURES_DIR = 'fixtures'
+function showProvisionHelp(): void {
+  const { GREY, NC, WHITE } = palette(process.stdout)
+  const lines = [
+    `${GREY}┌${NC}`,
+    `${GREY}├${NC} ${WHITE}Usage:${NC} canon sandbox [cat:cmd]`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Arguments:${NC}`,
+    `${GREY}│${NC}    cat:cmd   ${GREY}# Scenario to provision (e.g. git:commit)${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
+    `${GREY}│${NC}    reset     ${GREY}# Reset sandbox to baseline${NC}`,
+    `${GREY}│${NC}    clean     ${GREY}# Wipe the sandbox${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Options:${NC}`,
+    `${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
+    `${GREY}│${NC}    canon sandbox`,
+    `${GREY}│${NC}    canon sandbox git:commit`,
+    `${GREY}│${NC}    canon sandbox reset`,
+    `${GREY}│${NC}    canon sandbox clean`,
+    `${GREY}└${NC}`,
+  ]
+  process.stdout.write(`${lines.join('\n')}\n`)
+}
 
 /** A run that reported nothing counts as clean, so only real signals fail. */
 const CLEAN_ENVELOPE: RunEnvelope = { isError: false, turns: 0, denials: 0 }
@@ -477,16 +507,78 @@ export function register(program: Command): void {
     .action(async (_opts: unknown, cmd: Command) => {
       if (reportAbsentScenarioTree()) return
 
-      const args = cmd.args
+      const mismatch = checkoutMismatchWarning(process.cwd())
+      if (mismatch !== undefined) logWarn(mismatch)
+
+      // `--no-header` is the frame opt-out for a caller that already opened
+      // one, which `canon sandbox run` and the picker below both do.
+      const isHeader = cmd.args[0] !== '--no-header'
+      const args = isHeader ? cmd.args : cmd.args.slice(1)
 
-      if (args.length === 0) {
-        const resolved = await interactivePicker()
-        await execScript('manage-sandbox.sh', ['--no-header', resolved])
-      } else {
-        await execScript('manage-sandbox.sh', args)
+      if (args[0] === '-h' || args[0] === '--help') {
+        showProvisionHelp()
+        return
       }
+
+      const target = args[0] ?? (await interactivePicker())
+      process.exitCode = await runSandbox(PROJECT_ROOT, {
+        isHeader: isHeader && args[0] !== undefined,
+        target,
+        arm: args[1] === '' ? undefined : args[1],
+      })
     })
 
+  sandbox
+    .command('run')
+    .description(
+      'Provision a scenario, drive one claude -p session over it, and print the envelope with its verdict',
+    )
+    .argument('[target]', 'Scenario as <category>:<command>, e.g. git:commit')
+    .argument('[prompt]', 'Skill invocation, e.g. "/canon:git-commit"')
+    .argument('[arm]', 'Named scenario arm, e.g. small')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Env overrides:',
+        '  CANON_SKILL_TEST_MODEL            default sonnet',
+        '  CANON_SKILL_TEST_TOOLS            default Bash,Read,Glob,Grep,Edit,Write',
+        '  CANON_SKILL_TEST_MAX_TURNS        default 30',
+        '  CANON_SKILL_TEST_PERMISSION_MODE  default bypassPermissions',
+        '',
+        'Examples:',
+        '  canon sandbox run git:commit "/canon:git-commit"',
+        '  canon sandbox run claude:plan-feature "/canon:plan-feature add a widget" small',
+        '',
+        'Bills a real session through the claude binary on PATH.',
+        'Exit codes: the verdict, 1 when the envelope does not parse, or the',
+        'provisioning or session code when either stops the run first.',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        target: string | undefined,
+        prompt: string | undefined,
+        arm: string | undefined,
+        _opts: unknown,
+        cmd: Command,
+      ) => {
+        if (target === undefined) {
+          cmd.help()
+          return
+        }
+        if (reportAbsentScenarioTree()) return
+
+        process.exitCode = await runHeadless({
+          projectRoot: PROJECT_ROOT,
+          target,
+          prompt,
+          arm,
+        })
+      },
+    )
+
   sandbox
     .command('check')
     .description('Check a provisioned sandbox against a scenario expectation')
@@ -588,7 +680,7 @@ export function register(program: Command): void {
         '  canon sandbox equivalence claude --json',
         '  canon sandbox equivalence claude:plan-feature --base origin/main',
         '',
-        'Provisions offline only and never runs sandbox/run.sh or a claude binary.',
+        'Provisions offline only and never runs canon sandbox run or a claude binary.',
         '--stub-remote also runs the anchor arms, and wins over --include-anchor.',
         'Exit codes: 0 when every compared arm is identical or red the same way',
         'on both sides, 1 on any difference, exit mismatch, or enumeration error.',

package/src/commands/sessions.ts

@@ -24,7 +24,7 @@ import {
   pipeOutput,
   plural,
 } from '@/ui'
-import { mainWorktreeRoot } from '@/worktree'
+import { mainWorktreeRoot } from '@/git/worktree'
 
 interface ListCommandOptions {
   readonly json?: boolean

package/src/commands/slides.ts

@@ -1,14 +1,13 @@
-import { existsSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { INSTALL_BROWSER } from '@/browser/engine'
 import { creationRel, SCRATCH } from '@/record-root'
-import { LAYOUTS } from '@/slides/layouts'
+import { listDecks, resolveDeck, SLIDES_FOLDER } from '@/slides/decks'
 import { openDeck } from '@/slides/open'
-import { renderSlidesDoc } from '@/slides/render'
-import type { Variant } from '@/slides/styles'
 import { intro, outro, palette } from '@/ui'
 
+const SLIDES_AT = creationRel(process.cwd(), SLIDES_FOLDER)
+
 export function register(program: Command): void {
   const slides = program
     .command('slides')
@@ -19,77 +18,34 @@ export function register(program: Command): void {
     .command('render')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Render a SLIDES.md source, or a folder of HTML slides, into a PowerPoint deck',
+      `Render a deck under ${SLIDES_AT}/, or a folder of HTML slides, into a PowerPoint deck`,
     )
-    .option(
-      '-s, --source <path>',
-      'Source SLIDES.md file, or a folder of .html slides read in filename order',
-      '.claude/SLIDES.md',
+    .argument(
+      '[deck]',
+      'Deck name or folder, defaulting to the only deck when there is one',
     )
     .option(
       '-o, --out <path>',
       'Output directory',
       creationRel(process.cwd(), SCRATCH, 'render', 'slides'),
     )
-    .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(
       '-m, --mirror <path>',
       'Copy the deck to this directory after writing',
     )
     .option('--open', 'Open the deck after writing')
     .action(
-      async (opts: {
-        source: string
-        out: string
-        variant?: string
-        mirror?: string
-        open?: boolean
-      }) => {
+      async (
+        deck: string | undefined,
+        opts: { out: string; mirror?: string; open?: boolean },
+      ) => {
         try {
-          const sourcePath = resolve(process.cwd(), opts.source)
-          const outDir = resolve(process.cwd(), opts.out)
-          if (!existsSync(sourcePath)) {
-            fail(`${opts.source} not found`)
-          }
+          const root = process.cwd()
+          const resolved = resolveDeck(root, deck)
+          if (resolved.status === 'refused') fail(resolved.message)
+          const outDir = resolve(root, opts.out)
           const mirror = resolveMirror(opts.mirror)
-          if (statSync(sourcePath).isDirectory()) {
-            if (opts.variant !== undefined) {
-              fail('--variant applies to a SLIDES.md source, not a folder')
-            }
-            await renderHtmlFolder(sourcePath, outDir, mirror, opts.open)
-            return
-          }
-          const variant = parseVariant(opts.variant)
-          const { GREEN, GREY, NC, RED } = palette(process.stderr)
-          intro('Render slides')
-          const result = await renderSlidesDoc(sourcePath, outDir, {
-            variant,
-            mirror,
-          })
-          process.stderr.write(
-            `${GREY}│${NC} ${GREEN}✓${NC} ${result.slideCount} slides\n${GREY}│${NC} ${GREEN}✓${NC} ${result.pptxPath}\n`,
-          )
-          const validNames = LAYOUTS.map((layout) => layout.name).join(', ')
-          for (const { value, slideNumbers } of result.unrecognizedLayouts) {
-            const noun = slideNumbers.length === 1 ? 'slide' : 'slides'
-            process.stderr.write(
-              `${GREY}│${NC} ${RED}✗${NC} unrecognized layout "${value}" on ${noun} ${slideNumbers.join(', ')}. Valid layouts: ${validNames}\n`,
-            )
-          }
-          if (result.mirrorPath) {
-            process.stderr.write(
-              `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,
-            )
-          }
-          if (opts.open) {
-            const target = result.mirrorPath ?? result.pptxPath
-            const opened = await openDeck(target)
-            const mark = opened ? `${GREEN}✓${NC}` : `${RED}✗${NC}`
-            process.stderr.write(
-              `${GREY}│${NC} ${mark} ${opened ? 'opened' : 'could not open'} ${target}\n`,
-            )
-          }
-          outro()
+          await renderHtmlFolder(resolved.dir, outDir, mirror, opts.open)
         } catch (error) {
           reportFailure(error)
         }
@@ -99,18 +55,23 @@ export function register(program: Command): void {
   slides
     .command('list')
     .helpOption('-h, --help', 'Show this help message')
-    .description('List the available slide layouts')
-    .option('--json', 'Output the layout catalog as JSON')
+    .description(`List the decks under ${SLIDES_AT}/`)
+    .option('--json', 'Output the decks as JSON')
     .action((opts: { json?: boolean }) => {
+      const decks = listDecks(process.cwd())
       if (opts.json) {
-        process.stdout.write(`${JSON.stringify(LAYOUTS)}\n`)
+        process.stdout.write(`${JSON.stringify(decks)}\n`)
         return
       }
       const { GREEN, GREY, NC } = palette(process.stderr)
-      intro('Slide layouts')
-      for (const layout of LAYOUTS) {
+      intro('Slide decks')
+      if (decks.length === 0) {
+        process.stderr.write(`${GREY}│${NC} No deck under ${SLIDES_AT}/\n`)
+      }
+      for (const { name, title, slides: count, path } of decks) {
+        const noun = count === 1 ? 'slide' : 'slides'
         process.stderr.write(
-          `${GREY}│${NC} ${GREEN}✓${NC} ${layout.name}  ${GREY}${layout.description}${NC}\n`,
+          `${GREY}│${NC} ${GREEN}✓${NC} ${name}  ${GREY}${title}, ${count} ${noun}, ${path}${NC}\n`,
         )
       }
       outro()
@@ -121,8 +82,7 @@ export function register(program: Command): void {
  * The converter loads on demand, so no other command resolves pptxgenjs,
  * jszip, or the token module at startup. A fallback, a refused link, chart, or
  * effect, or a token the master fell back on reports one line each and keeps
- * the exit at 0, as an unrecognized layout does on the markdown path, since the
- * deck is written either way. A malformed `deck.json` refuses before any slide is laid
+ * the exit at 0, since the deck is written either way. A malformed `deck.json` refuses before any slide is laid
  * out and exits 1.
  */
 async function renderHtmlFolder(
@@ -192,12 +152,6 @@ async function renderHtmlFolder(
   outro()
 }
 
-function parseVariant(value: string | undefined): Variant | undefined {
-  if (value === undefined) return undefined
-  if (value === 'light' || value === 'dark') return value
-  fail(`Invalid variant "${value}". Use light or dark.`)
-}
-
 function resolveMirror(value: string | undefined): string | undefined {
   const mirror = value ?? process.env.CANON_SLIDES_MIRROR
   return mirror ? resolve(process.cwd(), mirror) : undefined
@@ -205,9 +159,9 @@ function resolveMirror(value: string | undefined): string | undefined {
 
 /**
  * Carries a fail-fast message from a validation helper to the action that
- * called it. `fail` has to keep its `never` return, since that is what makes
- * `parseVariant` exhaustive to the compiler, and a helper deep in the call
- * stack cannot set `process.exitCode` and unwind on its own.
+ * called it. `fail` keeps its `never` return so the compiler narrows past it,
+ * and a helper deep in the call stack cannot set `process.exitCode` and unwind
+ * on its own.
  */
 class SlidesError extends Error {}
 

package/src/commands/sync.ts

@@ -20,7 +20,7 @@ import {
 } from '@/sync/target'
 import type { UnclaimedFolder } from '@/sync/reverse'
 import { runGitWorkflow } from '@/sync/workflow'
-import { resolveTarget } from '@/target'
+import { resolveTarget } from '@/targets/validate'
 import {
   intro,
   isNonInteractive,

package/src/commands/tasks.ts

@@ -1,7 +1,7 @@
 import { relative } from 'node:path'
 import type { Command } from 'commander'
 import { execa } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { type AnswersOutcome, planAnswers } from '@/tasks/answers'
 import { type BranchOutcome, planBranch } from '@/tasks/branch'
 import {
@@ -59,7 +59,7 @@ import {
   outro,
   pipeOutput,
 } from '@/ui'
-import { mainWorktreeRoot } from '@/worktree'
+import { mainWorktreeRoot } from '@/git/worktree'
 
 /** Returned when the board carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2

package/src/commands/teach.ts

@@ -43,7 +43,7 @@ import {
   outro,
   pipeOutput,
 } from '@/ui'
-import { mainWorktreeRoot } from '@/worktree'
+import { mainWorktreeRoot } from '@/git/worktree'
 
 /**
  * A pair as the command line spells it, split on the first `=` so a value

package/src/commands/transcripts.ts

@@ -3,7 +3,7 @@ import type { Command } from 'commander'
 import { recordDir } from '@/record-root'
 import { ensureYtDlp, fetchOne } from '@/transcripts/fetch'
 import { palette } from '@/ui'
-import { mainWorktreeRoot } from '@/worktree'
+import { mainWorktreeRoot } from '@/git/worktree'
 
 interface TranscriptOptions {
   out?: string

package/src/commands/worktrees.ts

@@ -16,7 +16,7 @@ import {
   type Unreadable,
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
-import { mainWorktreeRoot } from '@/worktree'
+import { mainWorktreeRoot } from '@/git/worktree'
 import { repairBareFlag } from '@/worktrees/bare-flag'
 import {
   removeReclaimable,

package/src/comments/scan.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
-import { listIgnored } from '@/git-ignore'
+import { listIgnored } from '@/git/ignore'
 
 export type Language = 'ts' | 'sh'
 

package/src/comments/trend.ts

@@ -1,5 +1,5 @@
 import { $ } from 'bun'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import {
   countFiles,
   isPruned,

package/src/context/audit.ts

@@ -4,7 +4,7 @@ import { BARE_NAME, IGNORE_MARKER } from '@/context/citations'
 import type { AuditedFolder } from '@/context/folders'
 import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
 import { documentHeight } from '@/markdown/structure'
-import { isStubSeed } from '@/seed-marker'
+import { isStubSeed } from '@/tooling/seed-marker'
 
 /**
  * Checkpoint quoted from the standard stating it. It is not a cap.

package/src/context/citations.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
-import { listRepositoryFiles } from '@/git-files'
+import { listRepositoryFiles } from '@/git/files'
 import { RECORD_ROOTS } from '@/record-root'
 import { SURFACE_ROOTS } from '@/surface-root'
 

package/src/context/classify/extract.ts

@@ -2,8 +2,8 @@ import { existsSync, readFileSync } from 'node:fs'
 import { basename, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { resolveFolders } from '@/context/folders'
-import { gitEnv } from '@/git-env'
-import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { gitEnv } from '@/git/env'
+import { listChangedFiles, resolveBaseRef } from '@/git/files'
 import { surfaceDir } from '@/surface-root'
 
 /**