light-plan 0.0.0-stage → 0.1.0

package/dist/core/model/types.js

@@ -0,0 +1,167 @@
+import { DERIVED_FLAG } from '../../shared/flag-rollup.js';
+export { DERIVED_FLAG, isDerivedFlag } from '../../shared/flag-rollup.js';
+/** Attribute value kinds a board config may declare. Deliberately small. */
+export const ATTRIBUTE_TYPES = [
+    'string',
+    'text',
+    'int',
+    'float',
+    'bool',
+    'date',
+    'enum',
+    'array',
+];
+/**
+ * The one type the template registry adds to the issue vocabulary: a container
+ * that stands in for a level instead of templatizing it.
+ *
+ * A template of a feature has to sit at the feature's depth, so something has to
+ * occupy the epic's level above it — that is a folder. It is never instantiated
+ * and it holds nothing but other folders and the roots of templates.
+ *
+ * The name is reserved across every namespace (`config/schema.ts` refuses it),
+ * because the registry reuses the issue types by name and a board declaring its
+ * own `folder` would make "which folder?" unanswerable.
+ */
+export const TEMPLATE_FOLDER_TYPE = 'folder';
+/** The definition the registry uses for its one own type. */
+export const TEMPLATE_FOLDER_DEF = {
+    label: 'Folder',
+    attributes: {},
+    body: '',
+};
+export function hasPeriods(config) {
+    return Object.keys(config.period_types).length > 0;
+}
+export function hasResources(config) {
+    return Object.keys(config.resource_types).length > 0;
+}
+export function hasSquads(config) {
+    return Object.keys(config.squad_types).length > 0;
+}
+/**
+ * Frontmatter keys owned by light-plan. Custom attributes may not use these.
+ * Fields backed by frontmatter keep the snake_case spelling of the key;
+ * fields derived at load time (dir, parentId, depth) are camelCase.
+ */
+export const ISSUE_RESERVED_FIELDS = [
+    'id',
+    'type',
+    'title',
+    'status',
+    'assignee',
+    'period',
+    'flag',
+    'depends_on',
+    'relates_to',
+    'related_files',
+    'created',
+    'updated',
+    'author',
+];
+export const PERIOD_RESERVED_FIELDS = [
+    'id',
+    'type',
+    'title',
+    'starts',
+    'ends',
+    'active',
+    'squad',
+    'created',
+    'updated',
+    'author',
+];
+export const RESOURCE_RESERVED_FIELDS = [
+    'id',
+    'type',
+    'title',
+    'capacity',
+    'covers',
+    'created',
+    'updated',
+    'author',
+];
+export const TEMPLATE_RESERVED_FIELDS = [
+    'id',
+    'type',
+    'title',
+    'description',
+    'params',
+    'depends_on',
+    'relates_to',
+    'related_files',
+    'created',
+    'updated',
+    'author',
+];
+export const SQUAD_RESERVED_FIELDS = [
+    'id',
+    'type',
+    'title',
+    'members',
+    'created',
+    'updated',
+    'author',
+];
+/**
+ * Why an issue somebody is working on has stopped.
+ *
+ * A flag is not a status: the work stays where it is, in whatever column the
+ * board calls "in progress", and the flag says it is not moving. That is
+ * deliberate — a board that had to invent a "blocked" column would lose the
+ * distinction between "nobody has started this" and "somebody started it and
+ * hit a wall", and only the second one needs anyone's attention today.
+ */
+export const FLAG_REASONS = ['blocked', 'paused', 'help'];
+const FLAG_LABELS = {
+    blocked: 'Blocked',
+    paused: 'Paused',
+    help: 'Needs help',
+    [DERIVED_FLAG]: 'Stopped inside',
+};
+/**
+ * A reason a *person* may raise. `DERIVED_FLAG` is deliberately not one: it is
+ * the roll-up's word for "something inside this has stopped", and letting
+ * somebody type it would make a container's own flag indistinguishable from one
+ * the roll-up may clear. `flagIssue` refuses it for that reason.
+ */
+export function isFlagReason(value) {
+    return FLAG_REASONS.includes(value);
+}
+/**
+ * A value that may legitimately sit in a document's `flag` field — the reasons
+ * a person may raise, plus the one the roll-up writes.
+ *
+ * A different question from `isFlagReason`, and `check` asks this one: `--fix`
+ * writes `DERIVED_FLAG` onto containers, so validating against the raiseable
+ * reasons alone would make the repair produce a board that fails the check that
+ * asked for it.
+ */
+export function isValidFlag(value) {
+    return isFlagReason(value) || value === DERIVED_FLAG;
+}
+/**
+ * The label a flag is shown with, falling back to whatever the file says — a
+ * value this version does not know is still printed rather than swallowed.
+ *
+ * `src/shared/model.ts` carries the same list and the same function for the
+ * browser, which imports nothing from core by design. They must agree, or the
+ * canvas and `lpm flag list` will call the same flag two different things.
+ */
+export function flagLabel(flag) {
+    return FLAG_LABELS[flag] ?? flag;
+}
+export function reservedFieldsFor(kind) {
+    if (kind === 'issue')
+        return ISSUE_RESERVED_FIELDS;
+    if (kind === 'period')
+        return PERIOD_RESERVED_FIELDS;
+    if (kind === 'resource')
+        return RESOURCE_RESERVED_FIELDS;
+    return kind === 'template' ? TEMPLATE_RESERVED_FIELDS : SQUAD_RESERVED_FIELDS;
+}
+/** True for the registry's own container type, which is never instantiated. */
+export function isFolderTemplate(node) {
+    return node.type === TEMPLATE_FOLDER_TYPE;
+}
+//# sourceMappingURL=types.js.map

