@erclx/canon 4.3.0 → 4.5.0

package/src/paths.ts

@@ -0,0 +1,16 @@
+import { sep } from 'node:path'
+
+/**
+ * Whether a resolved path is the directory itself or sits inside it. The
+ * separator guard is the whole of it: a bare prefix test reads
+ * `.claude/plans-archive` as living under `.claude/plans`, which is a sibling
+ * rather than a child and is exactly the pair the plan folders spell.
+ *
+ * It lives at the root rather than beside either caller because both resolve
+ * plan paths and only one of them may reach `src/tasks/archive.ts`, whose
+ * index regeneration pulls in a Bun-only import that a test running under
+ * Vitest cannot load.
+ */
+export function isUnder(path: string, dir: string): boolean {
+  return path === dir || path.startsWith(`${dir}${sep}`)
+}

package/src/record-root.ts

@@ -0,0 +1,134 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The roots a session record folder is read at, in precedence order.
+ *
+ * `.canon/` wins because a tree that carries it has been migrated, and reading
+ * `.claude/` there would answer from the copy the move left behind. A tree that
+ * carries neither is every tree today, which is what keeps this branch a no-op
+ * until the move lands.
+ *
+ * The shape is `readStamp`'s: order the spellings, take the first that exists,
+ * and stand the creation default in when none does.
+ */
+export const RECORD_ROOTS = ['.canon', '.claude'] as const
+
+export type RecordRoot = (typeof RECORD_ROOTS)[number]
+
+/**
+ * The root a record folder is created at.
+ *
+ * It disagrees with the read precedence above on purpose, and the disagreement
+ * is the whole of this branch. Creating under `.canon/` before the move would
+ * write records to a root whose ignore line may not have reached a target yet,
+ * and it would split one project's records across two roots with no verb able
+ * to reconcile them. The move flips this line and nothing else.
+ */
+export const CREATION_ROOT: RecordRoot = '.claude'
+
+/**
+ * The deletable scratch folder, named at the spelling `.claude/` gives it.
+ *
+ * It is the one folder whose name differs by root. Inside a dotted root the
+ * leading dot hides nothing already hidden and costs a bare `ls` that omits the
+ * folder, so the move drops it. Every other record folder keeps its name,
+ * `.records.git` included, where the dot marks the mechanism apart from a
+ * payload rather than hiding it.
+ */
+export const SCRATCH = '.tmp'
+
+/** The scratch folder's name under `.canon/`. */
+const CANON_SCRATCH = 'tmp'
+
+/** How a root spells a folder name. Only the scratch folder differs. */
+function spell(root: RecordRoot, folder: string): string {
+  return root === '.canon' && folder === SCRATCH ? CANON_SCRATCH : folder
+}
+
+/**
+ * The root a folder resolves at: the first that carries it, and the creation
+ * default when neither does.
+ *
+ * Presence is read on the record folder itself rather than on the full path, so
+ * an archive or a payload that does not exist yet still resolves beside the
+ * records it belongs to rather than at the creation default.
+ */
+function rootOf(root: string, folder: string): RecordRoot {
+  return (
+    RECORD_ROOTS.find((candidate) =>
+      existsSync(join(root, candidate, spell(candidate, folder))),
+    ) ?? CREATION_ROOT
+  )
+}
+
+/**
+ * Where a record folder is read.
+ *
+ * `folder` is the record folder itself and `rest` is whatever sits inside it,
+ * so a caller spells no root and no folder-name variant of its own. A caller
+ * that spells `.claude` by hand is the one thing the move has to find, and one
+ * that calls this is one the move never has to open again.
+ */
+export function recordDir(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string {
+  const at = rootOf(root, folder)
+
+  return join(root, at, spell(at, folder), ...rest)
+}
+
+/**
+ * Every root a record folder would be read at, in precedence order, whether or
+ * not it is on disk.
+ *
+ * Containment tests take this rather than `recordDir`, since a path written
+ * against the root a tree no longer uses is still a path into that folder and
+ * reading it as outside would report a shipped plan as still live.
+ */
+export function recordDirs(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string[] {
+  return RECORD_ROOTS.map((candidate) =>
+    join(root, candidate, spell(candidate, folder), ...rest),
+  )
+}
+
+/** Where a record folder is created, which is the creation default always. */
+export function creationDir(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string {
+  return join(root, CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
+}
+
+/**
+ * The creation destination relative to the project root, which is the form a
+ * message displays and an option default carries.
+ */
+export function creationRel(folder: string, ...rest: string[]): string {
+  return join(CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
+}
+
+/**
+ * The record root itself, for a caller whose subject is the root rather than a
+ * folder inside it.
+ *
+ * A half-migrated tree resolves here on the root that exists rather than on the
+ * folders under it, which is what makes the backup history and its work tree
+ * one answer. Splitting them would let a push resolve a history at one root and
+ * stage a work tree at the other, which stages the deletion of every folder the
+ * move relocated.
+ */
+export function recordRoot(root: string): string {
+  return join(
+    root,
+    RECORD_ROOTS.find((candidate) => existsSync(join(root, candidate))) ??
+      CREATION_ROOT,
+  )
+}

package/src/records/backup.ts

@@ -1,16 +1,18 @@
 import { existsSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
+import { recordRoot } from '@/record-root'
 
 /**
- * The folders a backup carries, relative to `.claude/`. Most of them are the
- * `# Claude` group the claude manifest ships, minus three: `.claude/.tmp`,
- * which is defined as deletable without loss, `.claude/worktrees/`, whose
- * contents belong to the enclosing repository already, and
- * `.claude/.records.git/`, which is the history the rest are pushed into. The
- * list is spelled out rather than read off that group so adding an ignore entry
- * cannot silently enlarge the payload.
+ * The folders a backup carries, relative to the record root `workTree` resolves
+ * rather than to `.claude/` specifically, since the same nine names sit under
+ * whichever root a tree holds. Most of them are the `# Claude` group the claude
+ * manifest ships, minus three: the scratch folder, which is defined as deletable
+ * without loss, `worktrees/`, whose contents belong to the enclosing repository
+ * already, and `.records.git/`, which is the history the rest are pushed into.
+ * The list is spelled out rather than read off that group so adding an ignore
+ * entry cannot silently enlarge the payload.
  *
  * `diagrams` is the one name the manifest group does not carry, so a target
  * tracks it where this repository ignores it. That is the second reason to
@@ -65,10 +67,25 @@ const RETIRED_FOLDERS = [
   'task-archive',
 ] as const
 
-/** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */
-const RECORDS_GIT_DIR = join('.claude', '.records.git')
+/** The history directory's own name, which keeps its dot at either record root. */
+const RECORDS_GIT_NAME = '.records.git'
 
-const WORK_TREE = '.claude'
+/**
+ * The tree a backup stages, which is the record root itself.
+ *
+ * It resolves the root rather than each folder under it, so the history and the
+ * work tree are one answer. Resolving them apart would let a half-migrated tree
+ * open a history at one root and stage a work tree at the other, which stages
+ * the deletion of every folder the move relocated and pushes it.
+ */
+function workTree(root: string): string {
+  return recordRoot(root)
+}
+
+/** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */
+function recordsGitDir(root: string): string {
+  return join(workTree(root), RECORDS_GIT_NAME)
+}
 
 /** Both directions name the branch, so a machine whose `init.defaultBranch` differs still lands on it. */
 const RECORDS_BRANCH = 'main'
@@ -150,11 +167,11 @@ interface GitResult {
  * work tree.
  */
 async function records(root: string, args: string[]): Promise<GitResult> {
-  const gitDir = resolve(root, RECORDS_GIT_DIR)
-  const workTree = resolve(root, WORK_TREE)
+  const gitDir = resolve(recordsGitDir(root))
+  const tree = resolve(workTree(root))
 
   const result =
-    await $`git -C ${workTree} --git-dir=${gitDir} --work-tree=${workTree} ${args}`
+    await $`git -C ${tree} --git-dir=${gitDir} --work-tree=${tree} ${args}`
       .env(gitEnv())
       .quiet()
       .nothrow()
@@ -237,13 +254,15 @@ async function enclosingRemoteUrls(
  * cannot be read is what keeps a failed comparison from reading as a pass.
  */
 async function resolveRemote(root: string): Promise<string | BackupRefused> {
-  if (!existsSync(join(root, RECORDS_GIT_DIR))) {
+  const gitDir = recordsGitDir(root)
+
+  if (!existsSync(gitDir)) {
     return refuse(
       'no-repository',
       [
-        `No records history at ${RECORDS_GIT_DIR}. Create it once, against a private repository:`,
-        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} init`,
-        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} remote add origin <private-repo-url>`,
+        `No records history at ${relative(root, gitDir)}. Create it once, against a private repository:`,
+        `  git --git-dir=${gitDir} init`,
+        `  git --git-dir=${gitDir} remote add origin <private-repo-url>`,
       ].join('\n'),
     )
   }
@@ -254,7 +273,7 @@ async function resolveRemote(root: string): Promise<string | BackupRefused> {
       'no-remote',
       [
         'The records history has no origin. Point it at a private repository:',
-        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} remote add origin <private-repo-url>`,
+        `  git --git-dir=${gitDir} remote add origin <private-repo-url>`,
       ].join('\n'),
     )
   }
@@ -299,8 +318,7 @@ async function scopedFolders(root: string): Promise<string[]> {
   )
 
   return [...BACKED_FOLDERS, ...RETIRED_FOLDERS].filter(
-    (folder) =>
-      existsSync(join(root, WORK_TREE, folder)) || indexed.has(folder),
+    (folder) => existsSync(join(workTree(root), folder)) || indexed.has(folder),
   )
 }
 
@@ -311,7 +329,7 @@ function topSegment(path: string): string {
 /** What a report names, which is the folders a reader can go and open. */
 function presentFolders(root: string): string[] {
   return BACKED_FOLDERS.filter((folder) =>
-    existsSync(join(root, WORK_TREE, folder)),
+    existsSync(join(workTree(root), folder)),
   )
 }
 

package/src/records/size.ts

@@ -1,12 +1,13 @@
 import { existsSync, type Stats } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
+import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
 import { BACKED_FOLDERS } from '@/records/backup'
 
 /**
- * The folders a size reading covers, relative to `.claude/`.
+ * The folders a size reading covers, named at the record root they sit under.
  *
- * It is the backed set plus `.tmp`, which a backup skips because it is
+ * It is the backed set plus the scratch folder, which a backup skips because it is
  * deletable without loss and a reading covers because deletable is not the same
  * as empty: the routing handoffs and the memory archive both sit there and both
  * accumulate. `.records.git` stays out because it is the backup history rather
@@ -14,7 +15,7 @@ import { BACKED_FOLDERS } from '@/records/backup'
  * checkout of the enclosing repository with its own removal verb, and one of
  * them outweighs every record folder combined.
  */
-export const SIZED_FOLDERS = [...BACKED_FOLDERS, '.tmp'] as const
+export const SIZED_FOLDERS = [...BACKED_FOLDERS, SCRATCH] as const
 
 /**
  * The windows a reading reports, in days.
@@ -34,7 +35,7 @@ export interface WindowCount {
 }
 
 export interface FolderSize {
-  /** Relative to `.claude/`, which is the name a reader opens. */
+  /** Relative to the record root, which is the name a reader opens. */
   readonly folder: string
   readonly present: boolean
   readonly files: number
@@ -170,7 +171,7 @@ async function measure(
   folder: string,
   now: number,
 ): Promise<FolderSize> {
-  const path = join(root, '.claude', folder)
+  const path = recordDir(root, folder)
   const empty = GROWTH_WINDOWS.map((days) => ({ days, files: 0 }))
 
   if (!existsSync(path)) {
@@ -212,11 +213,15 @@ export async function sizeRecords(
   root: string,
   now: number = Date.now(),
 ): Promise<SizeOutcome> {
-  if (!existsSync(join(root, '.claude'))) {
+  // Either root answers, so a migrated tree is read rather than refused. The
+  // roots are tested rather than the folders under them, since a project that
+  // holds the root and no records yet is empty rather than absent and the
+  // per-folder `present` flags already say which of the ten it carries.
+  if (!RECORD_ROOTS.some((name) => existsSync(join(root, name)))) {
     return {
       ok: false,
       reason: 'no-folder',
-      message: `No .claude directory at ${root}, so there are no record folders to read.`,
+      message: `No ${RECORD_ROOTS.join(' or ')} directory at ${root}, so there are no record folders to read.`,
     }
   }
 

package/src/records/validate.ts

@@ -3,6 +3,10 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { linesOutsideFences } from '@/markdown/scan'
+import {
+  recordDir as resolveRecordDir,
+  recordDirs as resolveRecordDirs,
+} from '@/record-root'
 import {
   TEACH_GLOSSARY,
   TEACH_MISSION,
@@ -25,22 +29,22 @@ export const RECORD_KINDS = [
 export type RecordKind = (typeof RECORD_KINDS)[number]
 
 /**
- * The folders each kind reads, in precedence order.
+ * The folders standards reads, in precedence order.
  *
- * Standards carry two because the corpus authors at the project root and
- * installs under `.claude/`. The authoring root wins where both exist, since the
+ * It carries two because the corpus authors at the project root and installs
+ * under `.claude/`. The authoring root wins where both exist, since the
  * installed tree is a generated copy here and a finding fixed there is
  * overwritten by the next regen. A project that consumed the corpus holds only
  * the second, so one order serves both.
+ *
+ * Every other kind is a session record and takes the record roots instead,
+ * resolved by `@/record-root`. Standards is the one kind that is tracked, so it
+ * does not move and spells its own two candidates here.
  */
-const FOLDERS_BY_KIND: Readonly<Record<RecordKind, readonly string[]>> = {
-  plans: [join('.claude', 'plans')],
-  groundwork: [join('.claude', 'groundwork')],
-  intake: [join('.claude', 'intake')],
-  memory: [join('.claude', 'memory')],
-  standards: ['standards', join('.claude', 'standards')],
-  teach: [join('.claude', 'teach')],
-}
+const STANDARDS_FOLDERS: readonly string[] = [
+  'standards',
+  join('.claude', 'standards'),
+]
 
 /**
  * `unknown-kind` is raised at the argument boundary rather than by the walk, and
@@ -107,17 +111,31 @@ export type ValidateOutcome = ValidateReport | ValidateRefused
 
 /** Every folder a kind would accept, whether or not it is on disk. */
 export function recordDirs(root: string, kind: RecordKind): string[] {
-  return FOLDERS_BY_KIND[kind].map((folder) => join(root, folder))
+  if (kind === 'standards') {
+    return STANDARDS_FOLDERS.map((folder) => join(root, folder))
+  }
+
+  return resolveRecordDirs(root, kind)
 }
 
 /**
- * The folder a kind reads. The first candidate on disk wins, and the first
- * candidate stands in when none exists, so a refusal and a test fixture both
- * name the location the kind prefers.
+ * The folder a kind reads. The first candidate on disk wins, and the creation
+ * default stands in when none exists, so a refusal and a test fixture both name
+ * the location the kind would be written to.
+ *
+ * The default is where this parts company with `dirs[0]`, which the record
+ * kinds can no longer take: their first candidate is the root the move lands at
+ * and nothing creates there yet, so a fallback reading it would name a folder no
+ * verb would ever write. Standards has no such split, since it is tracked and
+ * its first candidate is where it is authored.
  */
 export function recordsDir(root: string, kind: RecordKind): string {
-  const dirs = recordDirs(root, kind)
-  return dirs.find((dir) => existsSync(dir)) ?? dirs[0]
+  if (kind === 'standards') {
+    const dirs = recordDirs(root, kind)
+    return dirs.find((dir) => existsSync(dir)) ?? dirs[0]
+  }
+
+  return resolveRecordDir(root, kind)
 }
 
 export function isRecordKind(value: string): value is RecordKind {

package/src/repo/metadata.ts

@@ -0,0 +1,206 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * What this run can compute from the tree alone. A field stays absent rather
+ * than empty when nothing local resolves it, so a caller never reads
+ * "nothing to propose" as "propose removing what is already there."
+ */
+export interface MetadataProposal {
+  readonly description?: string
+  readonly homepage?: string
+  readonly topics?: readonly string[]
+}
+
+/** What the remote already carries, read by the caller rather than here. */
+export interface CurrentMetadata {
+  readonly description: string
+  readonly homepage: string
+  readonly topics: readonly string[]
+}
+
+export interface MetadataDiff {
+  readonly description?: { readonly current: string; readonly proposed: string }
+  readonly homepage?: { readonly current: string; readonly proposed: string }
+  readonly topics?: {
+    readonly added: readonly string[]
+    readonly removed: readonly string[]
+  }
+}
+
+/** GitHub's own cap on the About field. */
+const MAX_DESCRIPTION_LENGTH = 350
+
+/** GitHub's own cap on topics per repository. */
+const MAX_TOPICS = 20
+
+/** GitHub's own shape for a topic: lowercase, alphanumeric, internal hyphens. */
+const TOPIC_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+
+/**
+ * Whether an already-trimmed, already-lowercased string is a shape GitHub
+ * accepts as a topic. Exported so a caller validating an operator-supplied
+ * topic list checks against the same rule this reader silently filters
+ * `package.json`'s `keywords` through, rather than reimplementing it against
+ * a looser test such as non-emptiness alone.
+ */
+export function isValidTopic(topic: string): boolean {
+  return TOPIC_PATTERN.test(topic)
+}
+
+/**
+ * A bare image, or an image wrapped in a link, which is the shape a shields.io
+ * badge takes. The wrapped alternative goes first, since the bare form would
+ * otherwise match its inner image alone and leave the wrapping link behind.
+ */
+const BADGE_TOKEN = /\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)|!\[[^\]]*\]\([^)]*\)/g
+
+/** True once every badge token is stripped and nothing remains. */
+function isBadgeLine(line: string): boolean {
+  return line.replace(BADGE_TOKEN, '').trim() === ''
+}
+
+function stripInlineMarkdown(line: string): string {
+  return line
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/(\*\*|__)(.+?)\1/g, '$2')
+    .replace(/(\*|_|`)(.+?)\1/g, '$2')
+    .trim()
+}
+
+/**
+ * The first prose line past the title and any badge row, stripped of inline
+ * markdown and capped at GitHub's About field length.
+ *
+ * `undefined` only when the file carries nothing past its title and badges,
+ * per the skill requirement's refusal boundary: a resolvable line that reads
+ * as a title rather than a sentence is still proposed, since rejecting it is
+ * a judgment for the person reading the proposal rather than for this reader.
+ */
+export function extractOpeningLine(readme: string): string | undefined {
+  for (const raw of readme.split('\n')) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#') || isBadgeLine(line)) continue
+
+    const stripped = stripInlineMarkdown(line)
+    if (stripped === '') continue
+
+    return stripped.length > MAX_DESCRIPTION_LENGTH
+      ? `${stripped.slice(0, MAX_DESCRIPTION_LENGTH - 1)}…`
+      : stripped
+  }
+  return undefined
+}
+
+/**
+ * `package.json`'s `keywords` read as candidate topics, the field the wider
+ * npm ecosystem already uses for this. Invalid entries are dropped silently
+ * rather than refused, since a manifest mixing free-text keywords with
+ * topic-shaped ones is ordinary and only the shaped half transfers.
+ */
+function readTopics(keywords: unknown): readonly string[] | undefined {
+  if (!Array.isArray(keywords)) return undefined
+
+  const topics = new Set<string>()
+  for (const entry of keywords) {
+    if (typeof entry !== 'string') continue
+    const topic = entry.trim().toLowerCase()
+    if (isValidTopic(topic)) topics.add(topic)
+    if (topics.size === MAX_TOPICS) break
+  }
+  return [...topics]
+}
+
+interface PackageFields {
+  readonly homepage?: unknown
+  readonly keywords?: unknown
+}
+
+async function readManifest(root: string): Promise<PackageFields | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(
+      await readFile(join(root, 'package.json'), 'utf8'),
+    )
+    return (parsed ?? undefined) as PackageFields | undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Computes what this tree can propose for its own repository metadata, with
+ * no network call: an About text from the README's opening line, and a
+ * homepage and a topic set from `package.json`, the one manifest every
+ * target project this ships to already carries.
+ *
+ * A field a target project declares nowhere stays absent rather than empty,
+ * so the caller comparing this against the remote never treats a field this
+ * reader has no opinion on as a proposal to clear it.
+ */
+export async function proposeMetadata(root: string): Promise<MetadataProposal> {
+  const [readme, manifest] = await Promise.all([
+    readFile(join(root, 'README.md'), 'utf8').catch(() => undefined),
+    readManifest(root),
+  ])
+
+  const description =
+    readme === undefined ? undefined : extractOpeningLine(readme)
+
+  const homepage =
+    typeof manifest?.homepage === 'string' && manifest.homepage.trim() !== ''
+      ? manifest.homepage.trim()
+      : undefined
+
+  const topics = readTopics(manifest?.keywords)
+
+  return {
+    ...(description !== undefined && { description }),
+    ...(homepage !== undefined && { homepage }),
+    ...(topics !== undefined && topics.length > 0 && { topics }),
+  }
+}
+
+/**
+ * Compares a computed proposal against what the remote already carries.
+ *
+ * A field the proposal has no opinion on is never diffed, which is what
+ * keeps a target project with no `keywords` field from seeing every existing
+ * topic reported as a removal.
+ */
+export function compareMetadata(
+  current: CurrentMetadata,
+  proposed: MetadataProposal,
+): MetadataDiff {
+  const diff: {
+    description?: { current: string; proposed: string }
+    homepage?: { current: string; proposed: string }
+    topics?: { added: readonly string[]; removed: readonly string[] }
+  } = {}
+
+  if (
+    proposed.description !== undefined &&
+    proposed.description !== current.description
+  ) {
+    diff.description = {
+      current: current.description,
+      proposed: proposed.description,
+    }
+  }
+
+  if (
+    proposed.homepage !== undefined &&
+    proposed.homepage !== current.homepage
+  ) {
+    diff.homepage = { current: current.homepage, proposed: proposed.homepage }
+  }
+
+  if (proposed.topics !== undefined) {
+    const currentSet = new Set(current.topics)
+    const proposedSet = new Set(proposed.topics)
+    const added = proposed.topics.filter((topic) => !currentSet.has(topic))
+    const removed = current.topics.filter((topic) => !proposedSet.has(topic))
+    if (added.length > 0 || removed.length > 0) diff.topics = { added, removed }
+  }
+
+  return diff
+}