@erclx/canon 4.118.0 → 4.120.0

package/src/design/neutral.ts

@@ -0,0 +1,127 @@
+import type { ColorToken, DesignTokens } from '@/design/tokens'
+import { TOKENS } from '@/design/tokens'
+
+/**
+ * The token set `canon design install` hands a target, achromatic so the only
+ * palette a target renders is one it wrote under `.claude/design/project/`.
+ * Type, spacing, and radii are this repository's by spread, and only the color
+ * list is a second copy, held to the same roles by `neutral.test.ts`.
+ *
+ * Grounds, surface, chrome, and border take the OKLCH lightness of the toolkit
+ * role they replace at chroma 0. Text roles are solved against `surface` for
+ * the contrast targets `TOKENS` records (13.5, 8.6, 5.6, 4.6), and the accent
+ * for 15.5, past `text` so it still reads apart from body copy. The state
+ * roles keep the toolkit's values, since a state color is a meaning rather
+ * than a palette.
+ */
+
+const DARK_GROUNDS = ['background', 'surface'] as const
+const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
+
+function toolkitRole(role: string): ColorToken {
+  const token = TOKENS.color.find((candidate) => candidate.role === role)
+  if (token === undefined) throw new Error(`TOKENS declares no ${role} role`)
+  return token
+}
+
+const NEUTRAL_COLOR: readonly ColorToken[] = [
+  { role: 'background', intent: 'page canvas', value: '#0e0e0e' },
+  {
+    role: 'surface',
+    intent: 'cards, panels, raised blocks',
+    value: '#141414',
+  },
+  {
+    role: 'chrome',
+    intent: 'the window titlebar, one step above the canvas',
+    value: '#1a1a1a',
+  },
+  { role: 'border', intent: 'every rule and panel edge', value: '#292929' },
+  {
+    role: 'text',
+    intent: 'headings, counts, emphasized runs',
+    value: '#dddddd',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'text-body',
+    intent: 'default body copy',
+    value: '#b2b2b2',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'text-secondary',
+    intent: 'labels, captions, supporting copy',
+    value: '#8e8e8e',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'muted',
+    intent: 'the faintest step, trailing notes',
+    value: '#7f7f7f',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'accent',
+    intent: 'install command, mark, primary action',
+    value: '#ececec',
+    grounds: DARK_GROUNDS,
+  },
+  toolkitRole('success'),
+  toolkitRole('warning'),
+  toolkitRole('error'),
+  {
+    role: 'light-background',
+    intent: 'page canvas on a light ground',
+    value: '#fafafa',
+  },
+  {
+    role: 'light-surface',
+    intent: 'cards and panels on a light ground',
+    value: '#f1f1f1',
+  },
+  {
+    role: 'light-chrome',
+    intent: 'the window titlebar, one step above the canvas',
+    value: '#e8e8e8',
+  },
+  {
+    role: 'light-text',
+    intent: 'primary text on a light ground',
+    value: '#252525',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-text-body',
+    intent: 'default body copy on a light ground',
+    value: '#444444',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-text-secondary',
+    intent: 'labels, captions, supporting copy on a light ground',
+    value: '#5f5f5f',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-muted',
+    intent: 'secondary text on a light ground',
+    value: '#6c6c6c',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-accent',
+    intent: 'links and primary action on light',
+    value: '#191919',
+    grounds: LIGHT_GROUNDS,
+  },
+  toolkitRole('light-success'),
+  {
+    role: 'light-border',
+    intent: 'rules and panel edges on light',
+    value: '#d4d4d4',
+    verify: true,
+  },
+]
+
+export const NEUTRAL_TOKENS: DesignTokens = { ...TOKENS, color: NEUTRAL_COLOR }

package/src/design/regen.ts

@@ -2,10 +2,12 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { buildDesignCss } from '@/design/css'
 import { renderDesignDocument } from '@/design/document'