package/dist/core/model/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/model/types.ts"],"names":[],"mappings":"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"}

package/dist/core/model/zod.d.ts

@@ -0,0 +1,6 @@
+import type { ZodError } from 'zod';
+/**
+ * Turn a zod error into `"path: message"` strings, the same format both schema
+ * parsers and the view parser use.
+ */
+export declare function formatZodIssues(error: ZodError): string[];

package/dist/core/model/zod.js

@@ -0,0 +1,11 @@
+/**
+ * Turn a zod error into `"path: message"` strings, the same format both schema
+ * parsers and the view parser use.
+ */
+export function formatZodIssues(error) {
+    return error.issues.map((issue) => {
+        const where = issue.path.length ? issue.path.join('.') : '(root)';
+        return `${where}: ${issue.message}`;
+    });
+}
+//# sourceMappingURL=zod.js.map

package/dist/core/model/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../../src/core/model/zod.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAe;IAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAClE,OAAO,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/operations/board-index.d.ts

@@ -0,0 +1,45 @@
+import type { LoadedBoard } from '../board/load.js';
+import type { AnyNode } from '../model/types.js';
+/**
+ * `.lpm/INDEX.md`: every document in the board, with its id, its title and a
+ * link to its file, nested exactly the way the folders are.
+ *
+ * A folder is named after its id and nothing else, so a file tree no longer
+ * says what anything is. This is where that went — one generated page a person
+ * can read (and a host can render) instead of walking the tree. It is derived
+ * state, never board truth: `load` never opens it, and deleting it costs
+ * nothing but a `lpm check --fix`.
+ *
+ * It is rewritten by the operations that can change it rather than on demand,
+ * so it is correct on disk the moment an operation returns. Rendering takes the
+ * board the operation ran against plus the one thing it did, because a reload
+ * costs a great deal more than a render does.
+ */
+/** What an operation just did, so the stale handle it holds can be corrected. */
+export interface IndexChange {
+    /** The document as the operation left it — or, when removed, as it was. */
+    node: AnyNode;
+    /** Its folder before the operation, when the operation moved it. */
+    from?: string;
+    /** The operation deleted it, and everything nested under it. */
+    removed?: boolean;
+}
+/**
+ * The whole index as markdown. Exported so `check` can tell a stale file from a
+ * current one without a second idea of what the file should say.
+ */
+export declare function renderBoardIndex(board: LoadedBoard, change?: IndexChange): string;
+/**
+ * Rewrite `.lpm/INDEX.md`. Call it after any write that adds, removes, moves or
+ * renames.
+ *
+ * Normally this renders from the board handle the operation ran against plus
+ * the one change it made, because a reload costs a great deal more than a render
+ * (~450ms against ~1ms) and the handle is right about everything else. When
+ * another process has rewritten the index since that handle was loaded, the
+ * cheap path would publish a table of contents missing their work, so this falls
+ * back to reading the board — including this operation's own write, which is
+ * already on disk by the time it is called, which is why the change is dropped
+ * on that path rather than applied twice.
+ */
+export declare function writeBoardIndex(board: LoadedBoard, change?: IndexChange): void;

