@erclx/canon 4.2.1 → 4.4.0

package/scripts/lib/sandbox-dispatch.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+
+# The bound on a nested background dispatch, and the recording behind it.
+#
+# An arm invoked without the narration its fixture states dispatched a real
+# `claude --bg` session against the machine's own process table, and nothing in
+# the harness noticed. `snapshot_tree` reads the sandbox and `snapshot_root`
+# reads four scratch directories, and a dispatched session writes into none of
+# them, so the escape watch reported clean throughout and was right to. The run
+# spent real cost until a person found it, and `SIGTERM` alone did not end it.
+#
+# Three mechanisms sit here rather than in `scripts/sandbox/run.sh`, which is the
+# only caller. Each is reachable from a test that never launches a session:
+# `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
+# reap against a `sleep`, where proving either through `run.sh` would mean
+# spawning the thing the bound exists to prevent.
+
+# The prevention. Writes a `claude` that refuses a background dispatch by flag
+# name and delegates everything else, for `run.sh` to place first on the PATH of
+# the session it spawns.
+#
+# The real binary is baked into the file rather than passed through the
+# environment. An env var carrying it would sit in the spawned session's own
+# environment, which hands any arm the exact string that walks around the shim.
+#
+# It names itself in its refusal. No arm shells to `claude` today, and one
+# written tomorrow would meet this and read it as the harness being broken
+# unless the text says which layer refused and why.
+#
+# It is not the whole bound. A dispatch reaching the binary by an absolute path
+# never resolves through PATH at all, which is what `reap_process_group`
+# backstops.
+install_dispatch_shim() {
+  local dir="$1"
+  local real="$2"
+
+  cat >"$dir/claude" <<SHIM
+#!/usr/bin/env bash
+# Generated by install_dispatch_shim in scripts/lib/sandbox-dispatch.sh.
+for arg in "\$@"; do
+  case "\$arg" in
+  --bg | --background)
+    echo "canon sandbox harness: refusing \$arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2
+    exit 64
+    ;;
+  esac
+done
+exec "$real" "\$@"
+SHIM
+
+  chmod +x "$dir/claude"
+}
+
+# True while any process still carries this group id. Reads the whole table
+# rather than `ps -g`, which selects by session on some builds and reports an
+# empty group as a clean exit either way.
+process_group_alive() {
+  ps -eo pgid= 2>/dev/null | tr -d ' ' | grep -qx "$1"
+}
+
+# The backstop. Signals a process group `run.sh` created, escalating rather than
+# sending one signal and reporting success, since the dispatch that produced this
+# row took two signals to reap.
+#
+# Prints its outcome and always exits zero. Every caller runs under `set -e`, and
+# a survivor is something to report rather than a reason to abandon the verdict
+# the run already took.
+#
+# The group has to be one the run created, and the refusal below is what makes
+# that property travel with the function rather than living in one caller.
+# `run.sh` reads the harness group once and reports `inherited` when the session
+# failed to lead a group of its own, which is a diagnosis; this is the floor
+# under it, and under every caller after it, because the cost of getting the
+# argument wrong is the operator's own shell.
+#
+# What it cannot reach is a dispatch that called `setsid` on its way out, which
+# leaves the group before this reads it. That is the half the shim covers.
+reap_process_group() {
+  local pgid="$1"
+
+  if [ "$pgid" = "$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')" ]; then
+    printf 'refused-own-group\n'
+    return 0
+  fi
+
+  if ! process_group_alive "$pgid"; then
+    printf 'clear\n'
+    return 0
+  fi
+
+  kill -TERM -"$pgid" 2>/dev/null || true
+  wait_for_group_exit "$pgid"
+
+  if ! process_group_alive "$pgid"; then
+    printf 'reaped-term\n'
+    return 0
+  fi
+
+  kill -KILL -"$pgid" 2>/dev/null || true
+  wait_for_group_exit "$pgid"
+
+  if process_group_alive "$pgid"; then
+    printf 'survived\n'
+  else
+    printf 'reaped-kill\n'
+  fi
+  return 0
+}
+
+# Five seconds per signal. A shorter window reports a survivor for a process
+# that was already exiting, and a longer one stalls a run whose verdict is
+# already taken.
+wait_for_group_exit() {
+  local pgid="$1"
+  local waited=0
+
+  while [ "$waited" -lt 20 ] && process_group_alive "$pgid"; do
+    sleep 0.25
+    waited=$((waited + 1))
+  done
+}
+
+# The client's own session registry, which is the only surface a nested dispatch
+# leaves a trace on that this harness can read. It is client-owned and carries no
+# contract, so a client that stops writing a record per session breaks the
+# detection silently. That is why what reads it reports rather than asserts.
+sessions_dir() {
+  printf '%s/sessions\n' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+}
+
+# Set whenever the registry directory existed at snapshot time. An absent
+# registry produces the same empty manifest a quiet run does, and the two mean
+# opposite things, so the report carries this rather than letting an unwatched
+# run read as a clean one. Same distinction `escape_watched` draws in `run.sh`,
+# which is also the only reader, hence the exemption on the write below.
+sessions_watched=0
+
+# Record names only, never hashes. A live session rewrites its own record on
+# every status change, so a content manifest would name every session running
+# beside this one, which is the noise the escape watch was already narrowed to
+# avoid. A record that appears between the two snapshots is a session that
+# started during the run, and that is the whole question.
+snapshot_sessions() {
+  local manifest="$1"
+  local dir
+  dir="$(sessions_dir)"
+
+  : >"$manifest"
+  [ -d "$dir" ] || return 0
+  # shellcheck disable=SC2034
+  sessions_watched=1
+
+  find "$dir" -maxdepth 1 -type f -name '*.json' 2>/dev/null |
+    sed 's|.*/||' | sort >"$manifest"
+  return 0
+}
+
+# The new side alone, unlike `writes_between`. A record that vanished is a
+# session that ended and a record that changed is one that was already running,
+# and neither is a dispatch this run made.
+sessions_between() {
+  comm -13 "$1" "$2"
+}
+
+# Turns a record name into a line a person can act on. The file can be gone by
+# the time this reads it, since a session that started and exited inside the run
+# takes its record with it, so an unreadable record still reports its name rather
+# than dropping out of the list.
+#
+# One record is one line. The name is written by whatever peer claimed the
+# session, so a newline inside it would split one record across two entries in a
+# list every reader takes as one line each.
+describe_session() {
+  local record desc
+  record="$(sessions_dir)/$1"
+
+  desc="$(jq -r '"\(.name // "unnamed") in \(.cwd // "an unrecorded directory")"
+    | gsub("\\s+"; " ")' "$record" 2>/dev/null || true)"
+  [ -z "$desc" ] && desc="record already gone"
+
+  printf '%s: %s\n' "$1" "$desc"
+}

package/src/claude/cases/misc.ts

@@ -24,4 +24,8 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: "This test just started failing and I don't know why yet.",
     expect: 'systematic-debugging',
   },
