jackherd 1.9.0 → 1.11.0

package/src/check/skill-budgets.ts

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, claudePath, SKILLS_DIRECTORY } from '../claude/paths'
+import { projectLockCandidates } from '../config/legacy-names'
+import { parseManifest } from '../sync/manifest'
+import { matchesGlob } from './glob'
+import { CHECK_STATUS, type CheckResult, type CheckStatus } from './result'
+import type { SkillBudgets } from './schema'
+import {
+  KIT_FILE_FALLBACK_BUDGET,
+  KIT_SKILL_BUDGETS,
+  OWN_SKILL_BUDGET,
+  SUPPLEMENT_BUDGET,
+} from './skill-budget-defaults'
+
+/** Words per path or glob from the project root; a key joining paths with ` + ` budgets them together. */
+export type BudgetTable = Readonly<SkillBudgets>
+
+/** A file with the budget it falls back on when neither the project nor the kit names one. */
+export type FileWords = { path: string; words: number; fallback: number }
+
+export type Measurement = { label: string; words: number; budget: number }
+
+type Overrun = typeof CHECK_STATUS.warn | typeof CHECK_STATUS.fail
+
+type MeasuredOverrun = { entry: Measurement; overrun: Overrun }
+
+const SUPPLEMENTS_DIRECTORY = 'project'
+const KIT_DOCUMENT = /^(skills\/.+\.md|agents\/[^/]+\.md|rules\/kit\/[^/]+\.md)$/
+const KIT_RULE = /^rules\//
+const PATHS_IN_FRONTMATTER = /^---\r?\n(?:(?!---)[^\n]*\n)*?paths:/
+const SUM_SEPARATOR = ' + '
+const FAIL_FACTOR = 1.1
+
+const OVERRUN_LABEL: Record<Overrun, string> = { warn: 'warning', fail: 'error' }
+
+const isGlob = (key: string): boolean => /[*?]/.test(key)
+
+/**
+ * The words of a file as `wc -w` counts them: runs of non-whitespace, over the whole file. The frontmatter counts,
+ * because an agent reads it with the rest, and the skill's description in it is loaded before the body is.
+ */
+export const countWords = (text: string): number => text.split(/\s+/).filter(Boolean).length
+
+/** The paths a budget key names: one, or several joined with ` + ` for what loads together. */
+export const budgetKeyPaths = (key: string): string[] => key.split(SUM_SEPARATOR)
+
+/**
+ * Whether a kit file, by its path in the kit (`skills/…`, `agents/…`, `rules/kit/…`), is text an agent loads as it
+ * is and so counts against a budget: a skill file, an agent, or a kit rule without a `paths:` glob in its
+ * frontmatter; a rule with one loads only on demand. The one choice `jh check` and the kit's own test share.
+ */
+export const isBudgetedKitDocument = (kitPath: string, text: string): boolean =>
+  KIT_DOCUMENT.test(kitPath) && !(KIT_RULE.test(kitPath) && PATHS_IN_FRONTMATTER.test(text))
+
+/** A file warns above its budget and fails above the budget plus 10 %. */
+export const overrunOf = (words: number, budget: number): Overrun | null => {
+  if (words > budget * FAIL_FACTOR) return CHECK_STATUS.fail
+  return words > budget ? CHECK_STATUS.warn : null
+}
+
+/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
+export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number => {
+  const glob = Object.keys(project).find((key) => isGlob(key) && matchesGlob(path, key))
+  return project[path] ?? (glob === undefined ? undefined : project[glob]) ?? defaults[path] ?? fallback
+}
+
+const sumEntry = (key: string, files: readonly FileWords[]): number | null => {
+  const parts = budgetKeyPaths(key).map((part) => files.find((file) => file.path === part))
+  return parts.every((part) => part !== undefined) ? parts.reduce((total, part) => total + part.words, 0) : null
+}
+
+/** Every file against its budget, then every sum entry of the project and the kit whose files all exist. */
+export const measureFiles = (
+  files: readonly FileWords[],
+  project: BudgetTable,
+  defaults: BudgetTable,
+): Measurement[] => {
+  const single = files.map(({ path, words, fallback }) => ({
+    label: path,
+    words,
+    budget: budgetOf(path, project, defaults, fallback),
+  }))
+  const sums = [...new Set([...Object.keys(project), ...Object.keys(defaults)])]
+    .filter((key) => key.includes(SUM_SEPARATOR))
+    .flatMap((key) => {
+      const words = sumEntry(key, files)
+      return words === null ? [] : [{ label: key, words, budget: budgetOf(key, project, defaults, 0) }]
+    })
+  return [...single, ...sums]
+}
+
+const overrunLine = ({ entry: { label, words, budget }, overrun }: MeasuredOverrun): string =>
+  `${OVERRUN_LABEL[overrun]}: ${label} has ${words} words, budget ${budget}`
+
+const withinLine = (count: number): string =>
+  count === 1 ? '1 file within its word budget' : `${count} files within their word budget`
+
+const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
+  if (overruns.some(({ overrun }) => overrun === CHECK_STATUS.fail)) return CHECK_STATUS.fail
+  return overruns.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
+}
+
+/** One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %. */
+export const budgetResult = (measured: readonly Measurement[], durationMs: number): CheckResult => {
+  const overruns = measured.flatMap((entry) => {
+    const overrun = overrunOf(entry.words, entry.budget)
+    return overrun === null ? [] : [{ entry, overrun }]
+  })
+  return {
+    name: 'Skill budgets',
+    command: `${measured.length} measured, words per budget`,
+    status: statusOf(overruns),
+    detail: overruns.map(overrunLine).join('\n') || withinLine(measured.length),
+    durationMs,
+  }
+}
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/** The kit documents the first valid lock file lists, the lock under its old name counting while sync has not moved it. */
+const kitPathsOf = (root: string): string[] => {
+  for (const candidate of projectLockCandidates(root)) {
+    const text = readText(candidate)
+    const parsed = text === null ? null : parseManifest(parseJson(text))
+    if (parsed?.ok) return Object.keys(parsed.manifest.files).filter((key) => KIT_DOCUMENT.test(key))
+  }
+  return []
+}
+
+const listDirectory = (path: string): string[] => (existsSync(path) ? readdirSync(path) : [])
+
+const fileWordsOf = (root: string, path: string, fallback: number): FileWords[] => {
+  const text = readText(join(root, path))
+  return text === null ? [] : [{ path, words: countWords(text), fallback }]
+}
+
+const kitFileWordsOf = (root: string, kitPath: string): FileWords[] => {
+  const path = claudePath(kitPath)
+  const text = readText(join(root, path))
+  return text === null || !isBudgetedKitDocument(kitPath, text)
+    ? []
+    : [{ path, words: countWords(text), fallback: KIT_FILE_FALLBACK_BUDGET }]
+}
+
+const ownSkillPaths = (root: string, kit: ReadonlySet<string>): string[] =>
+  listDirectory(join(root, CLAUDE_DIRECTORY, SKILLS_DIRECTORY))
+    .map((name) => claudePath(SKILLS_DIRECTORY, name, 'SKILL.md'))
+    .filter((path) => !kit.has(path))
+
+const supplementPaths = (root: string): string[] =>
+  listDirectory(join(root, CLAUDE_DIRECTORY, SUPPLEMENTS_DIRECTORY))
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => claudePath(SUPPLEMENTS_DIRECTORY, name))
+
+/**
+ * The installed kit skills with their references, kit agents and kit rules that load every session (the lock file
+ * says which files the kit installed), the project's supplements and its own skills, measured against the budgets.
+ * Null when there is nothing to measure.
+ */
+export const skillBudgetCheck = (root: string, project: BudgetTable = {}): CheckResult | null => {
+  const started = Date.now()
+  const kitPaths = kitPathsOf(root)
+  const kit = new Set(kitPaths.map((key) => claudePath(key)))
+  const files = [
+    ...kitPaths.flatMap((key) => kitFileWordsOf(root, key)),
+    ...supplementPaths(root).flatMap((path) => fileWordsOf(root, path, SUPPLEMENT_BUDGET)),
+    ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
+  ]
+  return files.length === 0 ? null : budgetResult(measureFiles(files, project, KIT_SKILL_BUDGETS), Date.now() - started)
+}