package/dist/core/operations/board-index.js

@@ -0,0 +1,147 @@
+import path from 'node:path';
+import { loadBoard } from '../board/load.js';
+import { sameStamp, stampOf, writeFileAtomic } from '../storage/atomic.js';
+import { collectionDir, documentFileName } from '../storage/paths.js';
+/** Explorer order: `LP-2` before `LP-10`, which plain string order gets wrong. */
+const byName = new Intl.Collator('en', { numeric: true, sensitivity: 'base' });
+function entriesOf(nodes) {
+    return nodes.map((node) => ({ id: node.id, title: node.title, dir: node.dir }));
+}
+/**
+ * Correct a collection's entries for an operation the board handle predates.
+ * A folder carries its descendants, so a move rewrites their paths too.
+ */
+function withChange(entries, change, kind) {
+    if (!change || change.node.kind !== kind)
+        return entries;
+    const { node, from, removed } = change;
+    if (removed) {
+        const inside = node.dir + path.sep;
+        return entries.filter((entry) => entry.dir !== node.dir && !entry.dir.startsWith(inside));
+    }
+    let out = entries;
+    if (from !== undefined && from !== node.dir) {
+        const inside = from + path.sep;
+        out = out.map((entry) => entry.dir === from
+            ? { ...entry, dir: node.dir }
+            : entry.dir.startsWith(inside)
+                ? { ...entry, dir: node.dir + entry.dir.slice(from.length) }
+                : entry);
+    }
+    const fresh = { id: node.id, title: node.title, dir: node.dir };
+    const at = out.findIndex((entry) => entry.id === node.id);
+    return at === -1
+        ? [...out, fresh]
+        : out.map((entry, index) => (index === at ? fresh : entry));
+}
+/** A title is one line here whatever the frontmatter said, so a row stays a row. */
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function link(lpmDir, dir, kind) {
+    const file = path.join(dir, documentFileName(kind));
+    return path.relative(lpmDir, file).split(path.sep).join('/');
+}
+/**
+ * One collection as a nested list. Parenting comes from the paths themselves —
+ * a folder whose parent is not a document of this collection is drawn at the
+ * top, which is the forgiving reading `load` takes of the same tree.
+ */
+function renderSection(entries, root, kind, lpmDir) {
+    const dirs = new Set(entries.map((entry) => entry.dir));
+    const children = new Map();
+    for (const entry of entries) {
+        const parent = path.dirname(entry.dir);
+        const under = dirs.has(parent) ? parent : root;
+        const siblings = children.get(under);
+        if (siblings)
+            siblings.push(entry);
+        else
+            children.set(under, [entry]);
+    }
+    for (const siblings of children.values()) {
+        siblings.sort((a, b) => byName.compare(path.basename(a.dir), path.basename(b.dir)));
+    }
+    const lines = [];
+    const walk = (under, depth) => {
+        for (const entry of children.get(under) ?? []) {
+            const indent = '  '.repeat(depth);
+            lines.push(`${indent}- [${entry.id}](${link(lpmDir, entry.dir, kind)}) — ${oneLine(entry.title)}`);
+            walk(entry.dir, depth + 1);
+        }
+    };
+    walk(root, 0);
+    return lines;
+}
+const SECTIONS = [
+    { kind: 'issue', heading: 'Issues', of: (board) => board.issues },
+    { kind: 'period', heading: 'Timeline', of: (board) => board.periods },
+    { kind: 'resource', heading: 'Team', of: (board) => board.resources },
+    { kind: 'squad', heading: 'Squads', of: (board) => board.squads },
+    { kind: 'template', heading: 'Registry', of: (board) => board.templates },
+];
+/**
+ * The whole index as markdown. Exported so `check` can tell a stale file from a
+ * current one without a second idea of what the file should say.
+ */
+export function renderBoardIndex(board, change) {
+    const { paths } = board;
+    const out = [
+        '# Board index',
+        '',
+        '<!-- Generated by light-plan. Every document in this board, nested as its',
+        '     folders are. Rewritten on every change; edits here are overwritten. -->',
+    ];
+    for (const section of SECTIONS) {
+        const entries = withChange(entriesOf(section.of(board)), change, section.kind);
+        if (!entries.length)
+            continue;
+        const root = collectionDir(paths, section.kind);
+        out.push('', `## ${section.heading}`, '');
+        out.push(...renderSection(entries, root, section.kind, paths.lpmDir));
+    }
+    if (out.length === 4)
+        out.push('', 'This board has no documents yet.');
+    return out.join('\n') + '\n';
+}
+/**
+ * Whether the index on disk is the one this handle's contents belong to.
+ *
+ * The incremental render is "these documents, plus the one thing I did", and
+ * that is only the whole truth while nobody else has written since. On a shared
+ * checkout somebody may have created three issues in between, and rendering
+ * from this handle would drop all three — the index is the one file where a
+ * lost update costs the *rest* of the board rather than one document.
+ */
+function indexIsOurs(board) {
+    const expected = board.stamps.get(board.paths.indexPath);
+    const actual = stampOf(board.paths.indexPath);
+    if (!expected)
+        return actual === null;
+    return actual !== null && sameStamp(expected, actual);
+}
+/**
+ * Rewrite `.lpm/INDEX.md`. Call it after any write that adds, removes, moves or
+ * renames.
+ *
+ * Normally this renders from the board handle the operation ran against plus
+ * the one change it made, because a reload costs a great deal more than a render
+ * (~450ms against ~1ms) and the handle is right about everything else. When
+ * another process has rewritten the index since that handle was loaded, the
+ * cheap path would publish a table of contents missing their work, so this falls
+ * back to reading the board — including this operation's own write, which is
+ * already on disk by the time it is called, which is why the change is dropped
+ * on that path rather than applied twice.
+ */
+export function writeBoardIndex(board, change) {
+    const { indexPath } = board.paths;
+    const [source, applied] = indexIsOurs(board)
+        ? [board, change]
+        : [loadBoard(board.paths, board.cache ? { cache: board.cache } : undefined), undefined];
+    writeFileAtomic(indexPath, renderBoardIndex(source, applied));
+    // So a second write in the same operation still takes the cheap path.
+    const stamp = stampOf(indexPath);
+    if (stamp)
+        board.stamps.set(indexPath, stamp);
+}
+//# sourceMappingURL=board-index.js.map