+  {
+    prompt: 'Does our github about text still match what the readme says?',
+    expect: 'repo-metadata',
+  },
 ]

package/src/cli.ts

@@ -37,6 +37,7 @@ import { register as deps } from '@/commands/deps'
 import { register as labels } from '@/commands/labels'
 import { register as autoship } from '@/commands/autoship'
 import { register as pr } from '@/commands/pr'
+import { register as repo } from '@/commands/repo'
 import { register as census } from '@/commands/census'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
@@ -86,6 +87,7 @@ function showHelp(): void {
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
     `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request body against its own diff (key-changes)${NC}`,
+    `${GREY}│${NC}    repo [cmd]         ${GREY}# This repository's own remote metadata (metadata propose, apply)${NC}`,
     `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    gate [cmd]         ${GREY}# Run the merge gate stage by stage (run)${NC}`,
@@ -135,6 +137,7 @@ function showHelp(): void {
     `${GREY}│${NC}    canon secrets scan --json`,
     `${GREY}│${NC}    canon deps audit --json`,
     `${GREY}│${NC}    canon labels audit --json`,
+    `${GREY}│${NC}    canon repo metadata propose --json`,
     `${GREY}│${NC}    canon census --json`,
     `${GREY}│${NC}    canon audits run --json`,
     `${GREY}│${NC}    canon gate run --all --no-write`,
@@ -192,6 +195,7 @@ deps(program)
 labels(program)
 autoship(program)
 pr(program)
+repo(program)
 census(program)
 audits(program)
 gate(program)

package/src/commands/repo.ts

@@ -0,0 +1,393 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  compareMetadata,
+  type CurrentMetadata,
+  isValidTopic,
+  type MetadataDiff,
+  proposeMetadata,
+} from '@/repo/metadata'
+import {
+  intro,
+  logAdd,
+  logInfo,
+  logRemove,
+  logStep,
+  logWarn,
+  outro,
+} from '@/ui'
+
+const GH_TIMEOUT_MS = 30_000
+
+type SourceRefusal = 'gh-missing' | 'gh-failed'
+type ApplyRefusal =
+  | SourceRefusal
+  | 'no-changes'
+  | 'empty-topics'
+  | 'invalid-topics'
+  | 'wrong-repo'
+
+const REFUSALS: Record<ApplyRefusal, string> = {
+  'gh-missing': 'gh is not on the path, so no remote could be read.',
+  'gh-failed':
+    'gh could not read this repository. Check the remote and gh auth status.',
+  'no-changes':
+    'Nothing to apply. Pass --description, --homepage, or --topics with the answered value.',
+  'empty-topics':
+    '--topics carried no usable topic, and this command never reads that as a request to remove every topic the remote carries. Pass the full desired set, or omit the flag to leave topics untouched.',
+  'invalid-topics':
+    '--topics carried an entry GitHub does not accept as a topic (lowercase letters, digits, and internal hyphens only). This command never narrows the desired set silently, since dropping it changes what the remaining diff removes.',
+  'wrong-repo':
+    'The remote --root resolved to is not the one --repo named. This command never writes to a repository the invocation did not explicitly confirm.',
+}
+
+interface ProposeOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+interface ApplyOptions {
+  readonly description?: string
+  readonly homepage?: string
+  readonly topics?: string
+  readonly repo: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+type CurrentRead =
+  | {
+      readonly kind: 'read'
+      readonly current: CurrentMetadata
+      readonly nameWithOwner: string
+    }
+  | { readonly kind: 'refused'; readonly reason: SourceRefusal }
+
+/** Reads what the remote already carries. The one network call this domain makes to read. */
+async function readCurrent(cwd: string): Promise<CurrentRead> {
+  if (Bun.which('gh') === null) return { kind: 'refused', reason: 'gh-missing' }
+
+  try {
+    const result = await execa(
+      'gh',
+      [
+        'repo',
+        'view',
+        '--json',
+        'description,homepageUrl,repositoryTopics,nameWithOwner',
+      ],
+      { cwd, timeout: GH_TIMEOUT_MS, env: gitEnv(), extendEnv: false },
+    )
+    const row = JSON.parse(result.stdout) as {
+      description?: string
+      homepageUrl?: string
+      repositoryTopics?: readonly { name: string }[]
+      nameWithOwner?: string
+    }
+    return {
+      kind: 'read',
+      current: {
+        description: row.description ?? '',
+        homepage: row.homepageUrl ?? '',
+        topics: (row.repositoryTopics ?? []).map((topic) => topic.name),
+      },
+      nameWithOwner: row.nameWithOwner ?? '',
+    }
+  } catch {
+    return { kind: 'refused', reason: 'gh-failed' }
+  }
+}
+
+export function register(program: Command): void {
+  const repo = program
+    .command('repo')
+    .description('Read and write this repository’s own remote metadata')
+    .helpOption('-h, --help', 'Show this help message')
+
+  const metadata = repo
+    .command('metadata')
+    .description('The About description, homepage, and topics GitHub shows')
+    .helpOption('-h, --help', 'Show this help message')
+
+  metadata
+    .command('propose')
+    .description(
+      'Compare a locally computed description, homepage, and topic set against the remote',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        "Computes from the tree alone: a description from the README's opening",
+        'line past its title and badges, and a homepage and topics from',
+        "package.json's own homepage and keywords fields. A field neither file",
+        'declares is never diffed, so an undeclared topic set never reads as a',
+        'proposal to clear what the remote already carries.',
+        '',
+        'This is the read half. It never writes. Run `canon repo metadata apply`',
+        'with the answered fields once a proposal is worth taking.',
+        '',
+        'Exit codes:',
+        '  0  the remote already carries what this run computed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  a difference was found',
+        '',
+        'Examples:',
+        '  canon repo metadata propose',
+        '  canon repo metadata propose --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ProposeOptions) => {
+      process.exitCode = await runPropose(opts)
+    })
+
+  metadata
+    .command('apply')
+    .description(
+      'Write an explicitly supplied description, homepage, or topic set to the remote',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .requiredOption(
+      '--repo <owner/name>',
+      'Repository this run is allowed to write to, checked against what gh resolves',
+    )
+    .option('--description <text>', 'About text to write')
+    .option('--homepage <url>', 'Homepage URL to write')
+    .option(
+      '--topics <list>',
+      'Comma-separated topic set to write, replacing what the remote carries',
+    )
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Takes the answered value for each field directly rather than',
+        're-running propose, so a change this writes is always one a person or',
+        'a second invocation already read and confirmed. --topics is the full',
+        'desired set. gh only takes an add and a remove list, so this reads the',
+        'current set once to compute both. An entry shaped like something other',
+        'than a GitHub topic refuses the whole run rather than being dropped.',
+        '',
+        '--repo is required and takes no default, since --root silently',
+        'resolving to the caller’s own cwd is what turned a verification run',
+        'against this exact command into a live write against a public remote.',
+        'The value is checked against what gh resolves for --root, so the',
+        'write refuses on any repository the invocation did not name aloud.',
+        '',
+        'Exit codes:',
+        '  0  the write succeeded, or the remote already matched',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon repo metadata apply --repo erclx/canon --description "One source for conventions."',
+        '  canon repo metadata apply --repo erclx/canon --topics cli-tool,governance,standards',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ApplyOptions) => {
+      process.exitCode = await runApply(opts)
+    })
+}
+
+function refuse(
+  reason: ApplyRefusal,
+  emitJson: boolean,
+  root: string,
+  detail?: string,
+): number {
+  const message =
+    detail === undefined ? REFUSALS[reason] : `${REFUSALS[reason]} ${detail}`
+
+  logStep('Refused')
+  logWarn(message)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+  }
+  return 1
+}
+
+async function runPropose(opts: ProposeOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon repo metadata propose')
+
+  const [proposal, currentRead] = await Promise.all([
+    proposeMetadata(root),
+    readCurrent(root),
+  ])
+
+  if (currentRead.kind === 'refused') {
+    return refuse(currentRead.reason, emitJson, root)
+  }
+
+  const diff: MetadataDiff = compareMetadata(currentRead.current, proposal)
+  const changed = Object.keys(diff).length > 0
+
+  logStep('Repository')
+  logInfo(currentRead.nameWithOwner)
+
+  logStep('Computed')
+  if (
+    proposal.description === undefined &&
+    proposal.homepage === undefined &&
+    proposal.topics === undefined
+  ) {
+    logInfo('nothing local resolved a description, a homepage, or topics')
+  } else {
+    if (proposal.description !== undefined) {
+      logInfo(`description: ${proposal.description}`)
+    }
+    if (proposal.homepage !== undefined)
+      logInfo(`homepage: ${proposal.homepage}`)
+    if (proposal.topics !== undefined) {
+      logInfo(`topics: ${proposal.topics.join(', ')}`)
+    }
+  }
+
+  logStep(changed ? 'Difference' : 'No difference')
+  if (!changed) {
+    logInfo('the remote already carries what this run computed')
+  } else {
+    if (diff.description !== undefined) {
+      logWarn(
+        `description: "${diff.description.current}" → "${diff.description.proposed}"`,
+      )
+    }
+    if (diff.homepage !== undefined) {
+      logWarn(
+        `homepage: "${diff.homepage.current}" → "${diff.homepage.proposed}"`,
+      )
+    }
+    if (diff.topics !== undefined) {
+      for (const topic of diff.topics.added) logAdd(`topic: ${topic}`)
+      for (const topic of diff.topics.removed) logRemove(`topic: ${topic}`)
+    }
+    logInfo(
+      'Run `canon repo metadata apply` with the answered fields. This run writes nothing.',
+    )
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        repo: currentRead.nameWithOwner,
+        current: currentRead.current,
+        proposal,
+        diff,
+      })}\n`,
+    )
+  }
+
+  return changed ? 2 : 0
+}
+
+async function runApply(opts: ApplyOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon repo metadata apply')
+
+  if (
+    opts.description === undefined &&
+    opts.homepage === undefined &&
+    opts.topics === undefined
+  ) {
+    return refuse('no-changes', emitJson, root)
+  }
+
+  let desired: ReadonlySet<string> | undefined
+  if (opts.topics !== undefined) {
+    const entries = opts.topics
+      .split(',')
+      .map((topic) => topic.trim().toLowerCase())
+      .filter((topic) => topic !== '')
+    if (entries.length === 0) return refuse('empty-topics', emitJson, root)
+
+    const invalid = entries.filter((topic) => !isValidTopic(topic))
+    if (invalid.length > 0) {
+      return refuse(
+        'invalid-topics',
+        emitJson,
+        root,
+        `Invalid: ${invalid.join(', ')}`,
+      )
+    }
+
+    desired = new Set(entries)
+  }
+
+  // Read ahead of every write, never only for --topics, since this is the
+  // one call that confirms --repo names the remote --root actually resolved
+  // to. A write skipping it on a description-only or homepage-only run would
+  // reopen the gap --repo exists to close.
+  const currentRead = await readCurrent(root)
+  if (currentRead.kind === 'refused')
+    return refuse(currentRead.reason, emitJson, root)
+  if (currentRead.nameWithOwner !== opts.repo) {
+    return refuse('wrong-repo', emitJson, root)
+  }
+
+  const args = ['repo', 'edit']
+  if (opts.description !== undefined)
+    args.push('--description', opts.description)
+  if (opts.homepage !== undefined) args.push('--homepage', opts.homepage)
+
+  if (desired !== undefined) {
+    const currentSet = new Set(currentRead.current.topics)
+    const toAdd = [...desired].filter((topic) => !currentSet.has(topic))
+    const toRemove = currentRead.current.topics.filter(
+      (topic) => !desired.has(topic),
+    )
+
+    if (toAdd.length > 0) args.push('--add-topic', toAdd.join(','))
+    if (toRemove.length > 0) args.push('--remove-topic', toRemove.join(','))
+  }
+
+  if (args.length === 2) {
+    logStep('Applied')
+    logInfo('the remote already matches every field supplied. Nothing written.')
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, written: false })}\n`)
+    }
+    return 0
+  }
+
+  if (Bun.which('gh') === null) return refuse('gh-missing', emitJson, root)
+
+  try {
+    await execa('gh', args, {
+      cwd: root,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+  } catch {
+    return refuse('gh-failed', emitJson, root)
+  }
+
+  logStep('Applied')
+  logInfo('gh repo edit wrote the supplied fields to the remote.')
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, written: true })}\n`)
+  }
+
+  return 0
+}