package/src/cli.ts

@@ -24,6 +24,8 @@ export const COMMANDS: CommandTable = {
   [HERD_COMMAND.name]: () => import('./plans/command'),
   init: () => import('./sync/init-command'),
   [HERD_COMMAND.alias]: () => import('./plans/command'),
+  lane: () => import('./lane/command'),
+  mermaid: () => import('./mermaid/command'),
   preview: () => import('./preview/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),

package/src/config/auto-window.ts

@@ -0,0 +1,8 @@
+import { DAY_MS } from '../plan-format/clock'
+
+/** The longest window `watch.parallelTasks.auto` may span: a forgotten switch ends within a week. */
+export const MAX_AUTO_WINDOW_DAYS = 7
+
+/** The days from `since` to `until`, two `YYYY-MM-DD` dates; read as UTC midnights, so no clock change shifts them. */
+export const windowDays = (since: string, until: string): number =>
+  Math.round((Date.parse(`${until}T00:00:00Z`) - Date.parse(`${since}T00:00:00Z`)) / DAY_MS)

package/src/config/link-kinds.ts

@@ -8,11 +8,17 @@ export type LinkKind = {
   icon: string
 }
 
+export const ARTIFACT_LINK_KIND: LinkKind = {
+  pattern: '^https://claude\\.ai/(code/)?artifact/',
+  label: 'Artifact',
+  icon: '✦',
+}
+
 /** The kinds known without configuration: plain URL patterns, no service is called. */
 export const DEFAULT_LINK_KINDS: readonly LinkKind[] = [
   { pattern: '^https://github\\.com/[^/]+/[^/]+/(pull|issues)/\\d+', label: 'GitHub', icon: '⑂' },
   { pattern: '^https://(www\\.)?figma\\.com/', label: 'Figma', icon: '◈' },
-  { pattern: '^https://claude\\.ai/(code/)?artifact/', label: 'Artifact', icon: '✦' },
+  ARTIFACT_LINK_KIND,
 ]
 
 export const isRegularExpression = (source: string): boolean => {

package/src/config/schema.ts

@@ -5,10 +5,12 @@ import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
 import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
 import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
+import { MAX_AUTO_WINDOW_DAYS, windowDays } from './auto-window'
 import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
 import { isRepositoryDirectory } from './repository-directory'
+import { DEFAULT_TONES, TONE_NAMES } from './tones'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
@@ -127,6 +129,20 @@ const parallelTasksSchema = z.strictObject({
    * the first answer of a lane's session carried.
    */
   maxTokens: z.number().int().positive().default(DEFAULT_PARALLEL_TASKS_MAX_TOKENS),
+  /**
+   * The days, both included, on which a proposal that keeps every limit is marked `auto` and the coordinator starts it
+   * without asking: subagents beside running work in a lane, at most two extra agents, no path that always asks.
+   * `since` is the day it was switched on, `until` at most seven days later; outside the window it is off. Unset by
+   * default, so every proposal asks.
+   */
+  auto: z
+    .strictObject({ since: z.iso.date(), until: z.iso.date() })
+    .refine(({ since, until }) => until >= since, 'until must not be before since')
+    .refine(
+      ({ since, until }) => windowDays(since, until) <= MAX_AUTO_WINDOW_DAYS,
+      `until must be at most ${MAX_AUTO_WINDOW_DAYS} days after since`,
+    )
+    .optional(),
 })
 
 const checksSchema = z.strictObject({
@@ -161,7 +177,7 @@ const sourcePath = z.string().refine(isSourcePath, 'not a source path: `.`, or `
 
 const SOURCE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 
-/** The seven known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
+/** The eight known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
 const sourceMapSchema = z
   .object({
     [SOURCE_FIELD.id]: sourcePath,
@@ -178,6 +194,8 @@ const sourceMapSchema = z
     [SOURCE_FIELD.author]: sourcePath.optional(),
     /** A ticket source's status, shown on its badge in the herd; also a field `reportOn` can name. */
     [SOURCE_FIELD.status]: sourcePath.optional(),
+    /** How often the entry happened (an error count), shown as `113×` beside the entry in the herd's `Sources` block. */
+    [SOURCE_FIELD.count]: sourcePath.optional(),
   })
   .catchall(sourcePath)
   .refine((map) => Object.keys(map).every((field) => SOURCE_FIELD_NAME.test(field)), {
@@ -188,6 +206,8 @@ const sourceMapSchema = z
 const canChange = ({ map, reportOn }: { map: Record<string, string | undefined>; reportOn?: string[] }): boolean =>
   map.updatedAt !== undefined || CONTENT_FIELDS.some((field) => map[field] !== undefined) || reportOn !== undefined
 
+const toneName = z.enum(TONE_NAMES)
+
 const sourceSchema = z
   .strictObject({
     /** Printed in every report of the source and the key of its saved state. */
@@ -203,6 +223,13 @@ const sourceSchema = z
     ignoreAuthors: z.array(z.string().min(1)).default([]),
     /** The most new or changed entries one report shows of this source; the rest is one line `+<n> more`. */
     reportLimit: z.number().int().min(1).default(5),
+    /** Shown before a row of "Waiting for you" that came from this source (`Error log · Checkout: …`); without it the source's name. */
+    label: z
+      .string()
+      .min(1)
+      .max(40)
+      .regex(/^[^\r\n]+$/, 'one line')
+      .optional(),
     /** The lane the source's reports name. */
     lane: z.string().min(1).optional(),
     /**
@@ -210,6 +237,8 @@ const sourceSchema = z
      * the lane above or the lane whose board row or plan names its id.
      */
     ticket: z.boolean().optional(),
+    /** The tone of the source's mark in the herd's `Sources` block while its newest report is new; without it the tone of the role `new`. */
+    tone: toneName.optional(),
     /**
      * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
      * `author`, `body` and `url`; without it a change of that content reports.
@@ -269,7 +298,7 @@ const checkFreePattern = z
   )
 
 /**
- * A path pattern that always asks before a merge under a plan approval: plain path words with wildcards, relative, no
+ * A path pattern that always asks (`guard.alwaysAsk`): plain path words with wildcards, relative, no
  * empty, `.` or `..` segment (GitHub lists no file with one, so such a pattern would never ask). Broad on purpose (`.github/**`, `**`), since a pattern here only ever adds a question; braces,
  * classes and negation stay out, so the hook, which has no schema library, reads exactly what this accepts.
  */
@@ -304,13 +333,13 @@ const mergeSchema = z.strictObject({
   withoutChecks: z.array(checkFreePattern).default([]),
 })
 
-const guardSchema = z.strictObject({
+const guardFields = z.strictObject({
   /**
-   * The commands the merge guard hook asks the user about before they run, also behind options before the verb, a chain,
-   * a wrapper or `sh -c`. `gh api` asks only for a write to a merge, a file, a dispatch, a rerun or a ref. An empty list switches the
-   * guard off.
+   * The commands the merge guard hook asks the user about before they run, where they stand at a program position, also
+   * behind options before the verb, a chain, a wrapper or `sh -c`. `gh api`, when listed, asks only for a write to a
+   * merge, a file, a dispatch, a rerun or a ref. An empty list switches the guard off.
    */
-  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run', 'gh run rerun', 'gh api']),
+  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run']),
   selfMerge: z
     .strictObject({
       /** Whether `/orchestrate` offers "merge it yourself after green checks" in the pull request question; off also stops the hook honouring such an answer. */
@@ -325,30 +354,54 @@ const guardSchema = z.strictObject({
       waitMinutes: z.number().int().min(1).max(9).default(8),
     })
     .prefault({}),
+  /**
+   * Paths that always ask, on top of the ones jackherd brings (`.github/**`, `**\/migrations/**`, `**\/.env*`,
+   * `.claude/**`, `.jackherd/**`, `bunfig.toml`, `**\/CLAUDE.md`, `**\/AGENTS.md`, `.agents/**`, `.mcp.json`,
+   * `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**\/.npmrc`, `**\/CODEOWNERS`): a
+   * `merge.withoutChecks` pattern never opens them, and the watcher never starts parallel work on them by itself. They
+   * add to that list, never replace it. A standing approval covers them; only workflows, migrations and env files ask.
+   */
+  alwaysAsk: z.array(alwaysAskPattern).default([]),
+  /**
+   * Checks that must be among the head commit's and green before a standing approval lets a merge pass, by their names
+   * on GitHub. Unset, the merge needs at least one check and every one green; set, also each of these. Either way
+   * GitHub must be able to merge it.
+   */
+  requiredChecks: z.array(checkName).optional(),
+  /** Read until 2.0.0 as `alwaysAsk` (`exceptPaths`) and `requiredChecks`; the plan approval it was for is gone. */
   planApproval: z
-    .strictObject({
-      /**
-       * Paths that always ask, on top of the ones jackherd brings (`.github/**`, `**\/migrations/**`, `**\/.env*`,
-       * `.claude/**`, `.jackherd/**`, `bunfig.toml`, `**\/CLAUDE.md`, `**\/AGENTS.md`, `.agents/**`, `.mcp.json`,
-       * `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**\/.npmrc`, `**\/CODEOWNERS`, every
-       * package.json, and the CHANGELOG.md of every package without `"private": true`):
-       * a pull request that changes one is never merged on a plan approval alone. They add to that list, never replace
-       * it; an invalid entry turns plan approval off, so every merge asks.
-       */
-      exceptPaths: z.array(alwaysAskPattern).default([]),
-      /**
-       * Checks that must be among the head commit's and green before a plan approval lets a merge pass, by their names
-       * on GitHub. Unset, the merge needs at least one check and every one green; set, also each of these. Either way
-       * GitHub must be able to merge it and the head must contain the base branch.
-       */
-      requiredChecks: z.array(checkName).optional(),
-    })
-    .prefault({}),
+    .strictObject({ exceptPaths: z.array(alwaysAskPattern).optional(), requiredChecks: z.array(checkName).optional() })
+    .optional()
+    .meta({ deprecated: true }),
 })
 
+/** A config from before 1.10.0 kept the paths that always ask and the required checks under `planApproval`. */
+const guardWithoutPlanApproval = ({ planApproval, ...guard }: z.output<typeof guardFields>) => {
+  const requiredChecks = guard.requiredChecks ?? planApproval?.requiredChecks
+  return {
+    ...guard,
+    alwaysAsk: [...guard.alwaysAsk, ...(planApproval?.exceptPaths ?? [])],
+    ...(requiredChecks === undefined ? {} : { requiredChecks }),
+  }
+}
+
+const guardSchema = guardFields.transform(guardWithoutPlanApproval)
+
 const hintsSchema = z.strictObject({
   /** Whether the `ask-hint` hook points out a last message that ends in a question while the turn used no `AskUserQuestion`; a lane session is never hinted. */
   askUserQuestion: z.boolean().default(true),
+  /** Whether the `task-hint` hook points a lane that edits a file without an open task signal to `jh task start`, once per task. */
+  taskSignal: z.boolean().default(true),
+})
+
+/** Minutes a lane works without a task signal before the watcher reports `no task signal`. */
+const DEFAULT_TASK_SIGNAL_MINUTES = 10
+
+const tonesSchema = z.strictObject({
+  waiting: toneName.default(DEFAULT_TONES.waiting),
+  new: toneName.default(DEFAULT_TONES.new),
+  running: toneName.default(DEFAULT_TONES.running),
+  resting: toneName.default(DEFAULT_TONES.resting),
 })
 
 const contextSchema = z
@@ -443,12 +496,15 @@ export const jackherdConfigSchema = z.strictObject({
         )
         .default(DEFAULT_LINK_KINDS.map((kind) => ({ ...kind }))),
       context: contextSchema.prefault({}),
+      /** The colour of each role in the herd, by name: what waits for you, what is new, what runs, what rests. */
+      tones: tonesSchema.prefault({}),
     })
     .prefault({}),
   /**
    * Read by `jh watch`; without `deploy` it reports no deploy runs. `feedback` is on unless set to `false`:
    * it reports new feedback on the lanes' pull requests except from the account the watcher runs as and `ignore`.
    * `parallelTasks.maxTokens` caps the cost of the extra agents in a proposal of parallel tasks at the heartbeat.
+   * `taskSignalMinutes` is how long a lane works without a task signal before it reports `no task signal`, once per phase.
    * `checks` reads the failed tests of a red lane pull request (`failedTestPattern`), also with `feedback` off.
    * Without `previews` it reads no deploy preview; with it, one `preview` per new head commit. Each of `sources` is a
    * command whose JSON output reports `source` for a new or changed entry.
@@ -459,6 +515,7 @@ export const jackherdConfigSchema = z.strictObject({
       feedback: z.union([z.literal(false), feedbackSchema]).prefault({}),
       checks: checksSchema.prefault({}),
       parallelTasks: parallelTasksSchema.prefault({}),
+      taskSignalMinutes: z.number().int().positive().default(DEFAULT_TASK_SIGNAL_MINUTES),
       previews: previewsSchema.optional(),
       sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
     })

package/src/config/tones.ts

@@ -0,0 +1,27 @@
+/** The colours the herd paints with by name; the terminal's own palette decides how each looks, `grey` is the dimmed text colour. */
+export const TONE = {
+  amber: 'amber',
+  teal: 'teal',
+  grey: 'grey',
+  red: 'red',
+  green: 'green',
+  blue: 'blue',
+  magenta: 'magenta',
+} as const
+
+export type ToneName = (typeof TONE)[keyof typeof TONE]
+
+export const TONE_NAMES = Object.values(TONE)
+
+/** What a tone is for in the herd: what waits for you, what is new, what runs, what rests. */
+export const TONE_ROLE = { waiting: 'waiting', new: 'new', running: 'running', resting: 'resting' } as const
+
+export type ToneRole = (typeof TONE_ROLE)[keyof typeof TONE_ROLE]
+
+/** The tone of each role, as the herd looked before the tones were configurable. */
+export const DEFAULT_TONES: Record<ToneRole, ToneName> = {
+  [TONE_ROLE.waiting]: TONE.amber,
+  [TONE_ROLE.new]: TONE.amber,
+  [TONE_ROLE.running]: TONE.teal,
+  [TONE_ROLE.resting]: TONE.grey,
+}

package/src/lane/close-board.ts

@@ -0,0 +1,106 @@
+import { twoDigits } from '../plan-format/clock'
+import { laneNameOf, parseSprintLanes } from '../plan-format/lanes'
+import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { PLAN_LANGUAGE, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { BOARD_LANE, type BoardLane } from './close-check'
+
+const CONTINUATION = '↳'
+const FIRST_CELL = /^\|((?:[^|\\]|\\.)*)\|/
+
+const HISTORY_HEADER: Record<PlanLanguage, readonly [string, string]> = {
+  [PLAN_LANGUAGE.de]: ['Datum', 'Ereignis'],
+  [PLAN_LANGUAGE.en]: ['Date', 'Event'],
+}
+
+const isoDate = (time: Date): string =>
+  `${time.getFullYear()}-${twoDigits(time.getMonth() + 1)}-${twoDigits(time.getDate())}`
+
+/** The word for a cleaned-up lane and the day, as a name cell carries it: `abgeräumt DD.MM.`, `cleaned up YYYY-MM-DD`. */
+export const closedMark = (time: Date, language: PlanLanguage): string => {
+  const day =
+    language === PLAN_LANGUAGE.de ? `${twoDigits(time.getDate())}.${twoDigits(time.getMonth() + 1)}.` : isoDate(time)
+  return `${PLAN_VOCABULARY[language].laneClosed} ${day}`
+}
+
+/** The date cell of a history row, `YYYY-MM-DD` in every plan language. */
+export const historyDate = (time: Date): string => isoDate(time)
+
+/** How the lanes table names `lane`, read as the herd reads it. */
+export const boardLaneOf = (board: string, lane: string, language: PlanLanguage): BoardLane => {
+  const found = parseSprintLanes(board, language).find(({ name }) => name === lane)
+  if (found === undefined) return BOARD_LANE.missing
+  return found.closed ? BOARD_LANE.closed : BOARD_LANE.open
+}
+
+/**
+ * The line indexes of the lane's current rows: the rows since it was last cleaned up, as `parseSprintLanes` keeps them,
+ * a row that names the lane again without the mark starting it anew. Empty when the lane is closed or missing.
+ */
+const currentRowIndexes = (board: string, lane: string, language: PlanLanguage): number[] => {
+  const { sections, laneClosed } = PLAN_VOCABULARY[language]
+  const start = sectionStart(board, sections.lanes)
+  if (start === -1) return []
+  let previous: string | null = null
+  let closed = false
+  let indexes: number[] = []
+  for (const { index, cells } of firstTableRows(sectionLines(board, sections.lanes))) {
+    const first = cells[0] ?? ''
+    const name = laneNameOf(first, previous)
+    previous = name ?? previous
+    if (name !== lane) continue
+    const marked = first.includes(laneClosed)
+    if (closed && !marked && !first.startsWith(CONTINUATION)) {
+      closed = false
+      indexes = []
+    }
+    closed ||= marked
+    indexes.push(start + index)
+  }
+  return closed ? [] : indexes
+}
+
+const withMarkedNameCell = (line: string, mark: string): string =>
+  line.replace(FIRST_CELL, (_cell, name: string) => `| ${name.trim()}, ${mark} |`)
+
+/** The board with `, <mark>` appended to the name cell of each current row of the lane; unchanged without one. */
+export const withLaneClosed = (board: string, lane: string, mark: string, language: PlanLanguage): string => {
+  const marked = new Set(currentRowIndexes(board, lane, language))
+  return board
+    .split('\n')
+    .map((line, index) => (marked.has(index) ? withMarkedNameCell(line, mark) : line))
+    .join('\n')
+}
+
+/** Text that stays inside one table cell: on one line, with its pipes escaped. */
+const cell = (text: string): string => terminalSafe(text.replace(/\s+/g, ' ')).trim().replaceAll('|', '\\|')
+
+const historyTableHead = (language: PlanLanguage): string[] => {
+  const header = HISTORY_HEADER[language]
+  return [`| ${header.join(' | ')} |`, `|${header.map((name) => '-'.repeat(name.length + 2)).join('|')}|`]
+}
+
+const withoutTrailingBlanks = (lines: readonly string[]): string[] => {
+  let end = lines.length
+  while (end > 0 && lines[end - 1].trim() === '') end -= 1
+  return lines.slice(0, end)
+}
+
+/**
+ * The board with a row on top of its history table, newest first as the coordinator writes them. A history section
+ * without a table gets one right under its heading; a board without the section gets it at its end.
+ */
+export const withHistoryRow = (board: string, date: string, text: string, language: PlanLanguage): string => {
+  const heading = PLAN_VOCABULARY[language].sections.history
+  const row = `| ${date} | ${cell(text)} |`
+  const lines = board.split('\n')
+  const start = sectionStart(board, heading)
+  if (start === -1)
+    return [...withoutTrailingBlanks(lines), '', `## ${heading}`, '', ...historyTableHead(language), row, ''].join('\n')
+  const tableAt = sectionLines(board, heading).findIndex((line) => line.startsWith('|'))
+  const firstRow = start + tableAt + 2
+  if (tableAt !== -1) return [...lines.slice(0, firstRow), row, ...lines.slice(firstRow)].join('\n')
+  const at = lines[start]?.trim() === '' ? start + 1 : start
+  const table = [...historyTableHead(language), row, ...(lines[start]?.trim() === '' ? [''] : [])]
+  return [...lines.slice(0, at), ...table, ...lines.slice(at)].join('\n')
+}