@adecore/plan 0.0.1 → 0.17.0-beta.2

package/dist/protocol.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+// Depth and item count require the whole tree and are checked by validatePlan.
+export const PLAN_LIMITS = {
+    idLength: 64,
+    title: 200,
+    description: 1000,
+    note: 500,
+    status: 200,
+    depth: 5,
+    items: 300,
+    plansPerChat: 20
+};
+export const PlanItemIdSchema = z
+    .string()
+    .min(1)
+    .max(PLAN_LIMITS.idLength)
+    .regex(/^[a-z0-9-]+$/);
+export const PlanIdSchema = PlanItemIdSchema;
+// Persisted consumers validate the entire enum; new fields must remain optional.
+export const PlanStepStateSchema = z.enum(['open', 'active', 'done', 'failed', 'skipped', 'blocked', 'warning', 'info']);
+export const PlanChecksSchema = z.enum(['anyone', 'agent', 'person']);
+export const PlanActorSchema = z.enum(['person', 'agent']);
+export const PlanKindSchema = z.enum(['steps', 'test']);
+const TitleSchema = z.string().min(1).max(PLAN_LIMITS.title);
+const DescriptionSchema = z.string().max(PLAN_LIMITS.description);
+const NoteSchema = z.string().max(PLAN_LIMITS.note);
+export const PlanMetaSchema = z.object({
+    title: TitleSchema,
+    kind: PlanKindSchema,
+    summary: DescriptionSchema.optional(),
+    // One line under the title, for a plan that tracks progress.
+    status: z.string().max(PLAN_LIMITS.status).optional(),
+    // Who sets a step that names no `checks` of its own.
+    checks: PlanChecksSchema
+});
+export const PlanStepSchema = z.object({
+    type: z.literal('step'),
+    id: PlanItemIdSchema,
+    title: TitleSchema,
+    description: DescriptionSchema.optional(),
+    checks: PlanChecksSchema.optional(),
+    // Only on a step without sub-steps; a parent derives its state from its children.
+    state: PlanStepStateSchema.optional(),
+    // Who set the state last and when, filled by the host and never by an agent.
+    by: PlanActorSchema.optional(),
+    at: z.string().optional(),
+    note: NoteSchema.optional(),
+    // A person lifted the lock, so the step is `anyone` from then on and an agent cannot lock it again.
+    unlocked: z.boolean().optional(),
+    get steps() {
+        return z.array(PlanStepSchema).optional();
+    }
+});
+export const PlanTextSchema = z.object({
+    type: z.literal('text'),
+    id: PlanItemIdSchema,
+    title: TitleSchema,
+    description: DescriptionSchema.optional()
+});
+// Sections do not nest: they only stand at the top of a plan.
+export const PlanSectionSchema = z.object({
+    type: z.literal('section'),
+    id: PlanItemIdSchema,
+    title: TitleSchema,
+    description: DescriptionSchema.optional(),
+    items: z.array(z.discriminatedUnion('type', [PlanTextSchema, PlanStepSchema]))
+});
+export const PlanItemSchema = z.discriminatedUnion('type', [PlanSectionSchema, PlanTextSchema, PlanStepSchema]);
+export const PlanSchema = z.object({
+    id: PlanIdSchema,
+    // Goes up by one on every applied batch of operations.
+    rev: z.number().int().nonnegative(),
+    createdAt: z.string(),
+    meta: PlanMetaSchema,
+    items: z.array(PlanItemSchema)
+});
+/*
+ * Operations name items by id and apply to the latest rev, without a base rev: a person's click and
+ * an agent's update never conflict, and an operation whose id is gone is refused instead.
+ */
+export const PlanSetOpSchema = z.object({
+    op: z.literal('set'),
+    ids: z.array(PlanItemIdSchema).min(1),
+    state: PlanStepStateSchema,
+    note: NoteSchema.optional(),
+    // Agent only: the step that becomes active in the same rev, so the work moves on without a gap.
+    next: PlanItemIdSchema.optional()
+});
+// An empty text clears the note.
+export const PlanNoteOpSchema = z.object({
+    op: z.literal('note'),
+    id: PlanItemIdSchema,
+    text: NoteSchema
+});
+export const PlanUnlockOpSchema = z.object({
+    op: z.literal('unlock'),
+    ids: z.union([z.array(PlanItemIdSchema).min(1), z.literal('all')])
+});
+/* Without `under` and `after` an item goes last at the top; with only `after` it goes right after that item, beside it. */
+export const PlanAddOpSchema = z.object({
+    op: z.literal('add'),
+    type: z.enum(['section', 'text', 'step']),
+    // Minted by the host when absent.
+    id: PlanItemIdSchema.optional(),
+    title: TitleSchema,
+    description: DescriptionSchema.optional(),
+    checks: PlanChecksSchema.optional(),
+    under: PlanItemIdSchema.optional(),
+    after: PlanItemIdSchema.optional()
+});
+// An empty description removes it.
+export const PlanEditOpSchema = z.object({
+    op: z.literal('edit'),
+    id: PlanItemIdSchema,
+    title: TitleSchema.optional(),
+    description: DescriptionSchema.optional(),
+    checks: PlanChecksSchema.optional()
+});
+export const PlanMoveOpSchema = z.object({
+    op: z.literal('move'),
+    id: PlanItemIdSchema,
+    under: PlanItemIdSchema.optional(),
+    after: PlanItemIdSchema.optional()
+});
+export const PlanRemoveOpSchema = z.object({
+    op: z.literal('remove'),
+    id: PlanItemIdSchema
+});
+// An empty summary or status removes it.
+export const PlanMetaOpSchema = z.object({
+    op: z.literal('meta'),
+    title: TitleSchema.optional(),
+    summary: DescriptionSchema.optional(),
+    status: z.string().max(PLAN_LIMITS.status).optional(),
+    checks: PlanChecksSchema.optional()
+});
+// What a person may send: checking off, a note and lifting a lock. The structure is the agent's.
+export const PlanPersonOpSchema = z.discriminatedUnion('op', [PlanSetOpSchema, PlanNoteOpSchema, PlanUnlockOpSchema]);
+export const PlanOpSchema = z.discriminatedUnion('op', [
+    PlanSetOpSchema,
+    PlanNoteOpSchema,
+    PlanUnlockOpSchema,
+    PlanAddOpSchema,
+    PlanEditOpSchema,
+    PlanMoveOpSchema,
+    PlanRemoveOpSchema,
+    PlanMetaOpSchema
+]);