package/dist/core/operations/board-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-index.js","sourceRoot":"","sources":["../../../src/core/operations/board-index.ts"],"names":[],"mappings":"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"}

package/dist/core/operations/claim.d.ts

@@ -0,0 +1,69 @@
+import type { LoadedBoard } from '../board/load.js';
+import type { Issue, Resource } from '../model/types.js';
+import type { MoveResult } from './move.js';
+/**
+ * Claiming an issue: the one operation that is a test-and-set.
+ *
+ * Everything else on a board is somebody stating an intention — a title, a
+ * dependency, a sprint. This is the one place where two people can want the
+ * same thing and only one of them can have it, so "read the board, decide,
+ * write" is not good enough: two agents on one checkout both load the board,
+ * both see `LP-12` waiting in the pool they cover, and both write their own name
+ * on it. The board then says one thing and the two agents believe another, and
+ * the work is done twice.
+ *
+ * So a claim is not `moveNode` with an assignee. It is:
+ *
+ * 1. take the board lock, so nobody else is mid-write;
+ * 2. **re-read the board**, because the handle the caller is holding was loaded
+ *    before the lock and may already be out of date;
+ * 3. check the issue is still free *as it stands on disk* — and refuse if it is
+ *    not, naming who has it;
+ * 4. only then write.
+ *
+ * Step 2 is what makes this different from every other operation, and it is why
+ * this one takes the cost of a reload. Elsewhere a stale handle is *detected*
+ * (`requireUnchanged`) and the caller is told to read again; here the caller is
+ * a queue runner picking work, and "read again" is something this can do for
+ * itself in the same breath.
+ *
+ * The claim is recorded in the document itself and not only in the frontmatter:
+ * an entry goes in the activity section, so the `_issue.md` a person opens in a
+ * file tree says who took it and when, and so the git history of the board
+ * carries the same fact. `assignee` plus an active status is what withholds the
+ * issue from everybody else's queue — `candidatesFor` skips work in an active
+ * status and routes the rest by assignee — so writing them *is* the claim, and
+ * the activity entry is how a reader finds out about it.
+ *
+ * What this does not do: it is not permission. `--force` takes work off
+ * somebody, exactly as it did before, because light-plan routes work and does
+ * not police it — the point is that taking it is now a deliberate act with a
+ * line in the document, rather than the accident of writing last.
+ */
+export interface ClaimInput {
+    /** Who is taking it: a resource id or name. */
+    assignee: string;
+    /**
+     * The status to move it into. Defaults to the board's first active status,
+     * which is what "picked up" means everywhere else.
+     */
+    status?: string;
+    /** Take it even though somebody else holds it. */
+    force?: boolean;
+}
+export interface ClaimResult extends MoveResult {
+    issue: Issue;
+    /** The resource that now holds it. */
+    holder: Resource;
+    /** Who it was taken off, when `force` took it off somebody. */
+    takenFrom?: string;
+    /** The issue was already this resource's, in this status — nothing changed. */
+    alreadyHeld: boolean;
+}
+/**
+ * Claim an issue for a resource, atomically.
+ *
+ * `target` is only used for its id: the issue this actually writes is the one
+ * on disk at the moment the lock is held.
+ */
+export declare function claimIssue(board: LoadedBoard, target: Issue, input: ClaimInput): ClaimResult;

