@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/lib/README.md

@@ -18,15 +18,14 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | Module | Responsibility |
 |---|---|
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
-| [`claims/`](./claims/) | Claim overlap, shared by the two things that ask "do these paths collide?" so approval and claiming cannot disagree: [`claims/overlap.ts`](./claims/overlap.ts) holds `normalizeClaimPath` (repository-relative, posix, no trailing slash — a Windows spelling reads as the same path), `claimsConflict` (a claim covers everything below it, in either direction) and `findClaimOverlap` (the first colliding pair). Used by `session-bus` when a session claims, and by plan approval when a split names its units. |
 | [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` / `writeConfigValuesAt` / `unsetConfigValueAt` (the leaf writers preserve siblings and metadata, `writeConfigValuesAt` applies several leaves in one document pass, and the last removes one and prunes what it emptied). Includes `clampInteger` / `clampNumber` / `cleanString` / `optionalString` / `asBoolean` / `stringList` / `asRecord` / `asNumber` (the untrusted-JSON narrowing pair) / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
 | [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters, plus `decodeCodePoint`, the other half of the same boundary — one numeric character reference as text, with a surrogate or out-of-range value decoded to U+FFFD. |
 | [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` / `JobFinishedEvent` (published by `job`, consumed by bytefly's notify capability), `SUBAGENT_FINISHED_CHANNEL` / `SubagentFinishedEvent` (published by `subagent`, consumed by bytefly's footer roll-up), and `WEB_SEARCH_PROVIDER_CHANNEL` / `WebSearchProviderEvent` (published by `web-access` at session start, consumed by bytefly's doctor so it can report the resolved provider without importing the extension — the key itself is never in the payload). |
 | [`notice.ts`](./notice.ts) | The shared transcript notice: `NOTICE_TYPE`, the `NoticeDetails` / `NoticeItem` shape, `noticeMessage` (the `display: true` message both send paths accept), `isNotice`, and `pruneStaleNotices` — posted by `job`, `watch`, and `session-bus`, rendered by bytefly — plus `burstText`, the one assembly of the model-facing text for a burst of pending outcomes (marker, counted headline, rows, an optional `… N more`, an optional hint). |
 | [`report.ts`](./report.ts) | The pending-report channel: `createPendingReporter` with `wake` / `pending` / `markReported` / `buildNotice` / `wakeRequested` / `source` / `onWoke`, returning the handlers that report at the next turn, raise at most one triggered turn per wake window, retry a wake the running turn suppressed once `agent_settled` reports an unaborted settle, and prune only their own notices; and `registerPendingChannel`, which binds those handlers to `session_start` / `session_tree` / `agent_start` / `agent_settled` / `before_agent_start` / `context` / `session_shutdown` around a `load` / `setStatus?` / `shutdown` runtime, so the order a session starts and shuts down is written once. A `load` that resolves a repository may return a promise, which is awaited before the trigger is armed; a runtime that publishes no chip omits `setStatus`. `job`, `watch`, and `session-bus` supply only their own arming in `onSessionStart` / `onSessionShutdown` and their own `wakeRequested`. |
-| [`errors.ts`](./errors.ts) | `messageOf`: the one boundary that turns an unknown thrown value into a user-facing line (an `Error` yields its message, anything else is stringified). |
-| [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `boundedTail` (the end of a joined tail with a `truncated` flag), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — `lineOf` (a value read as one sanitized line), `sanitizeUntrustedLine` / `sanitizeUntrustedText` with `MAX_OUTPUT_LINE` for **program output** (OSC/CSI escapes removed whole, `\r` progress resolved, clipped), and `shortenPath`. |
+| [`errors.ts`](./errors.ts) | `messageOf`: the one boundary that turns an unknown thrown value into a user-facing line (an `Error` yields its message, anything else is stringified), and `hasErrorCode` for the branch a caller takes on one errno code (`EEXIST` means another writer won). |
+| [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `formatSize` (`68 B`, `12.4 kB`, `1.5 MB`), `boundedTail` (the end of a joined tail with a `truncated` flag), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — `lineOf` (a value read as one sanitized line), `sanitizeUntrustedLine` / `sanitizeUntrustedText` with `MAX_OUTPUT_LINE` for **program output** (OSC/CSI escapes removed whole, `\r` progress resolved, clipped), and `shortenPath`. |
 | [`timer.ts`](./timer.ts) | The three timer seams and their production defaults, each cancellable and each built so a pending timer never holds the process open: `ArmTimer` / `defaultTimer` (one shot), `RepeatTimer` / `defaultInterval` (repeating), and `abortableSleep` (resolve after a delay, reject `Error("aborted")` when a signal wins). Shared by `wechat`'s bridge and prompt channel, plan's review page, `job`'s and `watch`'s repaint clocks, `bytefly`'s working tick, the browse live channel, and the search throttle — so a test drives a deadline instead of waiting on one. |
 | [`lines.ts`](./lines.ts) | `LineSplitter`, the byte-safe splitter for a stream of program output: buffers bytes and decodes only at a newline, so a UTF-8 character split across two reads survives, and caps an over-long line instead of dropping it. Shared by `job`, `watch`, `check`, and `subagent`. |
 | [`pool.ts`](./pool.ts) | `mapConcurrent`: one async read per entry with at most `limit` calls in flight and results in input order, so a directory listing or a status sweep fans out without an unbounded burst or a per-entry round trip. Shared by `file-browse` and `worktree`. |
@@ -34,18 +33,21 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote transport marks on the UI context it owns (`INTERACTION_TURN_KEY`), the `InteractionChannel` interface (`request` / `post` / `postFile`, plus an optional `setPromptTimeout` scope for a dialog the human must read something before answering), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, digest preface, and prompt `timeoutMs`) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `gitCommonDir`, `revParse`, `revParseMany` for several revisions in one call, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
-| [`http/`](./http/) | The loopback HTTP layer shared by `file-browse` and `plan`: [`http/headers.ts`](./http/headers.ts) (the page policy `PAGE_CSP` and the `pageHeaders` / `scriptHeaders` / `jsonHeaders` sets, plus `eventHeaders` for the one long-lived stream), [`http/response.ts`](./http/response.ts) (`ServeResponse` — a buffered body, a `filePath` stream, or an SSE `stream` — plus `htmlResponse` / `jsonResponse` / `jsonError` / `textResponse`), [`http/router.ts`](./http/router.ts) (`parseRequestUrl`, and `isLocalHostHeader` with the `required` mode each server chooses), [`http/server.ts`](./http/server.ts) (`bindLoopback` on `127.0.0.1` with the accept-error listener, `respond` for HEAD / streamed file / body, `openEventStream` for the head and reconnect hint of an SSE response, and the idempotent `createCloser`), and the [`http/index.ts`](./http/index.ts) barrel. |
+| [`http/`](./http/) | The loopback HTTP layer shared by `file-browse`, `plan`, and `board`: [`http/serve.ts`](./http/serve.ts) (the one server entry, `serveLoopback` — bind with a port retry, the capped request body, `HEAD` of a stream, the SSE head, idle grace, and the idempotent close — so an extension supplies a handler and no extension builds a `node:http` server), [`http/sink.ts`](./http/sink.ts) (`EventSink`, the one thing a route writes, which owns liveness — a write after the end is a no-op — plus the open-stream registry and the idle grace armed when the last one goes), [`http/headers.ts`](./http/headers.ts) (the page policy `PAGE_CSP` and the `pageHeaders` / `scriptHeaders` / `jsonHeaders` sets, plus `eventHeaders` for the one long-lived stream), [`http/response.ts`](./http/response.ts) (`ServeResponse` — a buffered body, a `filePath` stream, or an SSE `stream` — plus `htmlResponse` / `jsonResponse` / `jsonError` / `textResponse`), [`http/router.ts`](./http/router.ts) (`parseRequestUrl`, and `isLocalHostHeader` with the `required` mode each server chooses), [`http/guard.ts`](./http/guard.ts) (the request guards a served page shares: `postOnly`, `checkOrigin`, `requireJsonBody`, and `envelopeRefusal` — the method allowlist, then the fail-closed `Host` rule, then the origin check on every state-changing method), [`http/token.ts`](./http/token.ts) (`mintToken`, 128 random bits as hex, and `tokenMatches`, the constant-time comparison a route trusts), [`http/server.ts`](./http/server.ts) (the socket primitives `serveLoopback` is built from — `bindHost` with the accept-error listener, `respond` for HEAD / streamed file / body, `openEventStream`, and the idempotent `createCloser` — layer-internal, so the barrel does not export them), and the [`http/index.ts`](./http/index.ts) barrel. |
 | [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface, whose conventions are its own doc, [`tui/README.md`](./tui/README.md). Modules: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (the docked-list frame `dockListFrame`, the `screenFooter` that closes a screen's own rows, `screenHint`, `detailBlockRows` (the rows its detail block costs), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow` with its `align` option for a value held beside its label, `statusRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`, `byRunningFirst` for a live list's order), [`tui/columns.ts`](./tui/columns.ts) (`splitRow` for two cells at the two edges, `inlineRow` for two cells held together, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`, `labelLine` / `clipLabel` with `LABEL_WIDTH`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job`, `watch`, and `subagent` share, with the attached-context `notify` and a `detach` that clears its keys), [`tui/dock-screen.ts`](./tui/dock-screen.ts) (`DockListScreen`, the two-mode docked list + detail-pane screen with navigation, wheel, range, and confirm), [`tui/confirm.ts`](./tui/confirm.ts) (`ConfirmState`, the y/N layer behind every destructive screen action), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, `callLine` — the one headline every renderer draws — `detailsOrLine` (a result's details, or the one `errorLine` / `rejectionLine` a failure shows), sanitized `errorLine` / `rejectionLine`, `moreHint` / `overflowHint` / `earlierHint`, the `TailResult` transcript block, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, doc, and plan guards share, and the canonical-path helper the worktree registry keys records by. |
 | [`pdf.ts`](./pdf.ts) | The optional `unpdf` seam shared by `web-access` and `file-read`: `pdfGuidance`, `PdfUnavailableError`, `pdfTextFromResult`, and the lazy `loadPdfExtractor` / `extractPdfText` (an injected extractor wins), so a missing package and a merged-pages result read the same way through either surface. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
-| [`plans/`](./plans/) | The plan document's shared shape, for plan mode and for whatever reads a plan without importing it: [`plans/sections.ts`](./plans/sections.ts) is the one fence-aware scan (`extractSections`, `replaceSection`, `teamSectionBody`, and the `HEADING` / `FENCE` / `normalizeHeadingText` vocabulary), [`plans/team.ts`](./plans/team.ts) parses and renders the `## Team` section (`PlanUnit`, `PlanTeam`, `renderTeam`, `parseTeam`, `readTeam`, `writeTeam`), [`plans/split.ts`](./plans/split.ts) decides whether a proposed split is one (`checkSplit`, its refusals by name, `SHARED_FILES`, `MAX_OWNERS`, `mergeOrder`), and [`plans/store.ts`](./plans/store.ts) holds the one directory rule (`plansDir`) the store writes to and the bus reads from. The switch lives apart in [`plans/setting.ts`](./plans/setting.ts): `SPLIT_SECTION` / `SPLIT_KEY` / `SPLIT_DEFAULT`, the `SPLIT_SETTING_ID` / `SPLIT_SETTING_LABEL` the settings row shows, `splitEnabled(cwd)` and `SPLIT_OFF_NOTE`, so the panel row, approval, and the bus read one key. |
-| [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
+| [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny, and `WORKSPACE_READERS` — the built-in readers plus `read_doc` that plan, rewind, and subagent compose their allowlists from. |
 | [`plan-state.ts`](./plan-state.ts) | The plan-mode flag replayed from the session branch: `PLAN_MODE_ENTRY_TYPE` and `isPlanModeEnabled(entries)`, so `rewind` can refuse a write while planning without importing the plan extension. |
 | [`plan-entry.ts`](./plan-entry.ts) | Plan-mode entry shared by the extension that owns the mode and the one that offers it: `READ_ONLY_SUMMARY` and `PLAN_CONSENT` (one wording for the read-only guarantee), the `PLAN_ENTER_REQUEST` channel with its `PlanEnterRequest` payload, and `requestPlanMode(pi, ctx)` — a request/response over `pi.events` that resolves `false` instead of hanging when `plan` is not loaded, so a command context (which has no `executeTool`) can still enter the mode after asking the user once. |
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
 | [`repo-key.ts`](./repo-key.ts) | The per-repository storage key that outlives one checkout: `repoKeyOf(value)` hashes an identity to `REPO_KEY_LENGTH` hex characters, and `repoKeyFor(pi, cwd)` returns `{ root, key, fromGit }` from the repository's *common* git directory, so every worktree of one repository files state under the same key, while a directory outside git keys on itself. Shared by `session-bus` (sessions, mail, claims) and `plan` (plans). |
 | [`screen-session.ts`](./screen-session.ts) | `withPolledScreen`: mount one `ctx.ui.custom` dock screen — rails suppressed for its lifetime, an optional repaint tick through an injected `RepeatTimer`, and one teardown — handing the mount the host's `tui`, `theme`, `requestRender`, `close`, and `viewportRows`. Shared by `/jobs`, `/watch`, and `/memory`, whose rails window and timer window were the same one. |
+| [`board/`](./board/) | The shared feature board. [`board/card.ts`](./board/card.ts) is the record: `CARD_VERSION`, `Card` / `CardStatus` / `CardOwner` / `CardNote`, the field caps `MAX_TITLE` / `MAX_PATHS` / `MAX_PLAN` / `MAX_NOTE` / `MAX_NOTES`, the `normalize*` boundary the model's arguments pass (`normalizeTitle`, `normalizePathHints` — repo-relative hints, never claims —, `normalizeNote`, `normalizePlanPath`, `normalizeCardId`, `normalizePriority`), the priority (`PRIORITIES`, `priorityOf`, `priorityRank`) and the links (`dependsOf`), `matchesQuery` — the rule `list`'s `query` applies, which the page's filter box answers in its own script — `cardRef`, `signatureOf`, and `isCard`, the one gate a file read passes. [`board/rules.ts`](./board/rules.ts) is the lifecycle: `Actor`, `CardOp` (including `edit`, whose fields are each optional because an omitted one must be left alone), `createCard`, the pure `applyOp` over the card *and* the board index (every transition, its owner rule, the dependency gates a claim, a move, and a drop pass, and the sentence a refusal carries, with a no-op reported as `changed: false`), and `holds`. [`board/links.ts`](./board/links.ts) is the dependency graph that index answers: `BoardIndex` / `indexOf`, `blockersOf` (what is unfinished), `dependentsOf` / `dependedOn` (what a drop would strand), `wouldCycle`, and `normalizeDepends` — one edge stored once, as an id in the waiting card's file. [`board/session.ts`](./board/session.ts) is the session a call works as (`BoardSession`, `openBoardSession` — one store per working directory, and the id/label pair a card records, shared by `board` and `team`). [`board/store.ts`](./board/store.ts) is the backend: `BoardStore` over `<agentDir>/board/<repo-key>/cards/*.json`, with `createStore(dir)` and the one construction point `openBoard(pi, cwd)` — `create` allocates the id by hard-linking a temp file onto the name (so two adds cannot share one), `mutate` re-reads the board and re-checks an operation whose card changed underneath instead of overwriting it, `list` orders a lane by priority before age, and nothing prunes. [`board/round.ts`](./board/round.ts) is the lead's rollup (`buildRound`, `IDLE_MS` — owners, unassigned, unplanned, blocked, idle, done, read from the cards alone so it works with the bus disabled), and [`board/round-text.ts`](./board/round-text.ts) is that rollup as the sentences a reader gets (`formatRound`, `plural`), so the tool's result and `team`'s `/team` cannot describe one board two ways. [`board/view.ts`](./board/view.ts) is the page's snapshot (`buildView` → lanes, counts, rollup, bytes, signature, where, and the session reading it), the one shape a client is allowed to know. [`board/page-pointer.ts`](./board/page-pointer.ts) is how a second session finds a page already serving (`PAGE_FILE`, `PagePointer`, `readPointer`, the exclusive `createPointer`, `clearPointer` for its own note only, `probePage` — the file is believed only while it answers, and it carries a view token, never the write one — and `settlePointer`, the ladder a starting page runs: write, attach to a winner that answers, take over a note proved dead, and name the file rather than blame a session when it cannot be read). |
+| [`session-roster.ts`](./session-roster.ts) | Who is on this repository's bus, read as data: `readRoster(dir)` returns `RosterSession` (`id`, `label`, `mode`, `lastSeen`, `mail`, and `watching` when the record says) or `undefined` when the bus has never been used here, `rosterStateOf` applies the liveness rule, and `BUS_DIR_NAME` / `SESSIONS_DIR_NAME` / `INBOX_DIR_NAME` / `SESSION_TTL_MS` are the one copy of the layout, imported by `session-bus` and read by `board`'s page so the Team tab can list teammates without the board depending on the bus extension. |
+| [`session-tool.ts`](./session-tool.ts) | The `session` tool as the other extensions call it: `join(ctx, {label?, wake?, listen?})`, `peers(ctx)`, and `send(ctx, {kind, to, text})`, each a typed result that never throws (`{ ok, error }` or `undefined` for a read the bus cannot answer), plus `MAX_MESSAGE_TEXT`, the send cap `session-bus` re-exports as `MAX_TEXT`. One copy, because the alternative is two extensions knowing the tool's details shape. |
+| [`session-label.ts`](./session-label.ts) | The label rules a session is addressed by and a card records: `MAX_LABEL`, `normalizeLabel` (one line, capped, with a fallback), `shortId`, and `defaultLabel` (the Pi session name, else the working directory's basename, else the id). Shared by `session-bus` (which settles the unique one) and `board` (which records it on a claimed card), so a card's owner names a target the bus answers to. |
 | [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports, the published search provider, env, and a refresh-only reachability probe): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. A check kind is either a prerequisite (`binary`, `module`, `state`, `invocation`, `notify`, `provider`) or a `safety` switch whose off value trades a protection away, read from `bytefly.json` global-then-project. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
 | [`spawn.ts`](./spawn.ts) | The process seam for extensions that run a shell command: `SpawnedProcess`, `SpawnFn`, `KillTreeFn`, the pure `spawnOptions` / `killPlan`, `applyKillPlan` over injected seams, `isPidAlive`, and the `defaultSpawn` / `defaultKillTree` that execute them (process group on POSIX, `taskkill /T` on Windows). Shared by `job`, `watch`, `check`, `worktree`, and `wechat`. |

package/lib/board/card.ts

@@ -0,0 +1,290 @@
+/**
+ * The card record: the shape one card file holds, the caps a write is held to,
+ * and the parser that decides whether a file on disk is still a card.
+ *
+ * A card is the feature-level unit of the shared board: one outcome, one owner,
+ * and the history that explains it. Steps are deliberately *not* cards — they
+ * live in the owner's plan and todo — so a card carries a title and hints rather
+ * than a checklist.
+ *
+ * The record is untrusted when it comes back off disk: a file may be half-written
+ * by a process that died, hand-edited, or left by an older version. {@link isCard}
+ * is the one gate every read passes, so the router, the tool, and the page see
+ * the same record or none. Value-only: no I/O, no state.
+ */
+
+import { sanitizeLine } from "../format.ts";
+
+/** The schema version this build writes. A file with another value is refused, never migrated in place. */
+export const CARD_VERSION = 1;
+
+/** Longest title, in characters. One line, so it cannot wrap a lane row. */
+export const MAX_TITLE = 120;
+
+/** Most path hints one card may carry. */
+export const MAX_PATHS = 12;
+
+/** Longest path hint, in characters. */
+export const MAX_PATH = 200;
+
+/** Longest recorded plan path, in characters. */
+export const MAX_PLAN = 300;
+
+/** Longest single note, in characters. */
+export const MAX_NOTE = 1000;
+
+/** How many notes one card keeps; the oldest drops past this, counted in `notesDropped`. */
+export const MAX_NOTES = 8;
+
+/** How many other cards one card may wait on. */
+export const MAX_DEPENDS = 6;
+
+/** The priorities a card may carry, most urgent first — the order a lane sorts by. */
+export const PRIORITIES = ["high", "normal", "low"] as const;
+
+/** One priority a card can carry. */
+export type Priority = (typeof PRIORITIES)[number];
+
+/** What an absent priority means: a card is ordinary until somebody says otherwise. */
+export const DEFAULT_PRIORITY: Priority = "normal";
+
+/** The lanes, in the order the page and the rollup read them. */
+export const CARD_STATUSES = ["todo", "doing", "blocked", "done"] as const;
+
+/** One lane a card can sit in. */
+export type CardStatus = (typeof CARD_STATUSES)[number];
+
+/** Who holds a card: the session id when it is known, and always the label it is addressed by. */
+export interface CardOwner {
+	/** Session id, when the claim came from a live session. */
+	id?: string;
+	/** The bus label, which is what a peer is addressed by. */
+	label: string;
+}
+
+/** One note: who wrote it, when, and what it says. */
+export interface CardNote {
+	by: string;
+	at: number;
+	text: string;
+}
+
+/** One feature on the board. */
+export interface Card {
+	/** Schema version; an unknown value is refused rather than guessed at. */
+	v: 1;
+	/** `"4"`, shown as `#4`. Allocated by the store, never by a caller. */
+	id: string;
+	/** One line, ≤ {@link MAX_TITLE} — the feature's outcome. */
+	title: string;
+	status: CardStatus;
+	owner?: CardOwner;
+	/** Repository-relative hints, never claims. */
+	paths: string[];
+	/** The plan file being executed, once one is recorded. */
+	plan?: string;
+	/** How urgent the feature is; absent reads as {@link DEFAULT_PRIORITY}. */
+	priority?: Priority;
+	/** Ids of the cards this one waits for; absent reads as none. */
+	dependsOn?: string[];
+	/** The last {@link MAX_NOTES} notes, oldest first. */
+	notes: CardNote[];
+	/** How many notes dropped off the front, so a reader knows history was elided. */
+	notesDropped: number;
+	/** Bumped per write; the compare-and-set guard a concurrent writer loses on. */
+	rev: number;
+	createdAt: number;
+	updatedAt: number;
+	/** The label of whoever wrote this revision. */
+	by: string;
+}
+
+/** A rejected field, phrased for the model: what was wrong, not that something was. */
+export type FieldError = { error: string };
+
+/** The title as stored: one sanitized line, or the reason it cannot be one. */
+export function normalizeTitle(raw: unknown): { title: string } | FieldError {
+	if (typeof raw !== "string") return { error: "title is required." };
+	const title = sanitizeLine(raw).trim();
+	if (title === "") return { error: "title is required." };
+	if (title.length > MAX_TITLE) return { error: `title must be at most ${MAX_TITLE} characters.` };
+	return { title };
+}
+
+/**
+ * The path hints as stored: deduplicated, posix-separated, and inside the
+ * repository.
+ *
+ * A hint is not a claim, so it is never resolved against the filesystem — but an
+ * absolute path or one that climbs out of the repository would read as a claim on
+ * something the board cannot see, so both are refused.
+ */
+export function normalizePathHints(raw: unknown): { paths: string[] } | FieldError {
+	if (raw === undefined) return { paths: [] };
+	if (!Array.isArray(raw)) return { error: "paths must be a list of repository-relative paths." };
+	if (raw.length > MAX_PATHS) return { error: `at most ${MAX_PATHS} paths are allowed.` };
+	const paths: string[] = [];
+	for (const entry of raw) {
+		if (typeof entry !== "string") return { error: "every path must be a string." };
+		const cleaned = sanitizeLine(entry).trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+		if (cleaned === "") return { error: "every path must be a non-empty string." };
+		if (cleaned.length > MAX_PATH) return { error: `a path must be at most ${MAX_PATH} characters.` };
+		if (cleaned.startsWith("/") || /^[a-zA-Z]:\//.test(cleaned)) {
+			return { error: `path "${cleaned}" is absolute; use a repository-relative path.` };
+		}
+		if (cleaned.split("/").includes("..")) return { error: `path "${cleaned}" is outside the repository.` };
+		if (!paths.includes(cleaned)) paths.push(cleaned);
+	}
+	return { paths };
+}
+
+/**
+ * The priority as stored: one of {@link PRIORITIES}, or the reason it cannot be.
+ *
+ * Anything absent is `normal`, so `add` needs no default of its own and an older
+ * card file reads as the ordinary feature it was.
+ */
+export function normalizePriority(raw: unknown): { priority: Priority } | FieldError {
+	const allowed = PRIORITIES.join(", ");
+	if (raw === undefined) return { priority: DEFAULT_PRIORITY };
+	if (typeof raw !== "string") return { error: `priority must be one of ${allowed}.` };
+	const priority = sanitizeLine(raw).trim().toLowerCase();
+	const known = PRIORITIES.find((entry) => entry === priority);
+	return known === undefined ? { error: `priority must be one of ${allowed}.` } : { priority: known };
+}
+
+/** A card's priority, with the absent field read as its meaning. */
+export function priorityOf(card: Card): Priority {
+	return card.priority ?? DEFAULT_PRIORITY;
+}
+
+/** A card's dependencies, with the absent field read as its meaning. */
+export function dependsOf(card: Card): readonly string[] {
+	return card.dependsOn ?? [];
+}
+
+/** Where a card's priority sits in {@link PRIORITIES}: the lane sort's first key after the lane. */
+export function priorityRank(card: Card): number {
+	return PRIORITIES.indexOf(priorityOf(card));
+}
+
+/**
+ * Whether `query` names `card`: its title, one of its path hints, or its holder.
+ *
+ * The page's filter and `board list`'s `query` are the same question, so they are the
+ * same rule here — a reader who finds a card in the browser finds it in the tool.
+ */
+export function matchesQuery(card: Card, query: string): boolean {
+	const needle = query.trim().toLowerCase();
+	if (needle === "") return true;
+	if (card.title.toLowerCase().includes(needle)) return true;
+	if (card.owner !== undefined && card.owner.label.toLowerCase().includes(needle)) return true;
+	return card.paths.some((path) => path.toLowerCase().includes(needle));
+}
+
+/** One note's text: a single sanitized line, or the reason it cannot be one. */
+export function normalizeNote(raw: unknown): { text: string } | FieldError {
+	if (typeof raw !== "string") return { error: "text is required." };
+	const text = sanitizeLine(raw).trim();
+	if (text === "") return { error: "text is required." };
+	if (text.length > MAX_NOTE) return { error: `text must be at most ${MAX_NOTE} characters.` };
+	return { text };
+}
+
+/**
+ * The recorded plan path: one line, and nothing more.
+ *
+ * The board never reads the plan, so it does not resolve or check the path — this
+ * is a note to the reader about which plan the card is executing.
+ */
+export function normalizePlanPath(raw: unknown): { path: string } | FieldError {
+	if (typeof raw !== "string") return { error: "path is required." };
+	const path = sanitizeLine(raw).trim();
+	if (path === "") return { error: "path is required." };
+	if (path.length > MAX_PLAN) return { error: `path must be at most ${MAX_PLAN} characters.` };
+	return { path };
+}
+
+/** A card id as a caller writes it (`4`, `#4`), or undefined when it is not one. */
+export function normalizeCardId(raw: unknown): string | undefined {
+	if (typeof raw !== "string") return undefined;
+	const id = raw.trim().replace(/^#/, "");
+	return /^[0-9]+$/.test(id) ? id : undefined;
+}
+
+/** The id as everything user-facing writes it. */
+export function cardRef(id: string): string {
+	return `#${id}`;
+}
+
+/**
+ * The board's version, as one string: every card's id and revision, sorted.
+ *
+ * The page pushes a snapshot only when this moves, so the signature has to differ
+ * for a revision bump even inside one millisecond — which is why it carries `rev`
+ * rather than a timestamp. A dropped card changes it by leaving.
+ */
+export function signatureOf(cards: readonly Card[]): string {
+	return cards
+		.map((card) => `${card.id}:${card.rev}`)
+		.sort()
+		.join(",");
+}
+
+/**
+ * Whether `value` is a card this build can trust.
+ *
+ * Shape *and* the two invariants a bug could otherwise smuggle past the rules: a
+ * `todo` card has no owner, and the other three lanes always have one. A card that
+ * fails here is dropped by the reader rather than repaired, because a repair would
+ * guess at which half of the record was meant.
+ */
+export function isCard(value: unknown): value is Card {
+	if (typeof value !== "object" || value === null) return false;
+	const card = value as Record<string, unknown>;
+	if (card.v !== CARD_VERSION) return false;
+	if (typeof card.id !== "string" || !/^[0-9]+$/.test(card.id)) return false;
+	if (typeof card.title !== "string" || card.title === "") return false;
+	if (!CARD_STATUSES.includes(card.status as CardStatus)) return false;
+	if (!isOwner(card.owner)) return false;
+	if (!Array.isArray(card.paths) || card.paths.length > MAX_PATHS) return false;
+	if (!card.paths.every((path) => typeof path === "string")) return false;
+	if (card.plan !== undefined && typeof card.plan !== "string") return false;
+	if (card.priority !== undefined && !PRIORITIES.includes(card.priority as Priority)) return false;
+	if (card.dependsOn !== undefined && !isDepends(card.dependsOn)) return false;
+	if (!Array.isArray(card.notes) || card.notes.length > MAX_NOTES) return false;
+	if (!card.notes.every(isNote)) return false;
+	if (typeof card.notesDropped !== "number") return false;
+	if (typeof card.rev !== "number" || !Number.isInteger(card.rev) || card.rev < 1) return false;
+	if (typeof card.createdAt !== "number" || typeof card.updatedAt !== "number") return false;
+	if (typeof card.by !== "string") return false;
+	return (card.status === "todo") === (card.owner === undefined);
+}
+
+function isOwner(value: unknown): boolean {
+	if (value === undefined) return true;
+	if (typeof value !== "object" || value === null) return false;
+	const owner = value as Record<string, unknown>;
+	if (typeof owner.label !== "string" || owner.label === "") return false;
+	return owner.id === undefined || typeof owner.id === "string";
+}
+
+/**
+ * Whether `value` is a dependency list this build can trust: card ids, unowned ids,
+ * and no repeats — a set, because waiting twice on one card means nothing.
+ */
+function isDepends(value: unknown): boolean {
+	if (!Array.isArray(value) || value.length > MAX_DEPENDS) return false;
+	const seen = new Set<string>();
+	for (const id of value) {
+		if (typeof id !== "string" || !/^[0-9]+$/.test(id) || seen.has(id)) return false;
+		seen.add(id);
+	}
+	return true;
+}
+
+function isNote(value: unknown): boolean {
+	if (typeof value !== "object" || value === null) return false;
+	const note = value as Record<string, unknown>;
+	return typeof note.by === "string" && typeof note.at === "number" && typeof note.text === "string";
+}

package/lib/board/links.ts

@@ -0,0 +1,117 @@
+/**
+ * The dependency graph: which card waits for which, answered over an index of the
+ * whole board.
+ *
+ * A link is one id in the waiting card's own file — `#4 dependsOn ["2"]` — and the
+ * reverse edge is never stored, because a second copy of one edge is a copy that can
+ * drift. Questions that need the other cards (is this blocker finished, would this
+ * link close a loop, who waits on this card) are answered here, and `rules.ts` calls
+ * in with the index it was given, so the tool, the page, and `team` refuse the same
+ * link for the same reason.
+ *
+ * The graph is bounded by the store, not here: a card file is read through `isCard`,
+ * so every id is numeric and unique, and a dependency that names a card which is not
+ * on the board is refused when the link is written — and a card cannot be dropped
+ * while another waits on it.
+ *
+ * Pure: no I/O, no clock, and no state.
+ */
+
+import { type Card, type FieldError, cardRef, dependsOf, MAX_DEPENDS, normalizeCardId } from "./card.ts";
+
+/** The board as the graph reads it: every card, by its unpadded id. */
+export type BoardIndex = ReadonlyMap<string, Card>;
+
+/** Index `cards` by id, which is what every graph question is asked against. */
+export function indexOf(cards: readonly Card[]): BoardIndex {
+	return new Map(cards.map((card) => [card.id, card]));
+}
+
+/**
+ * The cards `card` waits for that are not finished, in the order it names them.
+ *
+ * A finished dependency is what a link is for: it has stopped explaining why the
+ * card cannot start, so it stops counting here and the card reads as ready.
+ */
+export function blockersOf(card: Card, board: BoardIndex): Card[] {
+	return dependsOf(card)
+		.map((id) => board.get(id))
+		.filter((other): other is Card => other !== undefined && other.status !== "done");
+}
+
+/** The cards that wait on `id`, oldest id first, so a report reads in board order. */
+export function dependentsOf(id: string, board: BoardIndex): Card[] {
+	return [...board.values()].filter((card) => dependsOf(card).includes(id)).sort((a, b) => Number(a.id) - Number(b.id));
+}
+
+/** The sentence a claim, a move, or an assignment is refused with while `card` waits, or undefined. */
+export function waitingOn(card: Card, board: BoardIndex): string | undefined {
+	const blockers = blockersOf(card, board);
+	if (blockers.length === 0) return undefined;
+	const named = blockers.map((blocker) => `${cardRef(blocker.id)} (${blocker.status})`).join(", ");
+	return `${cardRef(card.id)} waits on ${named}.`;
+}
+
+/** The sentence a drop is refused with while another card waits on `id`, or undefined. */
+export function dependedOn(id: string, board: BoardIndex): string | undefined {
+	const dependents = dependentsOf(id, board);
+	if (dependents.length === 0) return undefined;
+	const named = dependents.map((card) => cardRef(card.id)).join(", ");
+	const which = dependents.length === 1 ? "that card" : "those cards";
+	return `${cardRef(id)} is waited on by ${named}; drop ${which} first.`;
+}
+
+/**
+ * Whether making `id` wait on `dependsOn` would close a loop, and the sentence saying so.
+ *
+ * A loop is nothing a reader could act on: every card in it would wait forever, and
+ * the rollup would keep calling the whole ring blocked. It is checked through the
+ * existing edges rather than by counting depth, so a chain of any length is refused.
+ */
+export function wouldCycle(id: string, dependsOn: readonly string[], board: BoardIndex): string | undefined {
+	for (const dependency of dependsOn) {
+		if (reaches(dependency, id, board)) {
+			return `${cardRef(id)} cannot wait on ${cardRef(dependency)}: that would make a loop.`;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * The dependency list as stored: existing card ids, no repeats, no self, no loop.
+ *
+ * `[]` is a legal answer and means "waits on nothing", so an edit can remove a link
+ * — the caller decides whether an absent list means "leave it alone" or "none".
+ */
+export function normalizeDepends(raw: unknown, id: string, board: BoardIndex): { dependsOn: string[] } | FieldError {
+	if (!Array.isArray(raw)) return { error: "dependsOn must be a list of card ids." };
+	const dependsOn: string[] = [];
+	for (const entry of raw) {
+		const parsed = normalizeCardId(entry);
+		// The file name is the canonical spelling of an id, so `#04` and `4` are one card.
+		const dependency = parsed === undefined ? undefined : String(Number(parsed));
+		if (dependency === undefined) return { error: `${JSON.stringify(entry)} is not a card id.` };
+		if (dependency === id) return { error: `${cardRef(id)} cannot wait on itself.` };
+		if (!board.has(dependency)) return { error: `${cardRef(dependency)} does not exist.` };
+		if (!dependsOn.includes(dependency)) dependsOn.push(dependency);
+	}
+	if (dependsOn.length > MAX_DEPENDS) return { error: `at most ${MAX_DEPENDS} dependencies are allowed.` };
+	const loop = wouldCycle(id, dependsOn, board);
+	if (loop !== undefined) return { error: loop };
+	return { dependsOn };
+}
+
+/** Whether `from` reaches `target` along the graph's edges. */
+function reaches(from: string, target: string, board: BoardIndex): boolean {
+	const seen = new Set<string>();
+	const pending = [from];
+	while (pending.length > 0) {
+		const id = pending.pop();
+		if (id === undefined || seen.has(id)) continue;
+		if (id === target) return true;
+		seen.add(id);
+		const card = board.get(id);
+		if (card !== undefined) pending.push(...dependsOf(card));
+	}
+	return false;
+}