@adecore/plan 0.0.1 → 0.17.0-beta.2

package/dist/apply.js

@@ -0,0 +1,379 @@
+import { PlanChecksSchema, PlanItemIdSchema, PlanKindSchema, PlanMetaSchema, PlanOpSchema, PlanSchema, PlanSectionSchema, PlanStepSchema, PlanStepStateSchema, PlanTextSchema } from './protocol.js';
+import { z } from 'zod';
+import { canApply } from './permissions.js';
+import { allItems, allSteps, effectiveChecks, locateItem, refuse, structureProblem } from './tree.js';
+const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+export function randomItemId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(6));
+    return Array.from(bytes, (byte) => ID_ALPHABET[byte % ID_ALPHABET.length]).join('');
+}
+function issueMessage(error) {
+    const issue = error.issues[0];
+    if (!issue) {
+        return 'The plan is not valid';
+    }
+    const path = issue.path.map((part) => (typeof part === 'number' ? `[${part}]` : `.${String(part)}`)).join('');
+    return `${path ? `${path.replace(/^\./, '')}: ` : ''}${issue.message}`;
+}
+function idMinter(taken, mintId, minted) {
+    return () => {
+        for (let attempt = 0; attempt < 1000; attempt++) {
+            const id = mintId();
+            if (!taken.has(id)) {
+                taken.add(id);
+                minted.push(id);
+                return id;
+            }
+        }
+        throw new Error('Could not mint a free plan item id');
+    };
+}
+function setState(step, state, actor, now) {
+    // An agent confirming what a person set leaves the person's mark on it.
+    if (actor === 'agent' && step.by === 'person' && step.state === state) {
+        return;
+    }
+    // A person taking a mark away leaves nothing an agent has to respect, so a mis-click never locks the agent out.
+    if (actor === 'person' && state === 'open') {
+        step.state = state;
+        delete step.by;
+        delete step.at;
+        return;
+    }
+    step.state = state;
+    step.by = actor;
+    step.at = now;
+}
+function setNote(step, text) {
+    if (text === '') {
+        delete step.note;
+    }
+    else {
+        step.note = text;
+    }
+}
+/* The array a new or moved item goes into and where, or a refusal. */
+function placeFor(plan, type, under, after) {
+    let parent = null;
+    let siblings = plan.items;
+    if (under !== undefined) {
+        const location = locateItem(plan, under);
+        if (!location) {
+            return refuse('plan-missing-item', `The plan has no item "${under}"`);
+        }
+        const target = location.item;
+        if (target.type === 'text') {
+            return refuse('plan-bad-position', `"${under}" is a text block, which holds no items`);
+        }
+        parent = target;
+        if (target.type === 'section') {
+            siblings = target.items;
+        }
+        else {
+            target.steps ??= [];
+            siblings = target.steps;
+        }
+    }
+    else if (after !== undefined) {
+        const location = locateItem(plan, after);
+        if (!location) {
+            return refuse('plan-missing-item', `The plan has no item "${after}"`);
+        }
+        parent = location.parent;
+        siblings = location.siblings;
+    }
+    if (type === 'section' && parent !== null) {
+        return refuse('plan-bad-position', 'A section only stands at the top of a plan');
+    }
+    if (type === 'text' && parent?.type === 'step') {
+        return refuse('plan-bad-position', 'A step only holds steps, not a text block');
+    }
+    if (after === undefined) {
+        return { siblings, index: siblings.length, parent };
+    }
+    const index = siblings.findIndex((item) => item.id === after);
+    if (index === -1) {
+        return refuse('plan-bad-position', `"${after}" is not directly under "${under}"`);
+    }
+    return { siblings, index: index + 1, parent };
+}
+/* A leaf that gets its first sub-step: its state now follows from its children. */
+function becomeParent(parent, dropped) {
+    if (parent?.type !== 'step' || (parent.steps?.length ?? 0) !== 1) {
+        return;
+    }
+    if (parent.state !== undefined) {
+        dropped.push(parent.id);
+    }
+    delete parent.state;
+    delete parent.by;
+    delete parent.at;
+}
+function pruneEmptySteps(items) {
+    for (const item of allItems(items)) {
+        if (item.type === 'step' && item.steps?.length === 0) {
+            delete item.steps;
+        }
+    }
+}
+function applyOne(plan, op, options, mint, dropped) {
+    const verdict = canApply(op, options.actor, plan);
+    if (!verdict.ok) {
+        return verdict;
+    }
+    const stepAt = (id) => locateItem(plan, id).item;
+    switch (op.op) {
+        case 'set': {
+            for (const id of op.ids) {
+                const step = stepAt(id);
+                setState(step, op.state, options.actor, options.now);
+                if (op.note !== undefined) {
+                    setNote(step, op.note);
+                }
+            }
+            if (op.next !== undefined) {
+                setState(stepAt(op.next), 'active', options.actor, options.now);
+            }
+            return null;
+        }
+        case 'note':
+            setNote(stepAt(op.id), op.text);
+            return null;
+        case 'unlock': {
+            const roots = op.ids === 'all' ? plan.items : op.ids.map((id) => stepAt(id));
+            for (const step of allSteps(roots)) {
+                if (effectiveChecks(plan, step) === 'agent') {
+                    step.unlocked = true;
+                }
+            }
+            return null;
+        }
+        case 'add': {
+            const id = op.id ?? mint();
+            if (op.id !== undefined && locateItem(plan, op.id)) {
+                return refuse('duplicate-id', `The plan already has an item "${op.id}"`);
+            }
+            if (op.checks !== undefined && op.type !== 'step') {
+                return refuse('plan-invalid', 'Only a step has checks');
+            }
+            const place = placeFor(plan, op.type, op.under, op.after);
+            if ('ok' in place) {
+                return place;
+            }
+            const base = { id, title: op.title, ...(op.description ? { description: op.description } : {}) };
+            const item = op.type === 'section'
+                ? { type: 'section', ...base, items: [] }
+                : op.type === 'text'
+                    ? { type: 'text', ...base }
+                    : { type: 'step', ...base, ...(op.checks ? { checks: op.checks } : {}) };
+            place.siblings.splice(place.index, 0, item);
+            becomeParent(place.parent, dropped);
+            return null;
+        }
+        case 'edit': {
+            const item = locateItem(plan, op.id).item;
+            if (op.checks !== undefined && item.type !== 'step') {
+                return refuse('plan-invalid', 'Only a step has checks');
+            }
+            if (op.title !== undefined) {
+                item.title = op.title;
+            }
+            if (op.description === '') {
+                delete item.description;
+            }
+            else if (op.description !== undefined) {
+                item.description = op.description;
+            }
+            if (op.checks !== undefined && item.type === 'step') {
+                item.checks = op.checks;
+            }
+            return null;
+        }
+        case 'move': {
+            const location = locateItem(plan, op.id);
+            if (op.after === op.id || (op.under !== undefined && allItems([location.item]).some((item) => item.id === op.under))) {
+                return refuse('plan-bad-position', `"${op.id}" cannot move into itself`);
+            }
+            location.siblings.splice(location.index, 1);
+            const place = placeFor(plan, location.item.type, op.under, op.after);
+            if ('ok' in place) {
+                return place;
+            }
+            place.siblings.splice(place.index, 0, location.item);
+            becomeParent(place.parent, dropped);
+            return null;
+        }
+        case 'remove': {
+            const location = locateItem(plan, op.id);
+            location.siblings.splice(location.index, 1);
+            return null;
+        }
+        case 'meta': {
+            if (op.title !== undefined) {
+                plan.meta.title = op.title;
+            }
+            for (const key of ['summary', 'status']) {
+                if (op[key] === '') {
+                    delete plan.meta[key];
+                }
+                else if (op[key] !== undefined) {
+                    plan.meta[key] = op[key];
+                }
+            }
+            if (op.checks !== undefined) {
+                plan.meta.checks = op.checks;
+            }
+            return null;
+        }
+    }
+}
+/*
+ * Applies a batch of operations for one actor, all or nothing. Each operation sees the plan as the
+ * ones before it left it, and the whole batch is one rev, so a step done and the next one active land
+ * together.
+ */
+export function applyPlanOps(plan, ops, options) {
+    const parsedOps = z.array(PlanOpSchema).min(1).safeParse(ops);
+    if (!parsedOps.success) {
+        return refuse('plan-invalid', issueMessage(parsedOps.error));
+    }
+    const next = structuredClone(plan);
+    const minted = [];
+    const dropped = [];
+    const taken = new Set(allItems(next.items).map((item) => item.id));
+    const mint = idMinter(taken, options.mintId ?? randomItemId, minted);
+    for (const op of parsedOps.data) {
+        const problem = applyOne(next, op, options, mint, dropped);
+        if (problem) {
+            return problem;
+        }
+        for (const item of allItems(next.items)) {
+            taken.add(item.id);
+        }
+    }
+    pruneEmptySteps(next.items);
+    next.rev = plan.rev + 1;
+    const checked = validatePlan(next);
+    if (!checked.ok) {
+        return checked;
+    }
+    return { ok: true, plan: checked.plan, minted, dropped };
+}
+/* A plan as it is stored or sent: the schema, then the rules that need the whole tree. */
+export function validatePlan(value) {
+    const parsed = PlanSchema.safeParse(value);
+    if (!parsed.success) {
+        return refuse('plan-invalid', issueMessage(parsed.error));
+    }
+    const problem = structureProblem(parsed.data);
+    return problem ?? { ok: true, plan: parsed.data };
+}
+/*
+ * What an agent hands `plan new`. Strict, so a misspelled field is refused by its path instead of
+ * dropped. Ids are optional and minted when absent; who set a state and when is never the agent's to say.
+ */
+export const PlanDraftStepSchema = z.strictObject({
+    type: PlanStepSchema.shape.type,
+    id: PlanItemIdSchema.optional(),
+    title: PlanStepSchema.shape.title,
+    description: PlanStepSchema.shape.description,
+    checks: PlanStepSchema.shape.checks,
+    state: PlanStepStateSchema.optional(),
+    note: PlanStepSchema.shape.note,
+    get steps() {
+        return z.array(PlanDraftStepSchema).optional();
+    }
+});
+export const PlanDraftTextSchema = z.strictObject({ ...PlanTextSchema.shape, id: PlanItemIdSchema.optional() });
+export const PlanDraftSectionSchema = z.strictObject({
+    ...PlanSectionSchema.shape,
+    id: PlanItemIdSchema.optional(),
+    items: z.array(z.discriminatedUnion('type', [PlanDraftTextSchema, PlanDraftStepSchema]))
+});
+export const PlanDraftItemSchema = z.discriminatedUnion('type', [PlanDraftSectionSchema, PlanDraftTextSchema, PlanDraftStepSchema]);
+export const PlanDraftMetaSchema = z.strictObject({
+    title: PlanMetaSchema.shape.title.optional(),
+    kind: PlanKindSchema.optional(),
+    summary: PlanMetaSchema.shape.summary,
+    status: PlanMetaSchema.shape.status,
+    checks: PlanChecksSchema.optional()
+});
+export const PlanDraftSchema = z.strictObject({
+    meta: PlanDraftMetaSchema.optional(),
+    items: z.array(PlanDraftItemSchema)
+});
+export function parsePlanDraft(value) {
+    const parsed = PlanDraftSchema.safeParse(value);
+    return parsed.success ? { ok: true, draft: parsed.data } : refuse('plan-invalid', issueMessage(parsed.error));
+}
+/* A new plan from an agent's draft: ids minted, states marked as the agent's, and the same rules as any later change. */
+export function createPlan(draft, options) {
+    const parsed = PlanDraftSchema.safeParse(draft);
+    if (!parsed.success) {
+        return refuse('plan-invalid', issueMessage(parsed.error));
+    }
+    const source = parsed.data;
+    const title = options.meta?.title ?? source.meta?.title;
+    if (!title) {
+        return refuse('plan-invalid', 'A plan needs a title');
+    }
+    const meta = {
+        title,
+        kind: options.meta?.kind ?? source.meta?.kind ?? 'steps',
+        ...(source.meta?.summary ? { summary: source.meta.summary } : {}),
+        ...(source.meta?.status ? { status: source.meta.status } : {}),
+        checks: options.meta?.checks ?? source.meta?.checks ?? 'anyone'
+    };
+    const minted = [];
+    const taken = new Set();
+    for (const item of allDraftItems(source.items)) {
+        if (item.id !== undefined) {
+            if (taken.has(item.id)) {
+                return refuse('duplicate-id', `Two items share the id "${item.id}"`);
+            }
+            taken.add(item.id);
+        }
+    }
+    const mint = idMinter(taken, options.mintId ?? randomItemId, minted);
+    const described = (value) => {
+        if (value.description === '') {
+            delete value.description;
+        }
+        return value;
+    };
+    const toStep = (step) => {
+        const { steps, state, note, ...rest } = step;
+        const result = described({ ...rest, id: step.id ?? mint() });
+        if (steps && steps.length > 0) {
+            result.steps = steps.map(toStep);
+        }
+        if (state !== undefined) {
+            Object.assign(result, { state, by: 'agent', at: options.now });
+        }
+        if (note) {
+            result.note = note;
+        }
+        return result;
+    };
+    const toText = (text) => described({ ...text, id: text.id ?? mint() });
+    const items = source.items.map((item) => {
+        if (item.type === 'section') {
+            return described({ ...item, id: item.id ?? mint(), items: item.items.map((child) => (child.type === 'text' ? toText(child) : toStep(child))) });
+        }
+        return item.type === 'text' ? toText(item) : toStep(item);
+    });
+    const plan = { id: options.id, rev: 0, createdAt: options.now, meta, items };
+    const checked = validatePlan(plan);
+    if (!checked.ok) {
+        return checked;
+    }
+    for (const step of allSteps(checked.plan.items)) {
+        if (step.state !== undefined && effectiveChecks(checked.plan, step) === 'person') {
+            return refuse('person-only', `Only a person checks "${step.id}"`);
+        }
+    }
+    return { ok: true, plan: checked.plan, minted, dropped: [] };
+}
+function allDraftItems(items) {
+    return items.flatMap((item) => [item, ...allDraftItems(item.type === 'section' ? item.items : item.type === 'step' ? (item.steps ?? []) : [])]);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type PlanApplyOptions, type PlanApplied, randomItemId, applyPlanOps, validatePlan, PlanDraftStepSchema, type PlanDraftStep, PlanDraftTextSchema, type PlanDraftText, PlanDraftSectionSchema, type PlanDraftSection, PlanDraftItemSchema, type PlanDraftItem, PlanDraftMetaSchema, type PlanDraftMeta, PlanDraftSchema, type PlanDraft, parsePlanDraft, type PlanCreateOptions, createPlan } from './apply.ts';
+export { planToMarkdown, parsePlanMarkdown } from './markdown.ts';
+export { type PlanVerdict, canApply, canDeletePlan } from './permissions.ts';
+export { PLAN_STATE_MARKERS, PLAN_LEGEND, type PlanTextOptions, progressText, renderPlanText } from './text.ts';
+export { type PlanRefusalCode, type PlanRefusal, refuse, type PlanLocation, locateItem, findItem, allItems, allSteps, isParentStep, effectiveChecks, isFinishedOutcome, deriveState, stepState, type PlanProgress, planProgress, leafSteps, activeStepIds, holdsPersonState, structureProblem } from './tree.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { randomItemId, applyPlanOps, validatePlan, PlanDraftStepSchema, PlanDraftTextSchema, PlanDraftSectionSchema, PlanDraftItemSchema, PlanDraftMetaSchema, PlanDraftSchema, parsePlanDraft, createPlan } from './apply.js';
+export { planToMarkdown, parsePlanMarkdown } from './markdown.js';
+export { canApply, canDeletePlan } from './permissions.js';
+export { PLAN_STATE_MARKERS, PLAN_LEGEND, progressText, renderPlanText } from './text.js';
+export { refuse, locateItem, findItem, allItems, allSteps, isParentStep, effectiveChecks, isFinishedOutcome, deriveState, stepState, planProgress, leafSteps, activeStepIds, holdsPersonState, structureProblem } from './tree.js';