package/dist/text.d.ts

@@ -0,0 +1,9 @@
+import type { Plan, PlanStepState } from './protocol.ts';
+export declare const PLAN_STATE_MARKERS: Record<PlanStepState, string>;
+export declare const PLAN_LEGEND = "[ ] open, [~] active, [x] done, [!] failed, [-] skipped, [?] blocked, [w] warning, [i] info";
+export interface PlanTextOptions {
+    others?: readonly Plan[];
+    formatTime?: (at: string) => string;
+}
+export declare function progressText(plan: Pick<Plan, 'meta' | 'items'>): string;
+export declare function renderPlanText(plan: Plan, options?: PlanTextOptions): string;

package/dist/text.js

@@ -0,0 +1,143 @@
+import { effectiveChecks, isParentStep, leafSteps, planProgress, stepState } from './tree.js';
+export const PLAN_STATE_MARKERS = {
+    open: '[ ]',
+    active: '[~]',
+    done: '[x]',
+    failed: '[!]',
+    skipped: '[-]',
+    blocked: '[?]',
+    warning: '[w]',
+    info: '[i]'
+};
+export const PLAN_LEGEND = '[ ] open, [~] active, [x] done, [!] failed, [-] skipped, [?] blocked, [w] warning, [i] info';
+function localTime(at) {
+    const date = new Date(at);
+    if (Number.isNaN(date.getTime())) {
+        return '';
+    }
+    return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+}
+function oneLine(text) {
+    return text.replace(/\s*\n\s*/g, ' ');
+}
+function descriptionLines(description, indent) {
+    return description ? [`${indent}${oneLine(description)}`] : [];
+}
+function counter(progress) {
+    return `${progress.finished}/${progress.total}`;
+}
+export function progressText(plan) {
+    const progress = planProgress(plan.items);
+    const extra = (count, label) => (count > 0 ? [`${count} ${label}`] : []);
+    const warnings = progress.warning === 1 ? 'warning' : 'warnings';
+    if (plan.meta.kind === 'test') {
+        return [
+            `${progress.finished} of ${progress.total} run`,
+            `${progress.done} passed`,
+            ...extra(progress.warning, warnings),
+            ...extra(progress.info, 'info'),
+            ...extra(progress.failed, 'failed'),
+            ...extra(progress.skipped, 'skipped'),
+            ...extra(progress.blocked, 'blocked')
+        ].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')
+    ].join(', ');
+}
+function sentences(parts) {
+    return parts.map((part, index) => (index < parts.length - 1 && !/[.!?]$/.test(part) ? `${part}.` : part)).join(' ');
+}
+/*
+ * The compact text `plan read` prints for an agent: one line per item with its id in brackets, so
+ * the ids survive a compacted conversation, and a step's or a section's description on the line
+ * under it, the way the Markdown of a plan has it. The markers are `PLAN_LEGEND`.
+ */
+export function renderPlanText(plan, options = {}) {
+    const formatTime = options.formatTime ?? localTime;
+    const lines = [`Plan "${plan.meta.title}" (${plan.id}, ${plan.meta.kind}, rev ${plan.rev}): ${progressText(plan)}`];
+    const second = [];
+    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) {
+        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, number, indent) => {
+        let line = `${indent}${PLAN_STATE_MARKERS[stepState(step)]} ${number} ${step.title} [${step.id}]`;
+        if (isParentStep(step)) {
+            line += ` ${counter(planProgress(step.steps))}`;
+        }
+        else {
+            const notes = [];
+            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, indent) => {
+        let number = 0;
+        for (const item of items) {
+            if (item.type === 'text') {
+                lines.push(`${indent}${item.title} [${item.id}]${item.description ? `: ${oneLine(item.description)}` : ''}`);
+            }
+            else if (item.type === 'step') {
+                number++;
+                stepLine(item, String(number), indent);
+            }
+        }
+    };
+    let loose = [];
+    const flushLoose = () => {
+        if (loose.length > 0) {
+            lines.push('');
+            itemLines(loose, '');
+            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/dist/tree.d.ts

@@ -0,0 +1,41 @@
+import { type Plan, type PlanChecks, type PlanItem, type PlanSection, type PlanStep, type PlanStepState } from './protocol.ts';
+export type PlanRefusalCode = 'person-only' | 'set-by-person' | 'unlocked-by-person' | 'step-locked' | 'plan-missing-item' | 'plan-not-found' | 'op-not-allowed' | 'plan-not-a-step' | 'plan-parent-state' | 'plan-bad-position' | 'duplicate-id' | 'plan-too-deep' | 'plan-too-large' | 'plan-invalid' | 'too-many-plans';
+export interface PlanRefusal {
+    ok: false;
+    code: PlanRefusalCode;
+    message: string;
+}
+export declare function refuse(code: PlanRefusalCode, message: string): PlanRefusal;
+export interface PlanLocation {
+    item: PlanItem;
+    siblings: PlanItem[];
+    index: number;
+    parent: PlanSection | PlanStep | null;
+    depth: number;
+}
+export declare function locateItem(plan: Pick<Plan, 'items'>, id: string): PlanLocation | null;
+export declare function findItem(plan: Pick<Plan, 'items'>, id: string): PlanItem | null;
+export declare function allItems(items: readonly PlanItem[]): PlanItem[];
+export declare function allSteps(items: readonly PlanItem[]): PlanStep[];
+export declare function isParentStep(step: PlanStep): boolean;
+export declare function effectiveChecks(plan: Pick<Plan, 'meta'>, step: PlanStep): PlanChecks;
+export declare function isFinishedOutcome(state: PlanStepState): boolean;
+export declare function deriveState(states: readonly PlanStepState[]): PlanStepState;
+export declare function stepState(step: PlanStep): PlanStepState;
+export interface PlanProgress {
+    total: number;
+    open: number;
+    active: number;
+    done: number;
+    failed: number;
+    skipped: number;
+    blocked: number;
+    warning: number;
+    info: number;
+    finished: number;
+}
+export declare function planProgress(items: readonly PlanItem[]): PlanProgress;
+export declare function leafSteps(items: readonly PlanItem[]): PlanStep[];
+export declare function activeStepIds(plan: Pick<Plan, 'items'>): string[];
+export declare function holdsPersonState(item: PlanItem): boolean;
+export declare function structureProblem(plan: Pick<Plan, 'items'>): PlanRefusal | null;

package/dist/tree.js

@@ -0,0 +1,142 @@
+import { PLAN_LIMITS } from './protocol.js';
+export function refuse(code, message) {
+    return { ok: false, code, message };
+}
+function childrenOf(item) {
+    if (item.type === 'section') {
+        return item.items;
+    }
+    if (item.type === 'step') {
+        return item.steps ?? [];
+    }
+    return [];
+}
+export function locateItem(plan, id) {
+    const search = (siblings, parent, depth) => {
+        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);
+}
+export function findItem(plan, id) {
+    return locateItem(plan, id)?.item ?? null;
+}
+/* Every item in document order, parents before their children. */
+export function allItems(items) {
+    return items.flatMap((item) => [item, ...allItems(childrenOf(item))]);
+}
+export function allSteps(items) {
+    return allItems(items).filter((item) => item.type === 'step');
+}
+export function isParentStep(step) {
+    return (step.steps?.length ?? 0) > 0;
+}
+/* Unlocked wins over everything: a person lifted the lock and no one puts it back. */
+export function effectiveChecks(plan, step) {
+    return step.unlocked ? 'anyone' : (step.checks ?? plan.meta.checks);
+}
+export function isFinishedOutcome(state) {
+    return state === 'done' || state === 'skipped' || state === 'warning' || state === 'info';
+}
+/* A warning bubbles up so a parent does not look clean; info is only worth reading on the step itself. */
+export function deriveState(states) {
+    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';
+}
+/* A leaf's own state, or for a parent the state its children add up to. */
+export function stepState(step) {
+    return isParentStep(step) ? deriveState(step.steps.map(stepState)) : (step.state ?? 'open');
+}
+export function planProgress(items) {
+    const progress = { 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;
+}
+/*
+ * The steps that carry a state, in document order. A step with steps under it has no state of its
+ * own: it is a heading, and what it says about progress is whatever its leaves say.
+ */
+export function leafSteps(items) {
+    return allSteps(items).filter((step) => !isParentStep(step));
+}
+export function activeStepIds(plan) {
+    return leafSteps(plan.items)
+        .filter((step) => step.state === 'active')
+        .map((step) => step.id);
+}
+/* True when the item, or any step under it, carries a state a person set. */
+export function holdsPersonState(item) {
+    return allItems([item]).some((entry) => entry.type === 'step' && !isParentStep(entry) && entry.by === 'person' && entry.state !== undefined);
+}
+/* The rules of a plan the schema cannot say, because they need the whole tree. */
+export function structureProblem(plan) {
+    const ids = new Set();
+    let count = 0;
+    const walk = (items, depth, inside) => {
+        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');
+}

package/package.json

@@ -1,11 +1,49 @@
 {
   "name": "@adecore/plan",
-  "version": "0.0.1",
-  "description": "Placeholder for the first release.",
+  "version": "0.17.0-beta.2",
+  "description": "Plan schemas, atomic tree operations, actor permissions and Markdown.",
   "license": "FSL-1.1-MIT",
+  "author": "Bas Milius",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/basmilius/adecore.git",
     "directory": "packages/plan"
+  },
+  "bugs": {
+    "url": "https://github.com/basmilius/adecore/issues"
+  },
+  "homepage": "https://adecore.dev/plan/",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "source": "./src/protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    }
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test --conditions=source"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^24.13.6",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
   }
 }