package/dist/core/operations/claim.js

@@ -0,0 +1,115 @@
+import { loadBoard } from '../board/load.js';
+import { findIssue, isGenericResource } from '../board/query.js';
+import { isActiveStatus, isTerminalStatus, startStatusId } from '../config/lookup.js';
+import { BoardError, ConflictError } from '../errors.js';
+import { appendActivityEntry } from '../storage/activity.js';
+import { nowIso } from '../storage/document.js';
+import { moveNode } from './move.js';
+import { boardWrite, requireResource } from './shared.js';
+/**
+ * Whether `holder` may take an issue that currently sits with `current` without
+ * saying `--force`.
+ *
+ * Work parked in a pool is *waiting* for whoever covers the pool, so picking it
+ * up is the ordinary path and not a theft. Work with somebody's name on it is
+ * theirs. This is the rule both `lpm task start` and MCP `start_task` used to
+ * carry separately, and they did not agree: the CLI let a pool be drawn from and
+ * the MCP tool refused. One definition, so a person and an agent working the
+ * same board are offered the same deal.
+ */
+function mayTake(board, holder, current) {
+    if (current === holder.id)
+        return true;
+    const owner = board.resourcesById.get(current);
+    return Boolean(owner && isGenericResource(board, owner) && holder.covers.includes(current));
+}
+function heldError(board, issue, holder) {
+    const owner = issue.assignee ? board.resourcesById.get(issue.assignee) : null;
+    const name = owner ? `${owner.title} (${owner.id})` : issue.assignee;
+    const active = isActiveStatus(board.config, issue.status);
+    return new ConflictError(`${issue.id} is already ${active ? 'being worked on by' : 'assigned to'} ${name}`, [
+        // Read off disk a moment ago, which is the point: whoever is reading this
+        // lost the race rather than asked for something impossible.
+        `It is "${issue.status}" on the board as it stands now, and ${holder.title} (${holder.id}) is asking for it.`,
+        active
+            ? 'Force takes it off somebody who is part-way through it. Take something else instead.'
+            : 'Force takes it anyway, if you know it is not being worked on.',
+    ]);
+}
+/**
+ * Claim an issue for a resource, atomically.
+ *
+ * `target` is only used for its id: the issue this actually writes is the one
+ * on disk at the moment the lock is held.
+ */
+export function claimIssue(board, target, input) {
+    return boardWrite(board, `claim ${target.id}`, () => claimUnderLock(board, target, input));
+}
+function claimUnderLock(board, target, input) {
+    // The board as it is *now*, not as the caller read it. Everything below —
+    // who holds the issue, what status it is in, what its body says — has to come
+    // from this handle, or the check and the write would be about different
+    // versions of the same document.
+    const fresh = loadBoard(board.paths, board.cache ? { cache: board.cache } : undefined);
+    const issue = findIssue(fresh, target.id);
+    if (!issue) {
+        throw new ConflictError(`${target.id} is no longer on the board`, [
+            'It was deleted while you were reading. Ask for the next task.',
+        ]);
+    }
+    const holder = requireResource(fresh, input.assignee);
+    const status = input.status ?? startStatusId(fresh.config);
+    if (!status) {
+        throw new BoardError('This board declares no active status', [
+            'Mark one of the statuses in .lpm/config.yml with `active: true`.',
+        ]);
+    }
+    if (isTerminalStatus(fresh.config, issue.status)) {
+        throw new BoardError(`${issue.id} is already "${issue.status}"`, [
+            'Reopen it first if the work is not actually done.',
+        ]);
+    }
+    let takenFrom;
+    if (issue.assignee && !mayTake(fresh, holder, issue.assignee)) {
+        if (!input.force)
+            throw heldError(fresh, issue, holder);
+        takenFrom = issue.assignee;
+    }
+    const alreadyHeld = issue.assignee === holder.id && issue.status === status;
+    if (alreadyHeld) {
+        return {
+            node: issue,
+            issue,
+            holder,
+            alreadyHeld: true,
+            statusChanged: false,
+            periodChanged: false,
+            assigneeChanged: false,
+            rollups: [],
+            flagRollups: [],
+        };
+    }
+    // The claim, written into the document a person reads as well as the
+    // frontmatter a tool reads. `moveNode` does the rest — the status, the
+    // assignee, and carrying a reopened container up the tree — and it re-checks
+    // the file against this handle's stamp on the way in, which is the second
+    // line of defence if the lock was ever broken underneath us.
+    const claimed = {
+        ...issue,
+        body: appendActivityEntry(issue.body, {
+            at: nowIso(),
+            author: `${holder.title} (${holder.id})`,
+            heading: takenFrom ? `claimed — taken from ${takenFrom}` : 'claimed',
+            text: '',
+        }),
+    };
+    const result = moveNode(fresh, claimed, { assignee: holder.id, status });
+    return {
+        ...result,
+        issue: result.node,
+        holder,
+        alreadyHeld: false,
+        ...(takenFrom ? { takenFrom } : {}),
+    };
+}
+//# sourceMappingURL=claim.js.map

