@adecore/plan 0.38.0 → 0.40.0

package/dist/apply.js

@@ -44,14 +44,13 @@ function setState(step, state, actor, now) {
     if (actor === 'agent' && step.by === 'person' && step.state === state) {
         return;
     }
+    step.state = state;
     // 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;
 }
@@ -161,7 +160,7 @@ function applyOne(plan, op, options, mint, dropped) {
             setNote(stepAt(op.id), op.text);
             return null;
         case 'unlock': {
-            const roots = op.ids === 'all' ? plan.items : op.ids.map((id) => stepAt(id));
+            const roots = op.ids === 'all' ? plan.items : op.ids.map(stepAt);
             for (const step of allSteps(roots)) {
                 if (effectiveChecks(plan, step) === 'agent') {
                     step.unlocked = true;

package/dist/markdown.js

@@ -144,7 +144,7 @@ export function parsePlanMarkdown(markdown) {
     let blanks = 0;
     const container = () => (section ? section.items : draft.items);
     const popTo = (indent) => {
-        while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+        while ((stack.at(-1)?.indent ?? -1) >= indent) {
             stack.pop();
         }
     };
@@ -205,7 +205,7 @@ export function parsePlanMarkdown(markdown) {
             const state = marker === undefined ? undefined : MARKER_STATES[marker];
             const step = { type: 'step', title, ...(state ? { state } : {}) };
             popTo(indent);
-            const parent = stack[stack.length - 1]?.step;
+            const parent = stack.at(-1)?.step;
             if (parent) {
                 parent.steps ??= [];
                 parent.steps.push(step);
@@ -218,7 +218,7 @@ export function parsePlanMarkdown(markdown) {
         }
         const quote = /^>\s?(.*)$/.exec(content);
         popTo(indent);
-        const owner = stack[stack.length - 1]?.step;
+        const owner = stack.at(-1)?.step;
         if (owner && indent > 0) {
             if (quote) {
                 owner.note = appendLine(owner.note, quote[1]);

package/dist/text.js

@@ -29,16 +29,14 @@ function counter(progress) {
 export function progressText(plan) {
     const progress = planProgress(plan.items);
     const extra = (count, label) => (count > 0 ? [`${count} ${label}`] : []);
-    const warnings = progress.warning === 1 ? 'warning' : 'warnings';
+    const unfinished = [...extra(progress.failed, 'failed'), ...extra(progress.skipped, 'skipped'), ...extra(progress.blocked, 'blocked')];
     if (plan.meta.kind === 'test') {
         return [
             `${progress.finished} of ${progress.total} run`,
             `${progress.done} passed`,
-            ...extra(progress.warning, warnings),
+            ...extra(progress.warning, progress.warning === 1 ? 'warning' : 'warnings'),
             ...extra(progress.info, 'info'),
-            ...extra(progress.failed, 'failed'),
-            ...extra(progress.skipped, 'skipped'),
-            ...extra(progress.blocked, 'blocked')
+            ...unfinished
         ].join(', ');
     }
     // In a steps plan a warning or info is still done; the extras say which of the done steps to read.
@@ -46,9 +44,7 @@ export function progressText(plan) {
         `${progress.done + progress.warning + progress.info} of ${progress.total} done`,
         ...extra(progress.warning, `with ${progress.warning === 1 ? 'a warning' : 'warnings'}`),
         ...extra(progress.info, 'with info'),
-        ...extra(progress.failed, 'failed'),
-        ...extra(progress.skipped, 'skipped'),
-        ...extra(progress.blocked, 'blocked')
+        ...unfinished
     ].join(', ');
 }
 function sentences(parts) {
@@ -73,7 +69,7 @@ export function renderPlanText(plan, options = {}) {
     if (active.length > 0) {
         second.push(`Now: ${active.map((step) => `"${step.title}" [${step.id}]`).join(', ')}`);
     }
-    if (options.others && options.others.length > 0) {
+    if (options.others?.length) {
         const others = options.others.map((other) => `${other.id} "${other.meta.title}" (${other.meta.kind}, ${counter(planProgress(other.items))})`);
         second.push(`Also in this chat: ${others.join(', ')}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/plan",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Plan schemas, atomic tree operations, actor permissions and Markdown.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",
@@ -40,11 +40,11 @@
     "test": "bun test --conditions=source"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.2",
-    "@types/node": "^24.13.6",
+    "@types/bun": "^1.4.4",
+    "@types/node": "^24.19.2",
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   }
 }

package/src/apply.ts

@@ -47,6 +47,7 @@ const ID_BYTE_LIMIT = 256 - (256 % ID_ALPHABET.length);
 
 export function randomItemId(): string {
     let id = '';
+
     while (id.length < ID_LENGTH) {
         for (const byte of crypto.getRandomValues(new Uint8Array(ID_LENGTH))) {
             if (byte < ID_BYTE_LIMIT && id.length < ID_LENGTH) {
@@ -54,15 +55,19 @@ export function randomItemId(): string {
             }
         }
     }
+
     return id;
 }
 
 function issueMessage(error: z.ZodError): string {
     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}`;
 }
 
@@ -72,12 +77,15 @@ function idMinter(taken: Set<string>, mintId: () => string, minted: string[]) {
     return (): string | PlanRefusal => {
         for (let attempt = 0; attempt < MINT_ATTEMPTS; attempt++) {
             const id = mintId();
+
             if (!taken.has(id)) {
                 taken.add(id);
                 minted.push(id);
+
                 return id;
             }
         }
+
         return refuse('duplicate-id', `mintId gave no id the plan does not already have in ${MINT_ATTEMPTS} tries`);
     };
 }
@@ -87,14 +95,17 @@ function setState(step: PlanStep, state: PlanStepState, actor: PlanActor, now: s
     if (actor === 'agent' && step.by === 'person' && step.state === state) {
         return;
     }
+
+    step.state = state;
+
     // 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;
 }
@@ -116,16 +127,22 @@ function placeFor(
 ): { siblings: PlanItem[]; index: number; parent: PlanSection | PlanStep | null } | PlanRefusal {
     let parent: PlanSection | PlanStep | null = null;
     let siblings: PlanItem[] = plan.items;
+
     if (under !== undefined) {
         const location = locateItem(plan, under);
+
         if (!location) {
             return missingItem(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 {
@@ -134,25 +151,33 @@ function placeFor(
         }
     } else if (after !== undefined) {
         const location = locateItem(plan, after);
+
         if (!location) {
             return missingItem(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 };
 }
 
@@ -161,9 +186,11 @@ function becomeParent(parent: PlanSection | PlanStep | null, dropped: string[]):
     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;
@@ -179,107 +206,138 @@ function pruneEmptySteps(items: readonly PlanItem[]): void {
 
 function newItem(op: Extract<PlanOp, { op: 'add' }>, id: string): PlanItem {
     const base = { id, title: op.title, ...(op.description ? { description: op.description } : {}) };
+
     if (op.type === 'section') {
         return { type: 'section', ...base, items: [] };
     }
+
     if (op.type === 'text') {
         return { type: 'text', ...base };
     }
+
     return { type: 'step', ...base, ...(op.checks ? { checks: op.checks } : {}) };
 }
 
 function applyOne(plan: Plan, op: PlanOp, options: PlanApplyOptions, mint: () => string | PlanRefusal, dropped: string[]): PlanRefusal | null {
     const verdict = canApply(op, options.actor, plan);
+
     if (!verdict.ok) {
         return verdict;
     }
+
     const stepAt = (id: string): PlanStep => locateItem(plan, id)!.item as PlanStep;
+
     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));
+            const roots = op.ids === 'all' ? plan.items : op.ids.map(stepAt);
+
             for (const step of allSteps(roots)) {
                 if (effectiveChecks(plan, step) === 'agent') {
                     step.unlocked = true;
                 }
             }
+
             return null;
         }
         case 'add': {
             const id = op.id ?? mint();
+
             if (typeof id !== 'string') {
                 return id;
             }
+
             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;
             }
+
             place.siblings.splice(place.index, 0, newItem(op, id));
             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'] as const) {
                 if (op[key] === '') {
                     delete plan.meta[key];
@@ -287,9 +345,11 @@ function applyOne(plan: Plan, op: PlanOp, options: PlanApplyOptions, mint: () =>
                     plan.meta[key] = op[key];
                 }
             }
+
             if (op.checks !== undefined) {
                 plan.meta.checks = op.checks;
             }
+
             return null;
         }
     }
@@ -302,39 +362,50 @@ function applyOne(plan: Plan, op: PlanOp, options: PlanApplyOptions, mint: () =>
  */
 export function applyPlanOps(plan: Plan, ops: readonly PlanOp[], options: PlanApplyOptions): PlanApplied | PlanRefusal {
     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: string[] = [];
     const dropped: string[] = [];
     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: unknown): { ok: true; plan: Plan } | PlanRefusal {
     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 };
 }
 
@@ -386,6 +457,7 @@ export type PlanDraft = z.infer<typeof PlanDraftSchema>;
 
 export function parsePlanDraft(value: unknown): { ok: true; draft: PlanDraft } | PlanRefusal {
     const parsed = PlanDraftSchema.safeParse(value);
+
     return parsed.success ? { ok: true, draft: parsed.data } : refuse('plan-invalid', issueMessage(parsed.error));
 }
 
@@ -400,14 +472,18 @@ export interface PlanCreateOptions {
 /* 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: PlanDraft, options: PlanCreateOptions): PlanApplied | PlanRefusal {
     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: PlanMeta = {
         title,
         kind: options.meta?.kind ?? source.meta?.kind ?? 'steps',
@@ -415,66 +491,88 @@ export function createPlan(draft: PlanDraft, options: PlanCreateOptions): PlanAp
         ...(source.meta?.status ? { status: source.meta.status } : {}),
         checks: options.meta?.checks ?? source.meta?.checks ?? 'anyone'
     };
+
     const minted: string[] = [];
     const taken = new Set<string>();
+
     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);
     // Minted up front so a refusal stops here; the tree below takes them in the same order, parents first.
     const fresh: string[] = [];
+
     for (const item of allDraftItems(source.items)) {
         if (item.id === undefined) {
             const id = mint();
+
             if (typeof id !== 'string') {
                 return id;
             }
+
             fresh.push(id);
         }
     }
+
     const nextId = (): string => fresh.shift()!;
+
     const described = <T extends { description?: string }>(value: T): T => {
         if (value.description === '') {
             delete value.description;
         }
+
         return value;
     };
+
     const toStep = (step: PlanDraftStep): PlanStep => {
         const { steps, state, note, ...rest } = step;
         const result: PlanStep = described({ ...rest, id: step.id ?? nextId() });
+
         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: PlanDraftText): PlanText => described({ ...text, id: text.id ?? nextId() });
+
     const items = source.items.map((item): PlanItem => {
         if (item.type === 'section') {
             return described({ ...item, id: item.id ?? nextId(), items: item.items.map((child) => (child.type === 'text' ? toText(child) : toStep(child))) });
         }
+
         return item.type === 'text' ? toText(item) : toStep(item);
     });
+
     const plan: 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: [] };
 }
 

package/src/markdown.ts

@@ -51,37 +51,48 @@ function dropEscape(line: string): string {
  */
 export function planToMarkdown(plan: Plan): string {
     const blocks: string[] = [`# ${plan.meta.title}`];
+
     if (plan.meta.summary) {
         blocks.push(escapeText(plan.meta.summary));
     }
+
     const stepLines = (step: PlanStep, depth: number): string[] => {
         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: Extract<PlanItem, { type: 'text' }>): string => {
         const [first = '', ...rest] = item.description?.split('\n') ?? [];
+
         return [`> **${escapeBold(item.title)}**${first ? ` ${first}` : ''}`, ...rest.map((line) => `> ${escapeQuoted(line)}`)].join('\n');
     };
+
     const itemBlocks = (items: readonly PlanItem[]): string[] => {
         const result: string[] = [];
         let list: string[] = [];
+
         const flush = (): void => {
             if (list.length > 0) {
                 result.push(list.join('\n'));
                 list = [];
             }
         };
+
         for (const item of items) {
             if (item.type === 'step') {
                 list.push(...stepLines(item, 0));
@@ -90,11 +101,15 @@ export function planToMarkdown(plan: Plan): string {
                 result.push(textBlock(item));
             }
         }
+
         flush();
+
         return result;
     };
+
     let inSection = false;
     let loose: PlanItem[] = [];
+
     const flushLoose = (): void => {
         if (loose.length > 0) {
             // Only a rule brings the items after a section back to the top of the plan.
@@ -102,29 +117,38 @@ export function planToMarkdown(plan: Plan): string {
                 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: string): number {
     let width = 0;
+
     for (const char of line) {
         if (char === ' ') {
             width++;
@@ -134,6 +158,7 @@ function indentOf(line: string): number {
             break;
         }
     }
+
     return width;
 }
 
@@ -153,37 +178,50 @@ export function parsePlanMarkdown(markdown: string): { ok: true; draft: PlanDraf
     // The text the last line of prose went on and the blank lines since, so a paragraph break inside it stays.
     let continuing: object | null = null;
     let blanks = 0;
+
     const container = (): PlanDraftItem[] => (section ? section.items : draft.items) as PlanDraftItem[];
+
     const popTo = (indent: number): void => {
-        while (stack.length > 0 && stack[stack.length - 1]!.indent >= indent) {
+        while ((stack.at(-1)?.indent ?? -1) >= 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: string): PlanRefusal => 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: object): number => {
             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] === '##') {
@@ -192,52 +230,70 @@ export function parsePlanMarkdown(markdown: string): { ok: true; draft: PlanDraf
             } 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: PlanDraftStep = { type: 'step', title, ...(state ? { state } : {}) };
             popTo(indent);
-            const parent = stack[stack.length - 1]?.step;
+            const parent = stack.at(-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;
+        const owner = stack.at(-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] } : {}) };
@@ -247,18 +303,25 @@ export function parsePlanMarkdown(markdown: string): { ok: true; draft: PlanDraf
             } 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: readonly PlanDraftItem[]): void => {
         for (const entry of items) {
@@ -270,6 +333,8 @@ export function parsePlanMarkdown(markdown: string): { ok: true; draft: PlanDraf
             }
         }
     };
+
     clearParents(draft.items);
+
     return { ok: true, draft };
 }

package/src/permissions.ts

@@ -10,29 +10,37 @@ const AGENT_OPS: ReadonlySet<PlanOp['op']> = new Set(['set', 'note', 'add', 'edi
 
 function stepFor(plan: Plan, id: string, leaf: boolean): PlanStep | PlanRefusal {
     const location = locateItem(plan, id);
+
     if (!location) {
         return missingItem(id);
     }
+
     if (location.item.type !== 'step') {
         return refuse('plan-not-a-step', `"${id}" is a ${location.item.type}, not a step`);
     }
+
     if (leaf && isParentStep(location.item)) {
         return refuse('plan-parent-state', `The step "${id}" has sub-steps, so its state follows from them`);
     }
+
     return location.item;
 }
 
 function mayState(plan: Plan, step: PlanStep, state: PlanStepState, actor: PlanActor): PlanVerdict {
     const checks = effectiveChecks(plan, step);
+
     if (actor === 'person') {
         return checks === 'agent' ? refuse('step-locked', `Only the agent checks "${step.id}" until a person unlocks it`) : ALLOWED;
     }
+
     if (checks === 'person') {
         return refuse('person-only', `Only a person checks "${step.id}"`);
     }
+
     if (step.by === 'person' && step.state !== undefined && step.state !== state) {
         return refuse('set-by-person', `A person set "${step.id}" to ${step.state}; add a note or ask in the chat instead`);
     }
+
     return ALLOWED;
 }
 
@@ -42,15 +50,19 @@ function mayState(plan: Plan, step: PlanStep, state: PlanStepState, actor: PlanA
  */
 function mayHoldChildren(plan: Plan, under: string | undefined, after: string | undefined, added: readonly PlanChecks[]): PlanVerdict {
     const parent = under !== undefined ? locateItem(plan, under)?.item : after !== undefined ? locateItem(plan, after)?.parent : null;
+
     if (parent?.type !== 'step') {
         return ALLOWED;
     }
+
     if (!isParentStep(parent) && holdsPersonState(parent)) {
         return refuse('set-by-person', `A person set "${parent.id}" to ${parent.state}; a sub-step would take that state away`);
     }
+
     if (effectiveChecks(plan, parent) === 'person' && added.some((checks) => checks !== 'person')) {
         return refuse('person-only', `Only a person checks "${parent.id}", so a sub-step under it is one a person checks too`);
     }
+
     return ALLOWED;
 }
 
@@ -63,79 +75,102 @@ export function canApply(op: PlanOp, actor: PlanActor, plan: Plan): PlanVerdict
     if (!(actor === 'person' ? PERSON_OPS : AGENT_OPS).has(op.op)) {
         return refuse('op-not-allowed', actor === 'person' ? `A person cannot ${op.op} in a plan` : `An agent cannot ${op.op} a plan`);
     }
+
     switch (op.op) {
         case 'set': {
             if (op.next !== undefined && actor === 'person') {
                 return refuse('op-not-allowed', 'Only the agent moves on to a next step');
             }
+
             const targets: [string, PlanStepState][] = op.ids.map((id) => [id, op.state]);
+
             if (op.next !== undefined) {
                 targets.push([op.next, 'active']);
             }
+
             for (const [id, state] of targets) {
                 const step = stepFor(plan, id, true);
+
                 if ('ok' in step) {
                     return step;
                 }
+
                 const verdict = mayState(plan, step, state, actor);
+
                 if (!verdict.ok) {
                     return verdict;
                 }
             }
+
             return ALLOWED;
         }
         case 'note': {
             const step = stepFor(plan, op.id, false);
+
             return 'ok' in step ? step : ALLOWED;
         }
         case 'unlock': {
             if (op.ids === 'all') {
                 return ALLOWED;
             }
+
             for (const id of op.ids) {
                 const step = stepFor(plan, id, false);
+
                 if ('ok' in step) {
                     return step;
                 }
             }
+
             return ALLOWED;
         }
         case 'add':
             return mayHoldChildren(plan, op.under, op.after, op.type === 'step' ? [op.checks ?? plan.meta.checks] : []);
         case 'edit': {
             const location = locateItem(plan, op.id);
+
             if (!location) {
                 return missingItem(op.id);
             }
+
             const item = location.item;
+
             if (item.type !== 'step') {
                 return ALLOWED;
             }
+
             // A new title would make a person's check or stamp stand for something they never saw.
             if (op.title !== undefined && op.title !== item.title) {
                 if (holdsPersonState(item)) {
                     return refuse('set-by-person', `A person checked "${op.id}" or a step under it, so its title stays`);
                 }
+
                 if (effectiveChecks(plan, item) === 'person') {
                     return refuse('person-only', `Only a person checks "${op.id}", so its title stays`);
                 }
             }
+
             if (op.checks === undefined) {
                 return ALLOWED;
             }
+
             if (item.unlocked && op.checks !== 'anyone') {
                 return refuse('unlocked-by-person', `A person unlocked "${op.id}", so anyone checks it`);
             }
+
             if (effectiveChecks(plan, item) === 'person' && op.checks !== 'person') {
                 return refuse('person-only', `Only a person checks "${op.id}", and that stays so`);
             }
+
             return ALLOWED;
         }
         case 'move': {
             const location = locateItem(plan, op.id);
+
             if (!location) {
                 return missingItem(op.id);
             }
+
             return mayHoldChildren(
                 plan,
                 op.under,
@@ -145,22 +180,28 @@ export function canApply(op: PlanOp, actor: PlanActor, plan: Plan): PlanVerdict
         }
         case 'remove': {
             const location = locateItem(plan, op.id);
+
             if (!location) {
                 return missingItem(op.id);
             }
+
             if (holdsPersonState(location.item)) {
                 return refuse('set-by-person', `A person checked "${op.id}" or a step under it, so it stays`);
             }
+
             if (allSteps([location.item]).some((step) => effectiveChecks(plan, step) === 'person')) {
                 return refuse('person-only', `Only a person checks "${op.id}" or a step under it, so it stays`);
             }
+
             return ALLOWED;
         }
         case 'meta': {
             const inherits = allSteps(plan.items).some((step) => step.checks === undefined && !step.unlocked);
+
             if (op.checks !== undefined && op.checks !== 'person' && plan.meta.checks === 'person' && inherits) {
                 return refuse('person-only', 'Only a person checks the steps of this plan, and that stays so');
             }
+
             return ALLOWED;
         }
     }

package/src/text.ts

@@ -23,9 +23,11 @@ export interface PlanTextOptions {
 
 function localTime(at: string): string {
     const date = new Date(at);
+
     if (Number.isNaN(date.getTime())) {
         return '';
     }
+
     return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
 }
 
@@ -43,27 +45,27 @@ function counter(progress: PlanProgress): string {
 
 export function progressText(plan: Pick<Plan, 'meta' | 'items'>): string {
     const progress = planProgress(plan.items);
+
     const extra = (count: number, label: string): string[] => (count > 0 ? [`${count} ${label}`] : []);
-    const warnings = progress.warning === 1 ? 'warning' : 'warnings';
+
+    const unfinished = [...extra(progress.failed, 'failed'), ...extra(progress.skipped, 'skipped'), ...extra(progress.blocked, 'blocked')];
+
     if (plan.meta.kind === 'test') {
         return [
             `${progress.finished} of ${progress.total} run`,
             `${progress.done} passed`,
-            ...extra(progress.warning, warnings),
+            ...extra(progress.warning, progress.warning === 1 ? 'warning' : 'warnings'),
             ...extra(progress.info, 'info'),
-            ...extra(progress.failed, 'failed'),
-            ...extra(progress.skipped, 'skipped'),
-            ...extra(progress.blocked, 'blocked')
+            ...unfinished
         ].join(', ');
     }
+
     // In a steps plan a warning or info is still done; the extras say which of the done steps to read.
     return [
         `${progress.done + progress.warning + progress.info} of ${progress.total} done`,
         ...extra(progress.warning, `with ${progress.warning === 1 ? 'a warning' : 'warnings'}`),
         ...extra(progress.info, 'with info'),
-        ...extra(progress.failed, 'failed'),
-        ...extra(progress.skipped, 'skipped'),
-        ...extra(progress.blocked, 'blocked')
+        ...unfinished
     ].join(', ');
 }
 
@@ -80,52 +82,66 @@ export function renderPlanText(plan: Plan, options: PlanTextOptions = {}): strin
     const formatTime = options.formatTime ?? localTime;
     const lines = [`Plan "${plan.meta.title}" (${plan.id}, ${plan.meta.kind}, rev ${plan.rev}): ${progressText(plan)}`];
     const second: string[] = [];
+
     if (plan.meta.summary) {
         second.push(`Summary: ${oneLine(plan.meta.summary)}`);
     }
+
     if (plan.meta.status) {
         second.push(`Status: ${plan.meta.status}`);
     }
+
     const active = leafSteps(plan.items).filter((step) => step.state === 'active');
+
     if (active.length > 0) {
         second.push(`Now: ${active.map((step) => `"${step.title}" [${step.id}]`).join(', ')}`);
     }
-    if (options.others && options.others.length > 0) {
+
+    if (options.others?.length) {
         const others = options.others.map((other) => `${other.id} "${other.meta.title}" (${other.meta.kind}, ${counter(planProgress(other.items))})`);
         second.push(`Also in this chat: ${others.join(', ')}`);
     }
+
     if (second.length > 0) {
         lines.push(sentences(second));
     }
 
     const stepLine = (step: PlanStep, number: string, indent: string): void => {
         let line = `${indent}${PLAN_STATE_MARKERS[stepState(step)]} ${number} ${step.title} [${step.id}]`;
+
         if (isParentStep(step)) {
             line += ` ${counter(planProgress(step.steps!))}`;
         } else {
             const notes: string[] = [];
             const checks = effectiveChecks(plan, step);
+
             if (checks !== 'anyone') {
                 notes.push(`${checks}-only`);
             } else if (step.unlocked) {
                 notes.push('unlocked');
             }
+
             if (step.by === 'person' && step.state !== undefined) {
                 const time = step.at ? formatTime(step.at) : '';
                 notes.push(time ? `set by a person ${time}` : 'set by a person');
             }
+
             if (notes.length > 0) {
                 line += ` ${notes.join(', ')}`;
             }
         }
+
         if (step.note) {
             line += `: "${oneLine(step.note)}"`;
         }
+
         lines.push(line, ...descriptionLines(step.description, `${indent}  `));
         step.steps?.forEach((child, index) => stepLine(child, `${number}.${index + 1}`, `${indent}  `));
     };
+
     const itemLines = (items: readonly PlanItem[], indent: string): void => {
         let number = 0;
+
         for (const item of items) {
             if (item.type === 'text') {
                 lines.push(`${indent}${item.title} [${item.id}]${item.description ? `: ${oneLine(item.description)}` : ''}`);
@@ -137,6 +153,7 @@ export function renderPlanText(plan: Plan, options: PlanTextOptions = {}): strin
     };
 
     let loose: PlanItem[] = [];
+
     const flushLoose = (): void => {
         if (loose.length > 0) {
             lines.push('');
@@ -144,16 +161,21 @@ export function renderPlanText(plan: Plan, options: PlanTextOptions = {}): strin
             loose = [];
         }
     };
+
     for (const item of plan.items) {
         if (item.type !== 'section') {
             loose.push(item);
+
             continue;
         }
+
         flushLoose();
         const progress = planProgress(item.items);
         lines.push('', `## ${item.title} [${item.id}]${progress.total > 0 ? ` ${counter(progress)}` : ''}`, ...descriptionLines(item.description, '  '));
         itemLines(item.items, '  ');
     }
+
     flushLoose();
+
     return lines.join('\n');
 }

package/src/tree.ts

@@ -45,9 +45,11 @@ function childrenOf(item: PlanItem): PlanItem[] {
     if (item.type === 'section') {
         return item.items;
     }
+
     if (item.type === 'step') {
         return item.steps ?? [];
     }
+
     return [];
 }
 
@@ -56,16 +58,21 @@ export function locateItem(plan: Pick<Plan, 'items'>, id: string): PlanLocation
         for (let index = 0; index < siblings.length; index++) {
             const item = siblings[index]!;
             const itemDepth = item.type === 'step' ? depth + 1 : 0;
+
             if (item.id === id) {
                 return { item, siblings, index, parent, depth: itemDepth };
             }
+
             const found = search(childrenOf(item), item.type === 'text' ? null : item, item.type === 'step' ? itemDepth : depth);
+
             if (found) {
                 return found;
             }
         }
+
         return null;
     };
+
     return search(plan.items, null, 0);
 }
 
@@ -100,16 +107,20 @@ export function deriveState(states: readonly PlanStepState[]): PlanStepState {
     if (states.includes('failed')) {
         return 'failed';
     }
+
     if (states.includes('blocked')) {
         return 'blocked';
     }
+
     if (states.every(isFinishedOutcome)) {
         return states.includes('warning') ? 'warning' : 'done';
     }
+
     // A skipped step did not run, so next to open steps alone it moves nothing forward.
     if (states.some((state) => state === 'active' || state === 'done' || state === 'warning' || state === 'info')) {
         return 'active';
     }
+
     return 'open';
 }
 
@@ -135,14 +146,17 @@ export interface PlanProgress {
 
 export function planProgress(items: readonly PlanItem[]): PlanProgress {
     const progress: PlanProgress = { total: 0, open: 0, active: 0, done: 0, failed: 0, skipped: 0, blocked: 0, warning: 0, info: 0, finished: 0 };
+
     for (const step of leafSteps(items)) {
         const state = step.state ?? 'open';
         progress.total++;
         progress[state]++;
+
         if (state === 'failed' || isFinishedOutcome(state)) {
             progress.finished++;
         }
     }
+
     return progress;
 }
 
@@ -169,42 +183,56 @@ export function holdsPersonState(item: PlanItem): boolean {
 export function structureProblem(plan: Pick<Plan, 'items'>): PlanRefusal | null {
     const ids = new Set<string>();
     let count = 0;
+
     const walk = (items: readonly PlanItem[], depth: number, inside: 'top' | 'section' | 'step'): PlanRefusal | null => {
         for (const item of items) {
             count++;
+
             if (count > PLAN_LIMITS.items) {
                 return refuse('plan-too-large', `A plan holds at most ${PLAN_LIMITS.items} items`);
             }
+
             if (ids.has(item.id)) {
                 return refuse('duplicate-id', `Two items share the id "${item.id}"`);
             }
+
             ids.add(item.id);
+
             if (item.type === 'section' && inside !== 'top') {
                 return refuse('plan-bad-position', `The section "${item.id}" is not at the top of the plan; sections do not nest`);
             }
+
             if (item.type === 'text' && inside === 'step') {
                 return refuse('plan-bad-position', `The text block "${item.id}" is under a step; a step only holds steps`);
             }
+
             if (item.type === 'step') {
                 if (depth + 1 > PLAN_LIMITS.depth) {
                     return refuse('plan-too-deep', `The step "${item.id}" is ${depth + 1} levels deep; steps go at most ${PLAN_LIMITS.depth} levels deep`);
                 }
+
                 if (isParentStep(item) && (item.state !== undefined || item.by !== undefined || item.at !== undefined)) {
                     return refuse('plan-parent-state', `The step "${item.id}" has sub-steps, so its state follows from them`);
                 }
+
                 const problem = walk(item.steps ?? [], depth + 1, 'step');
+
                 if (problem) {
                     return problem;
                 }
             }
+
             if (item.type === 'section') {
                 const problem = walk(item.items, depth, 'section');
+
                 if (problem) {
                     return problem;
                 }
             }
         }
+
         return null;
     };
+
     return walk(plan.items, 0, 'top');
 }