@erclx/aitk 0.100.0 → 0.102.0

package/src/teach/workspace.ts

@@ -0,0 +1,797 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+import { type BodyLine, bodyLines } from '@/markdown/scan'
+
+export const TEACH_REFUSALS = [
+  'no-teach',
+  'no-workspace',
+  'ambiguous',
+  'exists',
+  'no-file',
+  'no-section',
+  'listed',
+  'defined',
+  'bad-input',
+] as const
+
+export type TeachRefusal = (typeof TEACH_REFUSALS)[number]
+
+export interface TeachRefused {
+  readonly ok: false
+  readonly reason: TeachRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/** The files and folders `standards/teach.md` fixes for a workspace. */
+export const TEACH_MISSION = 'MISSION.md'
+export const TEACH_RESOURCES = 'RESOURCES.md'
+export const TEACH_GLOSSARY = 'GLOSSARY.md'
+export const TEACH_REFERENCE = 'reference'
+export const TEACH_RECORDS = 'learning-records'
+export const TEACH_LESSONS = 'lessons'
+
+/**
+ * A workspace folder as the standard names it, capturing the ordinal and the
+ * topic separately so a listing sorts by the first and a selector matches the
+ * second.
+ */
+export const WORKSPACE_NAME = /^(\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)$/
+
+const TOPIC_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+const READ_HEADING = '## Read'
+const LEADS_HEADING = '## Leads'
+
+/**
+ * The line a scaffolded section carries until something real lands in it. An
+ * empty section reads as one someone forgot to write, and the insert verbs drop
+ * this line as the first real entry arrives.
+ */
+const PLACEHOLDER = '- None yet.'
+
+/** Two digits on the folder, per the standard, because a person opens few. */
+const ORDINAL_WIDTH = 2
+
+const DATE_LENGTH = 'YYYY-MM-DD'.length
+
+export interface WorkspaceSummary {
+  readonly slug: string
+  /** `NaN` when the folder name carries no ordinal, which a listing reports. */
+  readonly ordinal: number
+  readonly topic: string
+  /** Relative to the root, so a caller prints a path a reader can open. */
+  readonly path: string
+  readonly title: string | undefined
+  readonly opened: string | undefined
+  readonly lessons: number
+  readonly records: number
+  readonly reference: number
+  readonly terms: number
+  /** Required files the workspace does not carry, by the standard's layout. */
+  readonly missing: readonly string[]
+}
+
+export interface WorkspaceDetail extends WorkspaceSummary {
+  readonly lessonFiles: readonly string[]
+  readonly recordFiles: readonly string[]
+  readonly referenceFiles: readonly string[]
+  readonly glossary: readonly string[]
+}
+
+export interface WorkspacesListed {
+  readonly ok: true
+  readonly workspaces: readonly WorkspaceSummary[]
+  /** The ordinal an open would take, so no caller derives one by hand. */
+  readonly next: string
+}
+
+export interface WorkspaceRead {
+  readonly ok: true
+  readonly workspace: WorkspaceDetail
+}
+
+export interface WorkspaceOpened {
+  readonly ok: true
+  readonly slug: string
+  readonly path: string
+  readonly created: readonly string[]
+}
+
+export interface SourcesWritten {
+  readonly ok: true
+  readonly slug: string
+  readonly path: string
+  readonly read: readonly Source[]
+  readonly leads: readonly Source[]
+}
+
+export interface TermsWritten {
+  readonly ok: true
+  readonly slug: string
+  readonly path: string
+  readonly defined: readonly Term[]
+}
+
+export type ListOutcome = WorkspacesListed | TeachRefused
+export type ReadOutcome = WorkspaceRead | TeachRefused
+export type OpenOutcome = WorkspaceOpened | TeachRefused
+export type SourceOutcome = SourcesWritten | TeachRefused
+export type TermOutcome = TermsWritten | TeachRefused
+
+export interface Source {
+  readonly title: string
+  readonly url: string
+}
+
+export interface Term {
+  readonly term: string
+  readonly definition: string
+}
+
+export interface OpenRequest {
+  readonly topic: string
+  readonly subject: string
+  readonly startingPoint: string
+  readonly success: readonly string[]
+  readonly outOfScope: readonly string[]
+  readonly title?: string
+  readonly date?: string
+}
+
+function refuse(
+  reason: TeachRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): TeachRefused {
+  return { ok: false, reason, message, detail }
+}
+
+/**
+ * Every workspace sits under the main worktree root rather than under the
+ * checkout the caller stands in. Resolving that root belongs to the caller, so
+ * this takes one and never reads the working directory.
+ */
+export function teachDir(root: string): string {
+  return join(root, '.claude', 'teach')
+}
+
+async function listSlugs(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function filesIn(
+  dir: string,
+  folder: string,
+  suffix?: string,
+): Promise<string[]> {
+  const path = join(dir, folder)
+  if (!existsSync(path)) return []
+
+  const entries = await readdir(path, { withFileTypes: true })
+
+  return entries
+    .filter(
+      (entry) => entry.isFile() && (!suffix || entry.name.endsWith(suffix)),
+    )
+    .map((entry) => entry.name)
+    .sort()
+}
+
+function isEntry(line: string): boolean {
+  const trimmed = line.trim()
+  return trimmed.startsWith('- ') && trimmed !== PLACEHOLDER
+}
+
+/** One bullet per term the subject defines, which is what a glossary holds. */
+function glossaryTerms(text: string): string[] {
+  return unfenced(text)
+    .map((line) => line.text)
+    .filter(isEntry)
+    .map((line) => line.trim().slice('- '.length))
+}
+
+/** The ordinal a folder name carries, or `NaN` when it carries none. */
+function ordinalOf(slug: string): number {
+  const match = WORKSPACE_NAME.exec(slug)
+  return match ? Number(match[1]) : Number.NaN
+}
+
+async function summarize(
+  root: string,
+  dir: string,
+  slug: string,
+): Promise<WorkspaceDetail> {
+  const match = WORKSPACE_NAME.exec(slug)
+  const missionPath = join(dir, TEACH_MISSION)
+  const frontmatter = existsSync(missionPath)
+    ? parseFrontmatter(await readFile(missionPath, 'utf8'))
+    : undefined
+
+  const glossaryPath = join(dir, TEACH_GLOSSARY)
+  const glossary = existsSync(glossaryPath)
+    ? glossaryTerms(await readFile(glossaryPath, 'utf8'))
+    : []
+
+  const [lessonFiles, recordFiles, referenceFiles] = await Promise.all([
+    filesIn(dir, TEACH_LESSONS),
+    filesIn(dir, TEACH_RECORDS, '.md'),
+    filesIn(dir, TEACH_REFERENCE, '.md'),
+  ])
+
+  return {
+    slug,
+    ordinal: match ? Number(match[1]) : Number.NaN,
+    topic: match ? match[2] : slug,
+    path: relative(root, dir),
+    title: readField(frontmatter, 'title'),
+    opened: readField(frontmatter, 'date'),
+    lessons: lessonFiles.length,
+    records: recordFiles.length,
+    reference: referenceFiles.length,
+    terms: glossary.length,
+    missing: [TEACH_MISSION, TEACH_RESOURCES, TEACH_GLOSSARY].filter(
+      (file) => !existsSync(join(dir, file)),
+    ),
+    lessonFiles,
+    recordFiles,
+    referenceFiles,
+    glossary,
+  }
+}
+
+function byOrdinal(left: WorkspaceSummary, right: WorkspaceSummary): number {
+  if (Number.isNaN(left.ordinal)) return Number.isNaN(right.ordinal) ? 0 : 1
+  if (Number.isNaN(right.ordinal)) return -1
+  return left.ordinal - right.ordinal
+}
+
+/**
+ * Reads the ordinals off the folder names rather than off summaries, so opening
+ * a workspace costs one directory listing instead of a read of every file in
+ * every workspace already there.
+ */
+function nextOrdinal(slugs: readonly string[]): string {
+  const highest = slugs
+    .map(ordinalOf)
+    .filter((ordinal) => !Number.isNaN(ordinal))
+    .reduce((carry, ordinal) => Math.max(carry, ordinal), 0)
+
+  return String(highest + 1).padStart(ORDINAL_WIDTH, '0')
+}
+
+/**
+ * Every workspace under the root, with the ordinal a new one would take.
+ *
+ * A folder failing the name pattern is listed rather than dropped, since
+ * dropping it hides the one workspace a session most needs to see. Its ordinal
+ * reads as absent, it sorts last, and it never moves the next number.
+ */
+export async function listWorkspaces(root: string): Promise<ListOutcome> {
+  const dir = teachDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-teach', `No teach folder at ${relative(root, dir)}.`)
+  }
+
+  const slugs = await listSlugs(dir)
+
+  const workspaces = await Promise.all(
+    slugs.map((slug) => summarize(root, join(dir, slug), slug)),
+  )
+
+  return {
+    ok: true,
+    workspaces: [...workspaces].sort(byOrdinal),
+    next: nextOrdinal(slugs),
+  }
+}
+
+/**
+ * The workspace a selector names, matched on the folder name or on the topic
+ * behind the ordinal. Two topics matching is a refusal rather than a pick,
+ * because the caller meant one of them and no verb here can say which.
+ */
+async function findWorkspace(
+  root: string,
+  selector: string,
+): Promise<{ slug: string; dir: string } | TeachRefused> {
+  const dir = teachDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-teach', `No teach folder at ${relative(root, dir)}.`)
+  }
+
+  const slugs = await listSlugs(dir)
+  const matched = slugs.filter(
+    (slug) => slug === selector || WORKSPACE_NAME.exec(slug)?.[2] === selector,
+  )
+
+  if (matched.length === 0) {
+    return refuse('no-workspace', `No workspace named ${selector}.`, slugs)
+  }
+
+  if (matched.length > 1) {
+    return refuse(
+      'ambiguous',
+      `${selector} names ${matched.length} workspaces.`,
+      matched,
+    )
+  }
+
+  return { slug: matched[0], dir: join(dir, matched[0]) }
+}
+
+/** One workspace with the filenames behind each count. */
+export async function readWorkspace(
+  root: string,
+  selector: string,
+): Promise<ReadOutcome> {
+  const found = await findWorkspace(root, selector)
+  if ('ok' in found) return found
+
+  return { ok: true, workspace: await summarize(root, found.dir, found.slug) }
+}
+
+function titleFor(topic: string, given: string | undefined): string {
+  if (given) return given
+
+  const words = topic.split('-')
+  return [
+    words[0].charAt(0).toUpperCase() + words[0].slice(1),
+    ...words.slice(1),
+  ].join(' ')
+}
+
+function missionText(
+  request: OpenRequest,
+  title: string,
+  date: string,
+): string {
+  const outOfScope =
+    request.outOfScope.length > 0
+      ? request.outOfScope
+      : ['Nothing has been ruled out yet.']
+
+  return [
+    '---',
+    `title: ${title}`,
+    `description: ${request.subject}`,
+    `date: ${date}`,
+    '---',
+    '',
+    `# ${title}`,
+    '',
+    request.subject,
+    '',
+    '## Starting point',
+    '',
+    request.startingPoint,
+    '',
+    '## Success looks like',
+    '',
+    ...request.success.map((line) => `- ${line}`),
+    '',
+    '## Out of scope',
+    '',
+    ...outOfScope.map((line) => `- ${line}`),
+    '',
+  ].join('\n')
+}
+
+function resourcesText(title: string): string {
+  return [
+    '---',
+    `title: Sources for ${title}`,
+    `description: Sources read for ${title}, and leads found but not opened`,
+    '---',
+    '',
+    `# Sources for ${title}`,
+    '',
+    'Sources that stand behind this workspace, kept apart from leads nobody opened.',
+    '',
+    READ_HEADING,
+    '',
+    PLACEHOLDER,
+    '',
+    LEADS_HEADING,
+    '',
+    PLACEHOLDER,
+    '',
+  ].join('\n')
+}
+
+function glossaryText(title: string): string {
+  return [
+    '---',
+    `title: Glossary for ${title}`,
+    `description: Terms ${title} defines, one entry each`,
+    '---',
+    '',
+    `# Glossary for ${title}`,
+    '',
+    'One entry per term the subject defines, sorted alphabetically.',
+    '',
+    PLACEHOLDER,
+    '',
+  ].join('\n')
+}
+
+/** Today as `YYYY-MM-DD`, which is the one field the mission dates. */
+function today(): string {
+  return new Date().toISOString().slice(0, DATE_LENGTH)
+}
+
+/**
+ * Creates a workspace at the next ordinal with all three required files.
+ *
+ * The ordinal, the folder name, and every path are derived here rather than by
+ * the caller. A caller standing in a linked worktree cannot reach this root
+ * through its file-editing tools, so a path it composed by hand is one nothing
+ * checks before the write lands somewhere else.
+ */
+export async function openWorkspace(
+  root: string,
+  request: OpenRequest,
+): Promise<OpenOutcome> {
+  if (!TOPIC_SLUG.test(request.topic)) {
+    return refuse('bad-input', `Not a kebab-case topic: ${request.topic}.`, [
+      request.topic,
+    ])
+  }
+
+  if (request.success.length === 0) {
+    return refuse(
+      'bad-input',
+      'A mission needs at least one success line. Pass --success <line>.',
+    )
+  }
+
+  const dir = teachDir(root)
+  await mkdir(dir, { recursive: true })
+
+  const slugs = await listSlugs(dir)
+  const existing = slugs.find(
+    (slug) => WORKSPACE_NAME.exec(slug)?.[2] === request.topic,
+  )
+
+  if (existing) {
+    return refuse(
+      'exists',
+      `${existing} already covers ${request.topic}. Resume it rather than opening a second.`,
+      [existing],
+    )
+  }
+
+  const slug = `${nextOrdinal(slugs)}-${request.topic}`
+  const folder = join(dir, slug)
+  const title = titleFor(request.topic, request.title)
+
+  await mkdir(folder, { recursive: true })
+
+  const files: ReadonlyArray<readonly [string, string]> = [
+    [TEACH_MISSION, missionText(request, title, request.date ?? today())],
+    [TEACH_RESOURCES, resourcesText(title)],
+    [TEACH_GLOSSARY, glossaryText(title)],
+  ]
+
+  for (const [name, text] of files) {
+    await writeFile(join(folder, name), text)
+  }
+
+  return {
+    ok: true,
+    slug,
+    path: relative(root, folder),
+    created: files.map(([name]) => join(relative(root, folder), name)),
+  }
+}
+
+interface Range {
+  readonly start: number
+  readonly end: number
+}
+
+/**
+ * Body lines outside every fence, each still carrying the source line it came
+ * from. `bodyLines` numbers from one past the frontmatter it drops, so `number
+ * - 1` addresses the same line in the array a caller splits itself.
+ */
+function unfenced(text: string): BodyLine[] {
+  return bodyLines(text).filter((line) => !line.fenced)
+}
+
+/**
+ * The half-open source range a heading owns, ending at the next heading of the
+ * same level or above. A heading quoted inside a fenced example selects nothing,
+ * since the scan never sees it.
+ */
+function sectionRange(
+  lines: readonly BodyLine[],
+  heading: string,
+  total: number,
+): Range | undefined {
+  let start: number | undefined
+
+  for (const line of lines) {
+    if (start === undefined) {
+      if (line.text.trim() === heading) start = line.number
+      continue
+    }
+
+    if (/^##?[ \t]/.test(line.text)) return { start, end: line.number - 1 }
+  }
+
+  return start === undefined ? undefined : { start, end: total }
+}
+
+/**
+ * The half-open source range holding a bullet list, from its first entry to the
+ * last line of its last entry. A list carrying only the placeholder yields that
+ * line's range, so the first real entry replaces it rather than landing beside
+ * it.
+ *
+ * An indented non-blank line extends the range because that is how markdown
+ * wraps an entry too long for one line. An unindented one does not, so a
+ * paragraph written under a list stays outside and is neither sorted nor moved.
+ */
+function bulletRange(
+  lines: readonly BodyLine[],
+  within?: Range,
+): Range | undefined {
+  let first: number | undefined
+  let last: number | undefined
+
+  for (const line of lines) {
+    const index = line.number - 1
+
+    if (within && (index < within.start || index >= within.end)) continue
+
+    if (line.text.trim().startsWith('- ')) {
+      first ??= index
+      last = index
+      continue
+    }
+
+    const wraps = first !== undefined && /^\s+\S/.test(line.text)
+    if (wraps) last = index
+  }
+
+  return first === undefined || last === undefined
+    ? undefined
+    : { start: first, end: last + 1 }
+}
+
+/**
+ * The bullet blocks in a run of lines, each a bullet with the continuation lines
+ * wrapped under it.
+ *
+ * Splitting on the bullet marker rather than keeping the lines that are bullets
+ * is what holds a wrapped entry together. A filter over lines keeps the first
+ * line of one and silently drops the rest, which loses half of every entry an
+ * author wrapped at the margin.
+ */
+function bulletBlocks(lines: readonly string[]): string[][] {
+  const blocks: string[][] = []
+
+  for (const line of lines) {
+    if (line.trim().startsWith('- ')) {
+      blocks.push([line])
+      continue
+    }
+
+    blocks.at(-1)?.push(line)
+  }
+
+  return blocks.filter((block) => block[0].trim() !== PLACEHOLDER)
+}
+
+/**
+ * Places entries in a line range, dropping the scaffolded placeholder as the
+ * first real entry lands. `sorted` merges alphabetically and anything else
+ * appends, which is the split between a glossary and a source list.
+ */
+function placeEntries(
+  lines: readonly string[],
+  range: Range,
+  entries: readonly string[],
+  sorted: boolean,
+): string {
+  const kept = bulletBlocks(lines.slice(range.start, range.end))
+  const added = entries.map((entry) => [entry])
+
+  const placed = sorted
+    ? [...kept, ...added].sort((left, right) =>
+        left[0].toLowerCase().localeCompare(right[0].toLowerCase()),
+      )
+    : [...kept, ...added]
+
+  return [
+    ...lines.slice(0, range.start),
+    ...placed.flat(),
+    ...lines.slice(range.end),
+  ].join('\n')
+}
+
+/** Appends entries under a heading, keeping the blank lines around the list. */
+function insertUnderHeading(
+  text: string,
+  heading: string,
+  entries: readonly string[],
+): string | undefined {
+  const lines = text.split('\n')
+  const body = unfenced(text)
+  const section = sectionRange(body, heading, lines.length)
+  if (!section) return undefined
+
+  const bullets = bulletRange(body, section)
+
+  if (!bullets) {
+    return [
+      ...lines.slice(0, section.start),
+      '',
+      ...entries,
+      '',
+      ...lines.slice(section.end),
+    ].join('\n')
+  }
+
+  return placeEntries(lines, bullets, entries, false)
+}
+
+async function openFile(
+  dir: string,
+  slug: string,
+  name: string,
+): Promise<string | TeachRefused> {
+  const path = join(dir, name)
+
+  if (!existsSync(path)) {
+    return refuse('no-file', `${slug} carries no ${name}.`)
+  }
+
+  return path
+}
+
+/**
+ * Appends sources to `RESOURCES.md`, keeping what was read apart from what was
+ * only found.
+ *
+ * A URL already listed under either heading is refused rather than repeated,
+ * since a second entry for one source splits what rests on it across two lines.
+ */
+export async function recordSources(
+  root: string,
+  selector: string,
+  read: readonly Source[],
+  leads: readonly Source[],
+): Promise<SourceOutcome> {
+  const found = await findWorkspace(root, selector)
+  if ('ok' in found) return found
+
+  const path = await openFile(found.dir, found.slug, TEACH_RESOURCES)
+  if (typeof path !== 'string') return path
+
+  let text = await readFile(path, 'utf8')
+  const listed = unfenced(text)
+    .map((line) => line.text)
+    .filter(isEntry)
+
+  const repeated = [...read, ...leads].filter((source) =>
+    listed.some((line) => line.includes(`(${source.url})`)),
+  )
+
+  if (repeated.length > 0) {
+    return refuse(
+      'listed',
+      `${TEACH_RESOURCES} already lists ${repeated.map((source) => source.url).join(', ')}.`,
+      repeated.map((source) => source.url),
+    )
+  }
+
+  for (const [heading, sources] of [
+    [READ_HEADING, read],
+    [LEADS_HEADING, leads],
+  ] as const) {
+    if (sources.length === 0) continue
+
+    const written = insertUnderHeading(
+      text,
+      heading,
+      sources.map((source) => `- [${source.title}](${source.url})`),
+    )
+
+    if (written === undefined) {
+      return refuse(
+        'no-section',
+        `${TEACH_RESOURCES} carries no ${heading} section to write into.`,
+        [heading],
+      )
+    }
+
+    text = written
+  }
+
+  await writeFile(path, text)
+
+  return { ok: true, slug: found.slug, path, read, leads }
+}
+
+/**
+ * The entry shape the standard fixes, which leads with the bolded term.
+ *
+ * The definition is terminated before the citation is appended, since a caller
+ * passing a bare phrase would otherwise run it into the sentence naming where
+ * the term first appears.
+ */
+function termEntry(term: Term, firstSeen: string | undefined): string {
+  const definition = /[.!?]$/.test(term.definition)
+    ? term.definition
+    : `${term.definition}.`
+
+  const where = firstSeen ? ` First seen in ${firstSeen}.` : ''
+
+  return `- **${term.term}**: ${definition}${where}`
+}
+
+/** The term a glossary entry defines, read back out of its bolded span. */
+function definedTerm(entry: string): string {
+  return entry.replace(/^\*\*(.+?)\*\*.*$/s, '$1').toLowerCase()
+}
+
+/**
+ * Adds terms to `GLOSSARY.md`, alphabetically, in one read and one write.
+ *
+ * A term already defined is refused rather than replaced. A definition the
+ * subject has moved under is a revision of the entry rather than a second one,
+ * and no verb here can tell those two apart from the command line.
+ */
+export async function defineTerms(
+  root: string,
+  selector: string,
+  terms: readonly Term[],
+  firstSeen: string | undefined,
+): Promise<TermOutcome> {
+  const found = await findWorkspace(root, selector)
+  if ('ok' in found) return found
+
+  const path = await openFile(found.dir, found.slug, TEACH_GLOSSARY)
+  if (typeof path !== 'string') return path
+
+  const text = await readFile(path, 'utf8')
+  const existing = glossaryTerms(text).map(definedTerm)
+
+  const defined = terms.filter((term) =>
+    existing.includes(term.term.toLowerCase()),
+  )
+
+  if (defined.length > 0) {
+    return refuse(
+      'defined',
+      `${TEACH_GLOSSARY} already defines ${defined.map((term) => term.term).join(', ')}.`,
+      defined.map((term) => term.term),
+    )
+  }
+
+  const entries = terms.map((term) => termEntry(term, firstSeen))
+  const lines = text.split('\n')
+  const bullets = bulletRange(unfenced(text))
+
+  // A glossary carries no heading over its list, so the entries land in the
+  // bullet range itself. A file holding none yet is appended to, which covers a
+  // glossary written by hand rather than scaffolded here.
+  const written = bullets
+    ? placeEntries(lines, bullets, entries, true)
+    : `${text.trimEnd()}\n\n${entries.join('\n')}\n`
+
+  await writeFile(path, written)
+
+  return { ok: true, slug: found.slug, path, defined: terms }
+}