package/dist/core/operations/claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","sourceRoot":"","sources":["../../../src/core/operations/claim.ts"],"names":[],"mappings":"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"}

package/dist/core/operations/comment.d.ts

@@ -0,0 +1,30 @@
+import type { LoadedBoard } from '../board/load.js';
+import type { AnyNode } from '../model/types.js';
+import type { Comment } from '../storage/comments.js';
+/**
+ * Commenting on a document.
+ *
+ * The narrative half of a board: what was tried, what broke, what a reviewer
+ * asked for. Kept separate from the document's own body, which describes what
+ * the work *is* rather than how it went — and separate from the frontmatter,
+ * which is the part tools read.
+ *
+ * Nothing here validates the board, because a comment cannot make one invalid.
+ */
+export interface CommentInput {
+    body: string;
+    /** Defaults to the git identity of the checkout. */
+    author?: string;
+    /** Defaults to now. Accepted so an importer can preserve history. */
+    at?: string;
+}
+export interface CommentResult {
+    node: AnyNode;
+    comment: Comment;
+    /** How many the document has now. */
+    total: number;
+}
+export declare function addComment(board: LoadedBoard, id: string, input: CommentInput): CommentResult;
+export declare function listComments(board: LoadedBoard, id: string): Comment[];
+/** Delete one comment by its position. Numbering starts at 1. */
+export declare function removeComment(board: LoadedBoard, id: string, index: number): Comment;