+import { NEUTRAL_TOKENS } from '@/design/neutral'
 
 /**
- * The two artifacts the token source produces, written by `canon design regen`
- * and asserted for drift by the `design` stage of `bun run check`.
+ * The two artifacts the token sources produce, written by `canon design regen`
+ * and asserted for drift by the `design` stage of `bun run check`. The
+ * document renders from `TOKENS` and the stylesheet from `NEUTRAL_TOKENS`.
  *
  * The document is what a person reads and the stylesheet is what a target
  * installs, and neither is edited by hand. That is the cost the operator took
@@ -26,7 +28,7 @@ export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 export const DESIGN_BASE_CSS = join('src', 'design', 'base.css')
 
 const BASE_BANNER = [
-  '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.',
@@ -50,7 +52,7 @@ export function regenDesign(root: string): RegenResult {
     cssPath: write(
       root,
       DESIGN_BASE_CSS,
-      buildDesignCss(undefined, { banner: BASE_BANNER }),
+      buildDesignCss(NEUTRAL_TOKENS, { banner: BASE_BANNER }),
     ),
   }
 }

package/src/design/tokens.ts

@@ -381,13 +381,16 @@ 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'),
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */
-export function colorValue(role: string): string | undefined {
-  return TOKENS.color.find((token) => token.role === role)?.value
+export function colorValue(
+  role: string,
+  tokens: DesignTokens = TOKENS,
+): string | undefined {
+  return tokens.color.find((token) => token.role === role)?.value
 }
 
 /**

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
@@ -209,10 +209,10 @@ export const STAGES: readonly Stage[] = [
     success: 'Hero clean',
   },
   {
-    // `canon/DESIGN.md`, the base stylesheet, the web stylesheet, and the
-    // tab icon are all written from `src/design/tokens.ts` and none is edited
-    // by hand. Four artifacts from one source is the cost of the token move,
-    // and a render step that has to run is only safe while something fails
+    // `canon/DESIGN.md`, the web stylesheet, and the tab icon are written
+    // from `src/design/tokens.ts`, the base stylesheet from
+    // `src/design/neutral.ts`, and none is edited by hand. Four artifacts
+    // from two token sources is the cost of the token move, and a render step that has to run is only safe while something fails
     // when it did not, which is this.
     id: 'design',
     label: 'Design',
@@ -314,7 +314,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/gov/adapter.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
-import { canonRulesDir } from '@/gov/install'
+import { canonRulesDir, ruleSubdir } from '@/gov/install'
+import { loadRenames, resolveSuccessor } from '@/gov/renames'
 import { resolveMissingRules } from '@/gov/stacks'
 import type { InstalledFile, RetiredSurface, SyncAdapter } from '@/sync/engine'
 import { readStamp, stampedChain } from '@/sync/stamp'
@@ -49,11 +50,14 @@ export function indexSourceRules(root: string): Map<string, string> {
  * `.claude/rules/canon/` leaves outside the walk, so everything the walk does
  * reach is the toolkit's. A rule there with no source is one the toolkit
  * retired or renamed, and the sync deletes it rather than leaving it loaded.
+ * A rename `governance/renames.toml` declares also installs the rule under its
+ * new name.
  * A `projectSubdir` would compute a stale `canon/project/` destination, which
  * is wrong rather than merely redundant.
  */
 export function createGovAdapter(root: string): SyncAdapter {
   const index = indexSourceRules(root)
+  const renames = loadRenames(root)
 
   return {
     banner: 'canon gov sync',
@@ -67,10 +71,56 @@ export function createGovAdapter(root: string): SyncAdapter {
     collectRetired: (target: string) => collectRetiredGov(target),
     collectMissing: (target: string) => collectMissingGov(root, target),
     ownsInstalledRoot: true,
+    locateSuccessor: (file: InstalledFile, target: string) => {
+      const successor = resolveSuccessor(
+        renames,
+        index,
+        basename(file.path, '.md'),
+      )
+      if (successor === undefined) return undefined
+
+      const source = index.get(successor)
+      if (source === undefined) return undefined
+
+      return {
+        source,
+        dest:
+          heldRulePath(target, successor) ??
+          join(
+            canonRulesDir(target),
+            ruleSubdir(source, rulesSourceDir(root)),
+            `${successor}.md`,
+          ),
+      }
+    },
     stamp: { domain: 'governance', toolkitRoot: root },
   }
 }
 
+/**
+ * Where the target already holds a rule, in whichever band folder. A
+ * successor held outside the source's band stays where it is, the same way
+ * `locateSource` syncs a moved rule in place, rather than gaining a second copy.
+ *
+ * Holding the predecessor is the whole entitlement test, so no stamped chain
+ * is read here. That covers a rule `--add` layered on and a target installed
+ * before chains were stamped alike.
+ */
+function heldRulePath(target: string, rule: string): string | undefined {
+  const dir = canonRulesDir(target)
+  if (!existsSync(dir)) return undefined
+
+  for (const rel of new Bun.Glob(`**/${rule}.md`).scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    return join(dir, rel)
+  }
+
+  return undefined
+}
+
 /**
  * Rules the target's recorded chain entitles it to and its tree does not
  * hold. Reports as `notice` text through the same shape `collectRetired`

package/src/gov/install.ts

@@ -38,8 +38,14 @@ export function installedInternalRulesDir(target: string): string {
  * Rule names a target already holds, read off the installed `canon/` tree by
  * basename rather than off a recorded stack, since a target may hold rules
  * `--add` layered on that no stack lists.
+ *
+ * `successorOf` adds the name a held rule was renamed to, since the next sync
+ * installs it and a reader treating it as missing would name it twice.
  */
-export function installedRuleNames(target: string): Set<string> {
+export function installedRuleNames(
+  target: string,
+  successorOf?: (name: string) => string | undefined,
+): Set<string> {
   const dir = canonRulesDir(target)
   const names = new Set<string>()
   if (!existsSync(dir)) return names
@@ -49,7 +55,11 @@ export function installedRuleNames(target: string): Set<string> {
     onlyFiles: true,
     dot: true,
   })) {
-    names.add(basename(rel, '.md'))
+    const name = basename(rel, '.md')
+    names.add(name)
+
+    const successor = successorOf?.(name)
+    if (successor !== undefined) names.add(successor)
   }
 
   return names
@@ -84,7 +94,7 @@ export function listRuleSourcePaths(root: string): string[] {
  * in two subdirectories resolves deterministically rather than by whichever
  * entry the filesystem yielded first.
  */
-function indexRuleSources(root: string): Map<string, string> {
+export function indexRuleSources(root: string): Map<string, string> {
   const rulesRoot = rulesSourceDir(root)
   const byName = new Map<string, string>()
 

package/src/gov/renames.ts

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { indexRuleSources } from '@/gov/install'
+
+/** Old rule basename to the basename the same rule ships under now. */
+export type Renames = ReadonlyMap<string, string>
+
+function renamesPath(root: string): string {
+  return join(root, 'governance', 'renames.toml')
+}
+
+/**
+ * Reads the shipped rename ledger. A toolkit without one declares no renames,
+ * which leaves every sourceless rule on the retire path it took before the
+ * ledger existed.
+ */
+export function loadRenames(root: string): Renames {
+  const path = renamesPath(root)
+  if (!existsSync(path)) return new Map()
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const table = parsed.renamed
+  if (typeof table !== 'object' || table === null) return new Map()
+
+  return new Map(
+    Object.entries(table).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string',
+    ),
+  )
+}
+
+/**
+ * Follows a declared rename to the name the toolkit ships the rule under now,
+ * through every later rename of that name. The ledger is never pruned, so a
+ * target several releases behind still reaches the current name.
+ *
+ * Returns nothing when the chain ends on a name with no source, or loops,
+ * since installing a guess is worse than the retire the caller falls back to.
+ */
+export function resolveSuccessor(
+  renames: Renames,
+  index: ReadonlyMap<string, string>,
+  name: string,
+): string | undefined {
+  const visited = new Set([name])
+  let current = renames.get(name)
+
+  while (current !== undefined) {
+    if (visited.has(current)) return undefined
+    visited.add(current)
+
+    const next = renames.get(current)
+    if (next === undefined) break
+    current = next
+  }
+
+  if (current === undefined || !index.has(current)) return undefined
+  return current
+}
+
+/**
+ * Binds the ledger and the source tree at `root` once, for a caller asking
+ * about many held names.
+ */
+export function successorResolver(
+  root: string,
+): (name: string) => string | undefined {
+  const renames = loadRenames(root)
+  if (renames.size === 0) return () => undefined
+
+  const index = indexRuleSources(root)
+  return (name) => resolveSuccessor(renames, index, name)
+}

package/src/gov/stacks.ts

@@ -7,6 +7,7 @@ import {
   type RuleSource,
   rulesSourceDir,
 } from '@/gov/install'
+import { successorResolver } from '@/gov/renames'
 
 export interface GovStack {
   readonly name: string
@@ -163,6 +164,9 @@ export function unreferencedRules(root: string): string[] {
  * so reading its leaf entry is enough; no second walk resolves the chain
  * itself. A stack the toolkit no longer ships resolves to nothing rather than
  * throwing, the same way `readNewRules`'s band fallback already treats it.
+ *
+ * A held rule's declared successor counts as held, since the sync that
+ * renames the old file installs it.
  */
 export function resolveMissingRules(
   root: string,
@@ -176,7 +180,7 @@ export function resolveMissingRules(
   if (!resolution.ok) return []
 
   const { found } = lookupRules(root, resolution.rules)
-  const held = installedRuleNames(target)
+  const held = installedRuleNames(target, successorResolver(root))
 
   return found
     .filter((source) => !held.has(source.rule))

package/src/pr/evidence.ts

@@ -7,6 +7,9 @@ const MARKER_PREFIX = '<!-- pr-evidence:'
 /** How the first line of a body names the branch's preview deployment. */
 const PREVIEW_PREFIX = '**Preview:**'
 
+/** How the opening block names the branch's server on the operator's own machine, under any hosted preview line. */
+export const LOCAL_PREFIX = '**Local preview:**'
+
 /** The heading the checklist sits under, printed outside the delimiters so a carried checklist never doubles it. */
 const CHECKLIST_HEADING = '## What to look at'
 
@@ -128,6 +131,9 @@ export function evidenceMarker(head: string): string {
  *
  * A checklist closes the body, below the comparison it annotates, so one
  * comment carries the preview address, the screenshots, and what to look at.
+ *
+ * A local address sits under the hosted one, never above it, so the hosted
+ * line keeps the first-line position `findEvidencePreview` reads.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -136,9 +142,13 @@ export function renderEvidenceBody(
   head: string,
   preview?: string,
   checklist?: string,
+  local?: string,
 ): string {
-  const opening =
-    preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`, '']
+  const addresses = [
+    ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
+    ...(local === undefined ? [] : [`${LOCAL_PREFIX} ${local}`]),
+  ]
+  const opening = addresses.length === 0 ? [] : [...addresses, '']
   const closing =
     checklist === undefined
       ? []
@@ -223,6 +233,36 @@ export function findEvidencePreview(
   return first.slice(PREVIEW_PREFIX.length).trim() || undefined
 }
 
+/**
+ * Where the local address line sits in a body, searched only through the
+ * opening block above the first blank line, so a line quoted further down in
+ * a checklist is never taken for it. -1 when the block carries none.
+ */
+export function findLocalLineIndex(body: string): number {
+  const lines = body.split('\n')
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = (lines[index] ?? '').trim()
+    if (line === '') return -1
+    if (line.startsWith(LOCAL_PREFIX)) return index
+  }
+  return -1
+}
+
+/**
+ * The local address the marked comment already carries, carried forward on a
+ * re-render the way the hosted preview is.
+ */
+export function findEvidenceLocal(
+  comments: readonly EvidenceComment[],
+): string | undefined {
+  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
+  if (marked === undefined) return undefined
+  const index = findLocalLineIndex(marked.body)
+  if (index === -1) return undefined
+  const line = marked.body.split('\n')[index]?.trim() ?? ''
+  return line.slice(LOCAL_PREFIX.length).trim() || undefined
+}
+
 /**
  * The checklist the marked comment already carries, read back out of its
  * delimiters. The handoff file is deleted once posted, so every later render

package/src/pr/local.ts

@@ -0,0 +1,125 @@
+import { findLocalLineIndex } from '@/pr/evidence'
+
+/**
+ * The folder linked worktrees sit under. A listener there belongs to another
+ * branch even though its cwd sits inside the main checkout's toplevel.
+ */
+const LINKED_WORKTREES = '.claude/worktrees'
+
+/** The state `/proc/net/tcp` writes for a socket in LISTEN. */
+const PROC_LISTEN_STATE = '0A'
+
+export type LocalRefusal = 'no-server' | 'no-listener-reader'
+
+export interface Listener {
+  readonly port: number
+  readonly pid: number
+}
+
+/** The machine reads a detection makes, injected so it can be driven without binding a socket. */
+export interface LocalRunner {
+  /** Every TCP socket in LISTEN with its owning pid, or undefined when this machine offers no way to read them. */
+  listListeners(): Promise<readonly Listener[] | undefined>
+  cwdOf(pid: number): Promise<string | undefined>
+  /** Whether the port serves an HTML page at its root inside the runner's timeout. */
+  probe(port: number): Promise<boolean>
+}
+
+export type LocalResult =
+  | { readonly kind: 'found'; readonly port: number; readonly url: string }
+  | { readonly kind: 'refused'; readonly reason: LocalRefusal }
+
+function isInside(path: string, root: string): boolean {
+  return path === root || path.startsWith(`${root}/`)
+}
+
+/**
+ * Whether a process running in `cwd` serves this worktree. A tool that
+ * changes into a subfolder before listening still counts, while a sibling
+ * worktree nested under the main checkout's `.claude/worktrees/` does not.
+ */
+function belongsTo(cwd: string, worktreeRoot: string): boolean {
+  return (
+    isInside(cwd, worktreeRoot) &&
+    !isInside(cwd, `${worktreeRoot}/${LINKED_WORKTREES}`)
+  )
+}
+
+/**
+ * Finds the server this worktree is running: the lowest port whose listening
+ * process runs inside the worktree and answers an HTTP probe. A port rather
+ * than a process is the unit, since one dev server often holds a second
+ * socket for its reload channel, and the lower one is the page by convention.
+ */
+export async function findLocalServer(
+  worktreeRoot: string,
+  runner: LocalRunner,
+): Promise<LocalResult> {
+  const listeners = await runner.listListeners()
+  if (listeners === undefined) {
+    return { kind: 'refused', reason: 'no-listener-reader' }
+  }
+
+  const cwdByPid = new Map<number, string | undefined>()
+  const ports = new Set<number>()
+  for (const { pid, port } of listeners) {
+    if (!cwdByPid.has(pid)) cwdByPid.set(pid, await runner.cwdOf(pid))
+    const cwd = cwdByPid.get(pid)
+    if (cwd !== undefined && belongsTo(cwd, worktreeRoot)) ports.add(port)
+  }
+
+  for (const port of [...ports].sort((a, b) => a - b)) {
+    if (await runner.probe(port)) {
+      return { kind: 'found', port, url: `http://localhost:${port}` }
+    }
+  }
+  return { kind: 'refused', reason: 'no-server' }
+}
+
+/** Reads `lsof -nP -iTCP -sTCP:LISTEN -Fpn` output, where a `p` line opens a process and each `n` line names one of its sockets. */
+export function parseLsofListeners(text: string): Listener[] {
+  const listeners: Listener[] = []
+  let pid: number | undefined
+  for (const line of text.split('\n')) {
+    if (line.startsWith('p')) pid = Number(line.slice(1))
+    if (!line.startsWith('n') || pid === undefined) continue
+    const port = Number(line.slice(line.lastIndexOf(':') + 1))
+    if (Number.isInteger(port) && port > 0) listeners.push({ pid, port })
+  }
+  return listeners
+}
+
+export interface ProcSocket {
+  readonly port: number
+  readonly inode: string
+}
+
+/** Reads `/proc/net/tcp` or `tcp6`, keeping each listening socket's port and inode for matching against `/proc/<pid>/fd`. */
+export function parseProcNetTcp(text: string): ProcSocket[] {
+  const sockets: ProcSocket[] = []
+  for (const line of text.split('\n').slice(1)) {
+    const fields = line.trim().split(/\s+/)
+    const local = fields[1]
+    const state = fields[3]
+    const inode = fields[9]
+    if (local === undefined || inode === undefined) continue
+    if (state !== PROC_LISTEN_STATE) continue
+    const port = Number.parseInt(local.slice(local.lastIndexOf(':') + 1), 16)
+    if (Number.isInteger(port) && port > 0) sockets.push({ port, inode })
+  }
+  return sockets
+}
+
+/**
+ * Replaces the local address line of a marked body with `note`, leaving
+ * every other byte in place so the trailing marker, the checklist delimiters,
+ * and any ticked box survive. Undefined when the body carries no such line,
+ * which is also what a second strip of the same body returns.
+ */
+export function stripLocalLine(body: string, note: string): string | undefined {
+  const index = findLocalLineIndex(body)
+  if (index === -1) return undefined
+  const lines = body.split('\n')
+  lines[index] = note
+  return lines.join('\n')
+}