@erclx/canon 4.119.0 → 4.121.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,67 @@ 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 /proc where it exists, or through lsof on a 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 +1424,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 +1468,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 +1503,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 +1517,7 @@ async function runEvidence(
     identity.head,
     preview,
     checklist,
+    local,
   )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
@@ -1410,6 +1527,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 +1721,217 @@ 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: `/proc` wherever it exists, lsof on a
+ * machine without it, and no reader anywhere else.
+ */
+function machineLocalRunner(): LocalRunner {
+  const hasLsof = Bun.which('lsof') !== null
+  return {
+    async listListeners() {
+      // lsof 4.95 drops every process whose kernel-truncated name holds an
+      // unmatched `(`, which Next's `next-server (vX.Y.Z)` title cuts down to,
+      // so `/proc` goes first despite costing several times what lsof does.
+      if (existsSync('/proc/net/tcp')) {
+        const listeners = await readProcListeners()
+        if (listeners !== undefined) return listeners
+      }
+      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())
+      }
+      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/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/tokens.ts

@@ -381,7 +381,7 @@ export const TOKENS: DesignTokens = {
   iconography: [
     'No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing.',
     '',
-    'The same mark ships in five independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`, which teach pages also take by rendering the live mark. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+    'The same mark ships in five independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`, which teach pages also take by rendering the live mark. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design/tokens.md` carries which file holds each copy.',
   ].join('\n'),
 }
 

package/src/gate/measures.ts

@@ -438,8 +438,8 @@ export const recordIdempotence: Measure = async (ctx) => {
 }
 
 /**
- * A banned character, word, or spelling is a fact rather than a threshold, so
- * it fails the push while bullet, paragraph, and depth weight stay advisory.
+ * A banned character is a fact rather than a threshold, so it fails the push
+ * while bullet, paragraph, and depth weight stay advisory.
  *
  * The whole corpus is measured rather than the changed files, because a
  * `Do not use` bullet added to a standard bans a token retroactively and no
@@ -453,7 +453,7 @@ export const markdownBans: Measure = async (ctx) => {
   const { exitCode } = await ctx.cli(['markdown', 'audit', '--json'])
 
   if (exitCode === 0) {
-    return { emissions: [info('No banned character, word, or spelling')] }
+    return { emissions: [info('No banned character')] }
   }
 
   if (exitCode === 1) {
@@ -476,7 +476,7 @@ export const markdownBans: Measure = async (ctx) => {
     return {
       emissions: [output(frame.all)],
       failure:
-        'Markdown prose carries a banned character, word, or spelling, or a relative link resolves to nothing on disk. Rewrite the sentence or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
+        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk. Rewrite the sentence or fix the link, and reach for a code span only where the token is genuinely an identifier under discussion.',
     }
   }
 

package/src/gate/stages.ts

@@ -83,7 +83,7 @@ export interface Stage {
 
 /**
  * Corpora a `src/` test asserts over from outside `src/`, censused in
- * `canon/context/development/verification.md`. This list and that census are
+ * `canon/context/development/tests.md`. This list and that census are
  * two copies of one set with nothing comparing them, so a corpus joining the
  * census joins this list in the same change. The first four are directory
  * prefixes because their tests walk the tree whole, which is what reaches a
@@ -97,7 +97,6 @@ export const TEST_CORPORA_PATTERNS = [
   '^standards/markdown\\.md$',
   '^tooling/base/reference\\.md$',
   '^tooling/web/configs/scripts/worktree-port\\.sh$',
-  '^\\.cspell/banned-spellings\\.txt$',
   '^scripts/lib/worktree\\.sh$',
   '^scripts/core/check-ignore-parity\\.sh$',
 ]
@@ -314,7 +313,7 @@ export const STAGES: readonly Stage[] = [
   {
     // A hook, a workflow, or a husky script reaching one side of the seed or
     // config boundary and not the other is a capability withheld with no
-    // recorded reason, per the criterion in canon/context/tooling.md.
+    // recorded reason, per the criterion in canon/context/tooling/seeds.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
     checks: [

package/src/markdown/bans.ts

@@ -10,85 +10,28 @@ import type { BanSets } from '@/markdown/scan'
 const CHARACTERS = ['—', ';'] as const
 
 /**
- * Single lowercase words `markdown.md` bans under `## Language`.
+ * The one closed set the audit measures, owned here rather than harvested
+ * from the standard stating it.
  *
- * A multi-word ban is absent by the same test the character set applies. The
- * standard bans a pattern like `It's not X, it's Y` with a placeholder standing
- * in for the rest of the sentence, so no literal match reaches it and the
- * phrase bans stay a reader's judgment.
- */
-const WORDS = [
-  'seamless',
-  'robust',
-  'powerful',
-  'revolutionary',
-  'enhanced',
-  'allows',
-  'leverage',
-  'simply',
-  'just',
-  'easily',
-  'quickly',
-  'very',
-  'really',
-] as const
-
-/**
- * British spellings of the American examples `markdown.md` lists.
- *
- * The set is carried whole rather than derived from a suffix rule, because a
- * suffix pattern run over prose produced 46 of the 58 false positives measured
- * during intake: `exercises`, `promises`, and `revised` all end in `-ise` and
- * none is a British spelling. Matching whole words reaches none of them.
- *
- * `analyse` is absent because the standard's example is `analyze`, which ends
- * in `-yze` rather than the `-ize` its rule states. The set records what the
- * standard reaches rather than what a reader would extend it to, so adding the
- * spelling here would widen the check past the prose it answers to.
- */
-const SPELLINGS = [
-  'organise',
-  'summarise',
-  'recognise',
-  'behaviour',
-  'colour',
-  'centre',
-] as const
-
-/**
- * The three closed sets the audit measures, owned here rather than harvested
- * from the standards stating them.
- *
- * Parsing the prose was the alternative and it put a parser contract on two
- * documents authored for people, which the prose standard had to carry a
- * paragraph of its own to protect. The sets are a prior an author already
- * knows rather than a filter: measured at `60fc97bf` on 2026-08-19, these 21
- * terms ran across 483 markdown files for a clean exit, and every one of the
- * 70 occurrences of a banned word sat inside the ban list itself or inside an
- * example demonstrating the ban.
- *
- * The set is closed rather than extensible. Enumeration cannot close the gap
- * it aims at, and each addition costs a false-positive class, since `just`,
- * `allows`, and `very` have honest uses no literal match separates. A project
- * wanting its own vocabulary is asking for a different feature than this one.
+ * Parsing the prose was the alternative and it put a parser contract on a
+ * document authored for people. The set is closed rather than extensible,
+ * since a character is the one class a literal match settles. A word is left
+ * to `write-human` as guidance and a spelling to cspell, because a word ban
+ * catches the token and misses the habit behind it.
  */
 export const BAN_SETS: BanSets = {
   characters: CHARACTERS,
-  words: WORDS,
-  spellings: SPELLINGS,
 }
 
 /**
- * Names any set that arrived empty, so a run measuring nothing says so.
+ * Names the set when it arrived empty, so a run measuring nothing says so.
  *
  * Empty is not the same state as finding no hit. A scan with no terms reports
  * a clean file having looked for nothing, which is the silence the audit
- * refused to ship back when a standard could go missing. The sets ship with
- * the package now, so the only way one empties is an edit to this file, and
+ * refused to ship back when a standard could go missing. The set ships with
+ * the package now, so the only way it empties is an edit to this file, and
  * the guard is what keeps that edit loud rather than quiet.
  */
 export function emptyBanSets(sets: BanSets = BAN_SETS): string[] {
-  return (['characters', 'words', 'spellings'] as const).filter(
-    (name) => sets[name].length === 0,
-  )
+  return (['characters'] as const).filter((name) => sets[name].length === 0)
 }

package/src/markdown/gate.ts

@@ -21,7 +21,7 @@ export interface GateInput {
 /**
  * Whether the audit found something that should fail the caller.
  *
- * A banned character, word, or spelling and a relative link resolving to
+ * A banned character and a relative link resolving to
  * nothing on disk are both facts rather than a threshold, so either gates
  * unconditionally and there is no widened mode to reach for. The standards
  * decide what counts as banned, which keeps this answering how many rather