package/dist/markdown.d.ts

@@ -0,0 +1,8 @@
+import type { Plan } from './protocol.ts';
+import type { PlanDraft } from './apply.ts';
+import { type PlanRefusal } from './tree.ts';
+export declare function planToMarkdown(plan: Plan): string;
+export declare function parsePlanMarkdown(markdown: string): {
+    ok: true;
+    draft: PlanDraft;
+} | PlanRefusal;

package/dist/markdown.js

@@ -0,0 +1,271 @@
+import { PLAN_STATE_MARKERS } from './text.js';
+import { refuse, stepState } from './tree.js';
+const INDENT = '    ';
+const MARKER_STATES = {
+    ' ': undefined,
+    x: 'done',
+    X: 'done',
+    '~': 'active',
+    '!': 'failed',
+    '-': 'skipped',
+    '?': 'blocked',
+    w: 'warning',
+    W: 'warning',
+    i: 'info',
+    I: 'info'
+};
+/* What the reader takes for a heading, a rule, a list item or a quote at the start of a line, and the escape itself. */
+const MARKUP = /^(#{1,6}\s|(-{3,}|\*{3,}|_{3,})$|[-*+]\s|>|\\)/;
+function escapeLine(line) {
+    return MARKUP.test(line.trimStart()) ? `\\${line}` : line;
+}
+function escapeText(text) {
+    return text.split('\n').map(escapeLine).join('\n');
+}
+function escapeBold(title) {
+    return title.replace(/[\\*]/g, '\\$&');
+}
+/* A later line of a text block that starts in bold would start a text block of its own. */
+function escapeQuoted(line) {
+    return /^(\*\*|\\)/.test(line.trimStart()) ? `\\${line}` : line;
+}
+function dropEscape(line) {
+    return line.trimStart().startsWith('\\') ? line.replace('\\', '') : line;
+}
+/*
+ * A plan as a GFM task list: `#` the title, `##` a section, `> **Title**` a text block, `- [ ]` a
+ * step with its sub-steps indented under it. Beyond `[ ]` and `[x]` a step carries the markers of
+ * `plan read`, and a `>` line under a step is its note. Ids, who set a state and the locks stay out.
+ * A line of text the reader would take for markup starts with a backslash, which the reader drops.
+ */
+export function planToMarkdown(plan) {
+    const blocks = [`# ${plan.meta.title}`];
+    if (plan.meta.summary) {
+        blocks.push(escapeText(plan.meta.summary));
+    }
+    const stepLines = (step, depth) => {
+        const indent = INDENT.repeat(depth);
+        const inner = INDENT.repeat(depth + 1);
+        const lines = [`${indent}- ${PLAN_STATE_MARKERS[stepState(step)]} ${step.title}`];
+        for (const line of step.description?.split('\n') ?? []) {
+            lines.push(line === '' ? '' : `${inner}${escapeLine(line)}`);
+        }
+        for (const line of step.note?.split('\n') ?? []) {
+            lines.push(`${inner}> ${line}`);
+        }
+        for (const child of step.steps ?? []) {
+            lines.push(...stepLines(child, depth + 1));
+        }
+        return lines;
+    };
+    const textBlock = (item) => {
+        const [first = '', ...rest] = item.description?.split('\n') ?? [];
+        return [`> **${escapeBold(item.title)}**${first ? ` ${first}` : ''}`, ...rest.map((line) => `> ${escapeQuoted(line)}`)].join('\n');
+    };
+    const itemBlocks = (items) => {
+        const result = [];
+        let list = [];
+        const flush = () => {
+            if (list.length > 0) {
+                result.push(list.join('\n'));
+                list = [];
+            }
+        };
+        for (const item of items) {
+            if (item.type === 'step') {
+                list.push(...stepLines(item, 0));
+            }
+            else if (item.type === 'text') {
+                flush();
+                result.push(textBlock(item));
+            }
+        }
+        flush();
+        return result;
+    };
+    let inSection = false;
+    let loose = [];
+    const flushLoose = () => {
+        if (loose.length > 0) {
+            // Only a rule brings the items after a section back to the top of the plan.
+            if (inSection) {
+                blocks.push('---');
+                inSection = false;
+            }
+            blocks.push(...itemBlocks(loose));
+            loose = [];
+        }
+    };
+    for (const item of plan.items) {
+        if (item.type !== 'section') {
+            loose.push(item);
+            continue;
+        }
+        flushLoose();
+        blocks.push(`## ${item.title}`);
+        if (item.description) {
+            blocks.push(escapeText(item.description));
+        }
+        blocks.push(...itemBlocks(item.items));
+        inSection = true;
+    }
+    flushLoose();
+    return `${blocks.join('\n\n')}\n`;
+}
+function indentOf(line) {
+    let width = 0;
+    for (const char of line) {
+        if (char === ' ') {
+            width++;
+        }
+        else if (char === '\t') {
+            width += 4;
+        }
+        else {
+            break;
+        }
+    }
+    return width;
+}
+function appendLine(value, line, blanks = 0) {
+    return value === undefined ? line : `${value}\n${'\n'.repeat(blanks)}${line}`;
+}
+/*
+ * Reads a GFM task list into a draft for `plan new`. Lenient where Markdown is (a list item without a
+ * checkbox is an open step), strict where a line cannot belong to anything.
+ */
+export function parsePlanMarkdown(markdown) {
+    const draft = { items: [] };
+    let section = null;
+    let stack = [];
+    let text = null;
+    // The text the last line of prose went on and the blank lines since, so a paragraph break inside it stays.
+    let continuing = null;
+    let blanks = 0;
+    const container = () => (section ? section.items : draft.items);
+    const popTo = (indent) => {
+        while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+    };
+    const lines = markdown.replace(/\r\n?/g, '\n').split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index].trimEnd();
+        const content = raw.trim();
+        const indent = indentOf(raw);
+        const invalid = (message) => refuse('plan-invalid', `Line ${index + 1}: ${message}`);
+        if (content === '') {
+            text = null;
+            blanks++;
+            continue;
+        }
+        const previous = continuing;
+        const gap = blanks;
+        continuing = null;
+        blanks = 0;
+        const blanksBefore = (target) => {
+            continuing = target;
+            return previous === target ? gap : 0;
+        };
+        const plain = dropEscape(content);
+        const heading = /^(#{1,6})\s+(.*)$/.exec(content);
+        if (heading && indent < 4) {
+            text = null;
+            stack = [];
+            const title = heading[2].trim();
+            if (heading[1] === '#' && draft.meta?.title === undefined && draft.items.length === 0 && !section) {
+                draft.meta = { ...draft.meta, title };
+            }
+            else if (heading[1] === '##') {
+                section = { type: 'section', title, items: [] };
+                draft.items.push(section);
+            }
+            else {
+                return invalid('only one "#" title before everything else and "##" sections are headings in a plan');
+            }
+            continue;
+        }
+        if (/^(-{3,}|\*{3,}|_{3,})$/.test(content) && indent < 4) {
+            section = null;
+            stack = [];
+            text = null;
+            continue;
+        }
+        const item = /^[-*+]\s+(?:\[(.)\]\s+)?(.*)$/.exec(content);
+        if (item) {
+            text = null;
+            const marker = item[1];
+            if (marker !== undefined && !(marker in MARKER_STATES)) {
+                return invalid(`"[${marker}]" is not a step marker`);
+            }
+            const title = item[2].trim();
+            if (title === '') {
+                return invalid('a step needs a title');
+            }
+            const state = marker === undefined ? undefined : MARKER_STATES[marker];
+            const step = { type: 'step', title, ...(state ? { state } : {}) };
+            popTo(indent);
+            const parent = stack[stack.length - 1]?.step;
+            if (parent) {
+                parent.steps ??= [];
+                parent.steps.push(step);
+            }
+            else {
+                container().push(step);
+            }
+            stack.push({ indent, step });
+            continue;
+        }
+        const quote = /^>\s?(.*)$/.exec(content);
+        popTo(indent);
+        const owner = stack[stack.length - 1]?.step;
+        if (owner && indent > 0) {
+            if (quote) {
+                owner.note = appendLine(owner.note, quote[1]);
+            }
+            else {
+                owner.description = appendLine(owner.description, plain, blanksBefore(owner));
+            }
+            continue;
+        }
+        stack = [];
+        if (quote) {
+            const titled = /^\*\*((?:\\.|[^\\])+?)\*\*\s*(.*)$/.exec(quote[1].trim());
+            if (titled) {
+                const title = titled[1].trim().replace(/\\([\\*])/g, '$1');
+                text = { type: 'text', title, ...(titled[2] ? { description: titled[2] } : {}) };
+                container().push(text);
+            }
+            else if (text) {
+                text.description = appendLine(text.description, dropEscape(quote[1]));
+            }
+            else {
+                return invalid('a text block starts with a bold title: > **Title** description');
+            }
+            continue;
+        }
+        if (!section && draft.items.length === 0) {
+            draft.meta = { ...draft.meta, summary: appendLine(draft.meta?.summary, plain, blanksBefore(draft)) };
+            continue;
+        }
+        if (section && section.items.length === 0) {
+            section.description = appendLine(section.description, plain, blanksBefore(section));
+            continue;
+        }
+        return invalid('this line is not a step, a section, a text block or a description');
+    }
+    // A parent's state follows from its children, so a marker on it says nothing.
+    const clearParents = (items) => {
+        for (const entry of items) {
+            if (entry.type === 'section') {
+                clearParents(entry.items);
+            }
+            else if (entry.type === 'step' && entry.steps) {
+                delete entry.state;
+                clearParents(entry.steps);
+            }
+        }
+    };
+    clearParents(draft.items);
+    return { ok: true, draft };
+}

package/dist/permissions.d.ts

@@ -0,0 +1,7 @@
+import type { Plan, PlanActor, PlanOp } from './protocol.ts';
+import { type PlanRefusal } from './tree.ts';
+export type PlanVerdict = {
+    ok: true;
+} | PlanRefusal;
+export declare function canApply(op: PlanOp, actor: PlanActor, plan: Plan): PlanVerdict;
+export declare function canDeletePlan(plan: Plan, actor: PlanActor): PlanVerdict;