@erclx/canon 4.118.0 → 4.120.0

package/src/commands/pr.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { readdir, readFile, readlink, realpath } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
@@ -28,11 +28,21 @@ import {
 import {
   findEvidenceChecklist,
   findEvidenceCommentId,
+  findEvidenceLocal,
   findEvidencePreview,
   groupEvidence,
   renderEvidenceBody,
 } from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
+import {
+  findLocalServer,
+  type Listener,
+  type LocalRefusal,
+  type LocalRunner,
+  parseLsofListeners,
+  parseProcNetTcp,
+  stripLocalLine,
+} from '@/pr/local'
 import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
@@ -76,6 +86,28 @@ interface ReadOptions {
 interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
   readonly checklist?: string
+  readonly local?: string
+}
+
+interface LocalOptions extends ReadOptions {
+  readonly remove?: boolean
+  readonly note?: string
+}
+
+/** What replaces the local address line once the pull request closes. */
+const LOCAL_REMOVED_NOTE =
+  '_Local preview removed when the pull request closed._'
+
+/** How long the probe waits on a listener before reading it as not a server. */
+const LOCAL_PROBE_TIMEOUT_MS = 2_000
+
+const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
+  'no-server':
+    'Nothing listening inside this worktree served an HTML page. Start the dev server here and re-run to get a link.',
+  'no-listener-reader':
+    'This machine offers neither lsof nor /proc, so no listening socket could be read. Nothing is posted.',
+  'gh-failed':
+    'gh could not read or edit the marked comment on this pull request.',
 }
 
 interface PreviewOptions extends ReadOptions {
@@ -387,6 +419,10 @@ export function register(program: Command): void {
       '--checklist <path>',
       'Close the body with this visual checklist file, from canon:ui-checklist',
     )
+    .option(
+      '--local <url>',
+      "Add this worktree's running server under any preview line, from canon pr local",
+    )
     .addHelpText(
       'after',
       [
@@ -419,6 +455,13 @@ export function register(program: Command): void {
         'image still reports no-evidence, and the caller posts the checklist',
         'on its own.',
         '',
+        '--local adds a **Local preview:** line under the hosted preview line,',
+        'or opens the body with it when there is none, and is carried forward',
+        'the same way. It does not by itself turn no-evidence into ok, so a',
+        'branch with a server running and nothing to show posts no link-only',
+        'comment. Together with --checklist it does, so the checklist and the',
+        'link land in one comment.',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body or reported no-evidence',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -428,6 +471,7 @@ export function register(program: Command): void {
         '  canon pr evidence 1341 --json',
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
         '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
+        '  canon pr evidence 1341 --local http://localhost:5173 --json',
         '',
       ].join('\n'),
     )
@@ -484,6 +528,66 @@ export function register(program: Command): void {
     .action(async (number: string | undefined, opts: PreviewOptions) => {
       process.exitCode = await runPreview(number, opts)
     })
+
+  pr.command('local')
+    .description(
+      "Find the server this worktree is running and report its localhost address, or remove it from the pull request's evidence comment",
+    )
+    .argument('[number]', 'Pull request to edit on --remove')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Worktree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--remove',
+      "Replace the evidence comment's local preview line with a note",
+    )
+    .option(
+      '--note <text>',
+      'What replaces the line on --remove',
+      LOCAL_REMOVED_NOTE,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads every TCP socket in LISTEN, keeps those whose owning process runs',
+        "inside this worktree's toplevel, and requests / on each. The lowest",
+        'port serving an HTML page is reported, which skips a test runner or a',
+        'reload socket answering in the same tree.',
+        '',
+        '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',
+        'read through lsof, or through /proc on a Linux machine without it.',
+        '',
+        '--remove reads the pull request comment carrying the pr-evidence',
+        'marker and replaces its **Local preview:** line with --note, editing',
+        'the comment itself so a close workflow with no session can call it.',
+        '',
+        'Read `reason` on the JSON record:',
+        '  ok                  a page answered, with its address in `url`',
+        '  no-server           nothing inside this worktree served a page',
+        '  no-listener-reader  neither lsof nor /proc is available',
+        '  removed             --remove replaced the line',
+        '  no-comment          --remove found no marked comment, a no-op',
+        '  no-line             --remove found no local line, a no-op',
+        '',
+        'Exit codes:',
+        '  0  a server was found, or --remove finished, including a no-op',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr local --json',
+        '  canon pr local 1341 --remove --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: LocalOptions) => {
+      process.exitCode =
+        opts.remove === true
+          ? await runLocalRemove(number, opts)
+          : await runLocal(opts)
+    })
 }
 
 interface PullRequestRead {
@@ -1319,7 +1423,15 @@ async function runEvidence(
     baseTree.has(path),
   )
 
-  if (grouped.kind === 'refused' && opts.preview === undefined) {
+  // A local address rides on a checklist or a hosted preview and never opens
+  // a comment alone, so a docs-only branch with a server up posts nothing.
+  const hasChecklistAndLocal =
+    suppliedChecklist !== undefined && opts.local !== undefined
+  if (
+    grouped.kind === 'refused' &&
+    opts.preview === undefined &&
+    !hasChecklistAndLocal
+  ) {
     logStep('Skipped')
     logInfo(
       'No changed path carries an evidence/ segment, so there is nothing to post.',
@@ -1355,6 +1467,7 @@ async function runEvidence(
   let commentId: number | undefined
   let carriedPreview: string | undefined
   let carriedChecklist: string | undefined
+  let carriedLocal: string | undefined
   if (identity.number !== undefined) {
     const commentsRow = await gh(root, [
       'pr',
@@ -1389,9 +1502,11 @@ async function runEvidence(
     commentId = findEvidenceCommentId(comments)
     carriedPreview = findEvidencePreview(comments)
     carriedChecklist = findEvidenceChecklist(comments)
+    carriedLocal = findEvidenceLocal(comments)
   }
 
   const preview = opts.preview ?? carriedPreview
+  const local = opts.local ?? carriedLocal
   const checklist = suppliedChecklist ?? carriedChecklist
   const states = grouped.kind === 'read' ? grouped.states : []
   const body = renderEvidenceBody(
@@ -1401,6 +1516,7 @@ async function runEvidence(
     identity.head,
     preview,
     checklist,
+    local,
   )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
@@ -1410,6 +1526,7 @@ async function runEvidence(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,
   )
   if (preview !== undefined) logInfo(`preview ${preview}`)
+  if (local !== undefined) logInfo(`local preview ${local}`)
   if (checklist !== undefined) {
     logInfo(
       suppliedChecklist === undefined
@@ -1603,6 +1720,211 @@ async function runPreview(
   return 0
 }
 
+async function readText(path: string): Promise<string | undefined> {
+  return readFile(path, 'utf8').catch(() => undefined)
+}
+
+/**
+ * Every listening socket's owning pid, read from `/proc`. Only a process this
+ * user owns exposes its `fd` table, which is also the only process whose
+ * server this user's worktree could have started.
+ */
+async function readProcListeners(): Promise<Listener[] | undefined> {
+  const tables = await Promise.all(
+    ['/proc/net/tcp', '/proc/net/tcp6'].map(readText),
+  )
+  if (tables.every((text) => text === undefined)) return undefined
+  const byInode = new Map(
+    tables.flatMap((text) =>
+      text === undefined
+        ? []
+        : parseProcNetTcp(text).map((s) => [s.inode, s.port] as const),
+    ),
+  )
+
+  const processIds = (await readdir('/proc').catch(() => [])).filter((name) =>
+    /^\d+$/.test(name),
+  )
+  const listeners: Listener[] = []
+  for (const pid of processIds) {
+    const fds = await readdir(`/proc/${pid}/fd`).catch(() => [])
+    for (const fd of fds) {
+      const target = await readlink(`/proc/${pid}/fd/${fd}`).catch(() => '')
+      const inode = /^socket:\[(\d+)\]$/.exec(target)?.[1]
+      const port = inode === undefined ? undefined : byInode.get(inode)
+      if (port !== undefined) listeners.push({ pid: Number(pid), port })
+    }
+  }
+  return listeners
+}
+
+/**
+ * The machine half of a detection: lsof where it is installed, `/proc` on a
+ * Linux machine without it, and no reader anywhere else.
+ */
+function machineLocalRunner(): LocalRunner {
+  const hasLsof = Bun.which('lsof') !== null
+  return {
+    async listListeners() {
+      if (hasLsof) {
+        const result = await $`lsof -nP -iTCP -sTCP:LISTEN -Fpn`
+          .quiet()
+          .nothrow()
+        // lsof exits 1 both when it matched nothing and when it could not
+        // read some process, and the rows it did print are real either way.
+        if (result.exitCode <= 1) return parseLsofListeners(result.text())
+      }
+      if (existsSync('/proc/net/tcp')) return readProcListeners()
+      return undefined
+    },
+    async cwdOf(pid) {
+      if (existsSync(`/proc/${pid}/cwd`)) {
+        return readlink(`/proc/${pid}/cwd`).catch(() => undefined)
+      }
+      if (!hasLsof) return undefined
+      const result = await $`lsof -a -p ${pid} -d cwd -Fn`.quiet().nothrow()
+      const line = result
+        .text()
+        .split('\n')
+        .find((row) => row.startsWith('n'))
+      return line?.slice(1)
+    },
+    // An HTML page rather than any answer, since a test runner's server or a
+    // reload socket in the same tree answers too, and a reviewer opening one
+    // gets a bare 404 instead of the branch.
+    async probe(port) {
+      try {
+        const response = await fetch(`http://localhost:${port}/`, {
+          signal: AbortSignal.timeout(LOCAL_PROBE_TIMEOUT_MS),
+        })
+        await response.body?.cancel()
+        return (response.headers.get('content-type') ?? '').includes(
+          'text/html',
+        )
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+/** The worktree's toplevel with symlinks resolved, since a process cwd is read back resolved. */
+async function resolveWorktreeRoot(root: string): Promise<string> {
+  const result = await $`git -C ${root} rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  const toplevel = result.exitCode === 0 ? result.text().trim() : root
+  return realpath(toplevel).catch(() => toplevel)
+}
+
+async function runLocal(opts: LocalOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr local')
+
+  const worktree = await resolveWorktreeRoot(root)
+  const result = await findLocalServer(worktree, machineLocalRunner())
+  if (result.kind === 'refused') {
+    return refuseWith(
+      result.reason,
+      LOCAL_REFUSALS[result.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  logStep('Local preview')
+  logInfo(result.url)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, reason: 'ok', url: result.url, port: result.port })}\n`,
+    )
+  }
+  return 0
+}
+
+/**
+ * Replaces the local line on the marked comment. The verb writes here rather
+ * than handing a body back, because its caller is a close workflow with no
+ * session to post one.
+ */
+async function runLocalRemove(
+  number: string | undefined,
+  opts: LocalOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const note = opts.note ?? LOCAL_REMOVED_NOTE
+
+  intro('canon pr local --remove')
+
+  if (Bun.which('gh') === null) {
+    return refuseWith('gh-missing', PULL_REFUSALS['gh-missing'], emitJson, root)
+  }
+
+  const args = ['pr', 'view']
+  if (number !== undefined) args.push(number)
+  args.push('--json', 'comments')
+  const row = await gh(root, args)
+  let comments: readonly { url?: string; body: string }[] | undefined
+  try {
+    comments =
+      row === null
+        ? undefined
+        : (
+            JSON.parse(row) as {
+              comments?: readonly { url?: string; body: string }[]
+            }
+          ).comments
+  } catch {
+    comments = undefined
+  }
+  if (comments === undefined) {
+    return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
+  }
+
+  const finish = (reason: string, message: string): number => {
+    logStep(reason === 'removed' ? 'Removed' : 'Skipped')
+    logInfo(message)
+    outro()
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, reason })}\n`)
+    }
+    return 0
+  }
+
+  const commentId = findEvidenceCommentId(comments)
+  const marked = comments.find((comment) =>
+    comment.url?.endsWith(`#issuecomment-${commentId}`),
+  )
+  if (commentId === undefined || marked === undefined) {
+    return finish('no-comment', 'No comment carries the evidence marker.')
+  }
+
+  const stripped = stripLocalLine(marked.body, note)
+  if (stripped === undefined) {
+    return finish('no-line', 'The evidence comment carries no local line.')
+  }
+
+  const patched = await gh(root, [
+    'api',
+    '-X',
+    'PATCH',
+    `repos/{owner}/{repo}/issues/comments/${commentId}`,
+    '-f',
+    `body=${stripped}`,
+  ])
+  if (patched === null) {
+    return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
+  }
+
+  return finish('removed', `comment ${commentId}`)
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command

package/src/commands/sync.ts

@@ -133,9 +133,17 @@ function renderCheck(report: CheckReport): void {
       logWarn(entry.notice ?? `${entry.rel} (${entry.state})`)
     }
 
-    const { stale, customized, drifted, stranded, retired, orphaned, missing } =
-      domain.counts
-    if (stale + customized + drifted + stranded + retired === 0) {
+    const {
+      stale,
+      customized,
+      drifted,
+      stranded,
+      retired,
+      renamed,
+      orphaned,
+      missing,
+    } = domain.counts
+    if (stale + customized + drifted + stranded + retired + renamed === 0) {
       logInfo(orphaned === 0 ? 'up to date' : `up to date (${orphaned} local)`)
     }
     // A local file is not a deficiency and a missing rule is, so this never

package/src/commands/tasks.ts

@@ -409,12 +409,14 @@ export function register(program: Command): void {
       [
         '',
         'Exit codes:',
-        '  0  the line was added, corrected, or already correct',
+        '  0  the line was added, appended to, corrected, or already correct',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'It adds Pull request: #NNN under the origin lines the task carries,',
-        'and corrects the number in place when the line exists. The board is',
-        'shared scratch, so a linked worktree records against the same board.',
+        'and appends the number to the line when one exists, so a task shipped',
+        'in slices lists every pull request. A line that does not read as a',
+        'list is replaced. The board is shared scratch, so a linked worktree',
+        'records against the same board.',
         '',
         'Examples:',
         '  canon tasks pull-request 673 v28.1-trigger-escalation',
@@ -448,11 +450,10 @@ export function register(program: Command): void {
         '  0  the line was added, corrected, or already correct',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
-        'It writes Plan: [<label>](<target>) right after the H1, the same',
-        'add/correct/unchanged shape canon tasks pull-request writes with, and',
-        'resolves both a bare slug and a board-relative path the way',
-        'canon tasks plan-answers does. Safe from a linked worktree, since it',
-        'resolves the board root in-process.',
+        'It writes Plan: [<label>](<target>) right after the H1, corrects the',
+        'target in place when the line exists, and resolves both a bare slug',
+        'and a board-relative path the way canon tasks plan-answers does. Safe',
+        'from a linked worktree, since it resolves the board root in-process.',
         '',
         'Examples:',
         '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',

package/src/context/classify/extract.ts

@@ -285,8 +285,8 @@ export function sweepSections(
   // An H3 sitting before the document's first H2, or in a document that
   // carries no H2 at all, has no enclosing section for the main loop below
   // to attribute it to. Sweep it as a section of its own instead of
-  // dropping it, which is the shape `canon/context/development/scratch.md`
-  // takes: an H1 followed directly by eight H3s and no H2 anywhere.
+  // dropping it, which is the shape of an entry whose H1 is followed
+  // directly by H3s with no H2 anywhere.
   const firstH2 = headings.findIndex((h) => h.level === 2)
   const leadingBound = firstH2 === -1 ? headings.length : firstH2
 

package/src/counts/scan.ts

@@ -129,7 +129,7 @@ const QUANTIFIERS = ['all']
  * of the number.
  *
  * Found on this module's own first review, against a live instance the verb
- * gate alone reported clean: `canon/context/development/gates.md` stated
+ * gate alone reported clean: the development gating-stages entry stated
  * `the twelve audits` while the tree held 20, sitting inside the plausibility
  * bound this design already carries, so nothing but the missing shape kept it
  * from reporting.

package/src/design/base.css

@@ -1,29 +1,29 @@
-/* Generated by `canon design regen` from src/design/tokens.ts. Do not edit.
+/* Generated by `canon design regen` from src/design/neutral.ts. Do not edit.
    This is the base half of a design install. A target overrides a value in
    .claude/design/project/, which the three-way merge leaves alone, so this
    file changes freely and nothing a project wrote lives in it. */
 
 :root {
-  --color-background: #0f0e0c;
-  --color-surface: #151412;
-  --color-chrome: #1b1a18;
-  --color-border: #2a2926;
-  --color-text: #d9d7d4;
-  --color-text-body: #aeada9;
-  --color-text-secondary: #8c8b86;
-  --color-muted: #7f7f7c;
-  --color-accent: #c76b5f;
+  --color-background: #0e0e0e;
+  --color-surface: #141414;
+  --color-chrome: #1a1a1a;
+  --color-border: #292929;
+  --color-text: #dddddd;
+  --color-text-body: #b2b2b2;
+  --color-text-secondary: #8e8e8e;
+  --color-muted: #7f7f7f;
+  --color-accent: #ececec;
   --color-success: #61c454;
-  --color-light-background: #fbfaf8;
-  --color-light-surface: #f1f1ee;
-  --color-light-chrome: #e9e8e5;
-  --color-light-text: #2c2c29;
-  --color-light-text-body: #4b4947;
-  --color-light-text-secondary: #666561;
-  --color-light-muted: #6e6d6c;
-  --color-light-accent: #ad4a4b;
+  --color-light-background: #fafafa;
+  --color-light-surface: #f1f1f1;
+  --color-light-chrome: #e8e8e8;
+  --color-light-text: #252525;
+  --color-light-text-body: #444444;
+  --color-light-text-secondary: #5f5f5f;
+  --color-light-muted: #6c6c6c;
+  --color-light-accent: #191919;
   --color-light-success: #2d6b22;
-  --color-light-border: #d5d4d1;
+  --color-light-border: #d4d4d4;
   --space-xs: 0.25rem;
   --space-sm: 0.5rem;
   --space-md: 0.875rem;

package/src/design/board.ts

@@ -10,6 +10,7 @@ import {
 import { join, relative, sep } from 'node:path'
 import { DESIGN_DOCUMENT } from '@/design/regen'
 import { renderDesignDoc } from '@/design/render'
+import { NEUTRAL_TOKENS } from '@/design/neutral'
 import { colorValue } from '@/design/tokens'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { recordDir } from '@/record-root'
@@ -131,6 +132,16 @@ const SCROLLSPY_SCRIPT = [
   '})();</script>',
 ].join('')
 
+/**
+ * A role's toolkit value, falling back to the neutral install base's where the
+ * toolkit record drops the role, so the board never restates a hex of its own.
+ */
+function roleColor(role: string): string {
+  const value = colorValue(role) ?? colorValue(role, NEUTRAL_TOKENS)
+  if (value === undefined) throw new Error(`No design token declares ${role}`)
+  return value
+}
+
 /**
  * The same brand mark `src/design/render.ts` embeds in its own preview,
  * colored with the dark accent since the board's default chrome is dark
@@ -139,7 +150,7 @@ const SCROLLSPY_SCRIPT = [
  * copies rather than a shared icon helper for the first second caller.
  */
 function faviconLink(): string {
-  const color = colorValue('accent') ?? '#e0724b'
+  const color = roleColor('accent')
   const href = `data:image/svg+xml,${encodeURIComponent(
     `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80"><path d="M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z" fill="${color}" /><rect x="44" y="15" width="12" height="70" rx="2" fill="${color}" /></svg>`,
   )}`
@@ -232,12 +243,12 @@ ${SCROLLSPY_SCRIPT}
 }
 
 function panelPage(title: string, body: string): string {
-  const accent = colorValue('light-accent') ?? '#a4471c'
-  const surface = colorValue('light-surface') ?? '#f4efe6'
-  const border = colorValue('light-border') ?? '#e4dcd0'
-  const muted = colorValue('light-muted') ?? '#726b62'
-  const text = colorValue('light-text') ?? '#1a1815'
-  const background = colorValue('light-background') ?? '#faf7f2'
+  const accent = roleColor('light-accent')
+  const surface = roleColor('light-surface')
+  const border = roleColor('light-border')
+  const muted = roleColor('light-muted')
+  const text = roleColor('light-text')
+  const background = roleColor('light-background')
 
   return `<!doctype html>
 <html lang="en">