@owlmeans/server-planning 0.1.18-rc.0

package/tests/context.ts

@@ -0,0 +1,198 @@
+import { AppType, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import {
+  CodeScope, CodeStyle, IntrinsicStatus, SpecificationFormat, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type {
+  AnyTypeSchema, PlanningFacade, PlanningPlugin, PlanningService, StatusFlowSchema, TransitionReceipt,
+  WithPlanningService, Workcard,
+} from '@owlmeans/planning'
+import { appendPlanningService } from '../src/service.js'
+import { makeMemoryPlanningStore } from '../src/store/memory.js'
+import type { MemoryPlanningStore, MemoryPlanningStoreOptions } from '../src/store/types.js'
+import type { PlanningServiceOptions } from '../src/types.js'
+
+export const ENTITY = 'entity-1'
+export const OTHER_ENTITY = 'entity-2'
+export const PROFILE = 'profile-1'
+
+export const PROJECT = 'test:project'
+export const TASK = 'test:task'
+export const BUG = 'test:bug'
+export const NOTE = 'test:note'
+export const SPEC = 'test:spec'
+
+const flows: StatusFlowSchema[] = [
+  {
+    id: 'test:task',
+    version: 1,
+    statuses: [
+      { key: 'todo', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'doing', intrinsic: IntrinsicStatus.InProgress },
+      { key: 'done', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    ],
+    transitions: [
+      { name: 'start', from: ['todo'], to: 'doing', explicit: true },
+      { name: 'finish', from: ['doing'], to: 'done', explicit: true },
+      { name: 'reopen', from: '*', to: 'todo' },
+    ],
+  },
+  {
+    id: 'test:review',
+    version: 1,
+    statuses: [
+      { key: 'waiting', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'approved', intrinsic: IntrinsicStatus.Closed },
+    ],
+    transitions: [{ name: 'approve', from: ['waiting'], to: 'approved' }],
+  },
+  {
+    id: 'test:project',
+    version: 1,
+    statuses: [
+      { key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'active', intrinsic: IntrinsicStatus.InProgress },
+    ],
+    transitions: [{ name: 'activate', from: ['open'], to: 'active' }],
+  },
+  {
+    id: 'test:doc',
+    version: 1,
+    statuses: [{ key: 'draft', intrinsic: IntrinsicStatus.Planned, initial: true }],
+    transitions: [],
+  },
+]
+
+const types: AnyTypeSchema[] = [
+  {
+    type: PROJECT,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: ['test:project'],
+    cardTypes: [TASK, BUG],
+    projectTypes: [PROJECT],
+    specifications: [
+      { category: 'brief', format: SpecificationFormat.Markdown },
+      {
+        category: 'plan',
+        format: SpecificationFormat.Json,
+        revisioned: true,
+        keepRevisions: 3,
+        schema: { type: 'object', required: ['steps'], properties: { steps: { type: 'array' } } },
+      },
+    ],
+    code: { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity, mutable: true },
+  },
+  {
+    type: TASK,
+    kind: WorkcardKind.Card,
+    version: 1,
+    fields: {
+      type: 'object',
+      properties: { area: { type: 'string', enum: ['guest', 'user'] }, primary: { type: 'boolean' } },
+      additionalProperties: false,
+    },
+    flows: ['test:task', 'test:review'],
+    specifications: [{ category: 'design', format: SpecificationFormat.Json, revisioned: true }],
+    relationships: [{ name: 'follows', to: [TASK], single: true }, { name: 'blocks' }],
+    labels: ['urgent', 'later'],
+    code: { prefix: 'T-', style: CodeStyle.Random, length: 5, uppercase: true, uniqueWithin: CodeScope.Parent },
+  },
+  {
+    type: BUG,
+    kind: WorkcardKind.Card,
+    version: 1,
+    fields: { type: 'object' },
+    flows: ['test:task'],
+    specifications: [],
+  },
+  {
+    type: NOTE,
+    kind: WorkcardKind.Card,
+    version: 1,
+    fields: { type: 'object' },
+    flows: ['test:task'],
+    specifications: [],
+  },
+  {
+    type: SPEC,
+    kind: WorkcardKind.Specification,
+    version: 1,
+    fields: { type: 'object' },
+    flows: ['test:doc'],
+    specifications: [],
+  },
+]
+
+/** The fixture types and flows, as a plugin contributes them. */
+export const fixturePlugin: PlanningPlugin = { name: 'fixtures', order: 0, schemas: { types, flows } }
+
+export interface TestPlanning {
+  context: BasicContext<BasicConfig> & WithPlanningService
+  service: PlanningService
+  store: MemoryPlanningStore
+  facade: (entityId?: string) => PlanningFacade
+}
+
+/**
+ * One real context the way a backend wires planning: a memory store, the fixture plugin, and a
+ * clock that never repeats a timestamp, so ordering by `at` is deterministic.
+ */
+export const makeTestPlanning = async (
+  options: PlanningServiceOptions = {}, storeOptions: MemoryPlanningStoreOptions = {}
+): Promise<TestPlanning> => {
+  let tick = Date.parse('2026-01-01T00:00:00.000Z')
+  const now = () => new Date(tick++).toISOString()
+  const store = makeMemoryPlanningStore({ now, ...storeOptions })
+
+  const cfg: BasicConfig = { ready: false, service: 'server-planning-tests', type: AppType.Backend, services: {} }
+  const context = appendPlanningService(makeBasicContext(cfg), {
+    now,
+    store,
+    ...options,
+    plugins: [fixturePlugin, ...(options.plugins ?? [])],
+  })
+  context.configure()
+  await context.init()
+
+  const service = context.planning()
+
+  return {
+    context,
+    service,
+    store,
+    facade: (entityId = ENTITY) => service.for({ entityId, profileId: PROFILE, channel: 'test' }),
+  }
+}
+
+export const createProject = async (
+  facade: PlanningFacade, title: string = 'Test Project', extra: Record<string, unknown> = {}
+): Promise<Workcard> => (await facade.execute({
+  card: { kind: WorkcardKind.Project, type: PROJECT, title, ...extra },
+  action: TransitionAction.Create,
+}, { wait: true })).card!
+
+export const createTask = async (
+  facade: PlanningFacade, project: string, title: string = 'A task', extra: Record<string, unknown> = {}
+): Promise<TransitionReceipt> => await facade.execute({
+  card: { kind: WorkcardKind.Card, type: TASK, parent: project, title, ...extra },
+  action: TransitionAction.Create,
+}, { wait: true })
+
+/** A protocol-bound handler run with the smallest binding context the transport needs. */
+export const invoke = async (handler: any, context: unknown, req: Record<string, unknown>): Promise<any> => {
+  const res: any = { resolve: (value: unknown) => { res.value = value }, reject: (e: Error) => { res.error = e } }
+  await handler.bind({ ref: { ctx: context } })({ headers: {}, params: {}, query: {}, body: {}, ...req }, res)
+  if (res.error != null) {
+    throw res.error
+  }
+  return res.value
+}
+
+/** An authenticated request of one organization. */
+export const session = (entityId: string = ENTITY, patch: Record<string, unknown> = {}): Record<string, unknown> => ({
+  entity: { id: entityId, slug: entityId, iamKey: entityId },
+  auth: { type: 'test', userId: 'user-1', profileId: PROFILE, entitySlug: entityId, scopes: ['*'] },
+  ...patch,
+})

package/tests/entrypoints.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test'
+import { protocols } from '@owlmeans/entrypoint'
+import { CommitState, makePlanningProtocols, TransitionAction, WorkcardKind, WorkcardNotFound } from '@owlmeans/planning'
+import { executePlanning, getCard, getCommit, listCards } from '../src/actions/index.js'
+import { servePlanningEntrypoints } from '../src/helper.js'
+import {
+  createProject, createTask, invoke, makeTestPlanning, OTHER_ENTITY, PROFILE, PROJECT, session, TASK,
+} from './context.js'
+
+const tree = makePlanningProtocols({ base: { alias: 'test:planning' }, guards: 'test-guard' })
+
+describe('@owlmeans/server-planning — entrypoints', () => {
+  test('one binding per protocol of the tree', () => {
+    const declared = protocols(tree as never)
+    const bindings = servePlanningEntrypoints(tree)
+
+    expect(bindings.length).toBe(declared.length)
+    expect(new Set(bindings.map(binding => binding.alias))).toEqual(new Set(declared.map(protocol => protocol.alias)))
+  })
+
+  test('execute takes the actor and createdBy from the request, never from the body', async () => {
+    const { context } = await makeTestPlanning()
+    const execute = executePlanning(tree.execute, { scope: () => ({ channel: 'web' }) })
+
+    const view = await invoke(execute, context, {
+      ...session(),
+      body: {
+        card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Wire', createdBy: 'intruder' },
+        action: TransitionAction.Create,
+        actor: { profileId: 'intruder', channel: 'forged', runId: 'forged' },
+        wait: true,
+      },
+    })
+
+    expect(view.transition.actor).toEqual({ profileId: PROFILE, userId: 'user-1', channel: 'web' })
+    expect(view.card.createdBy).toBe(PROFILE)
+  })
+
+  test('another entity\'s card answers WorkcardNotFound — to a read and to a write', async () => {
+    const { context, facade } = await makeTestPlanning()
+    const project = await createProject(facade())
+    const task = (await createTask(facade(), project.id!, 'Mine', { labels: ['urgent'] })).card!
+
+    await expect(invoke(getCard(tree.card.get), context, { ...session(OTHER_ENTITY), params: { id: task.id } }))
+      .rejects.toBeInstanceOf(WorkcardNotFound)
+    await expect(invoke(executePlanning(tree.execute), context, {
+      ...session(OTHER_ENTITY), body: { card: task.id, action: TransitionAction.Update, changes: { title: 'Theirs' } },
+    })).rejects.toBeInstanceOf(WorkcardNotFound)
+
+    const listed = await invoke(listCards(tree.card.list), context, { ...session(), query: { type: TASK, labels: 'urgent,later' } })
+    expect(listed.items.map((card: { id: string }) => card.id)).toEqual([task.id])
+    expect((await invoke(listCards(tree.card.list), context, { ...session(OTHER_ENTITY), query: { type: TASK } })).total).toBe(0)
+  })
+
+  test('commit.get holds until the commit lands, and never past maxPoll', async () => {
+    const { context, facade, store } = await makeTestPlanning({}, { sync: false })
+    const receipt = await facade().execute({ card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Polled' }, action: TransitionAction.Create })
+    const request = { ...session(), params: { transition: receipt.transition.id }, query: { wait: 3600 } }
+
+    const clamped = Date.now()
+    const pending = await invoke(getCommit(tree.commit.get, { maxPoll: 0.05 }), context, request)
+    expect(pending.state).toBe(CommitState.Pending)
+    expect(Date.now() - clamped).toBeLessThan(1000)
+
+    const held = invoke(getCommit(tree.commit.get), context, request)
+    await new Promise(resolve => setTimeout(resolve, 20))
+    await store.flush()
+    const landed = await held
+    expect(landed.state).toBe(CommitState.Committed)
+    expect(landed.card.title).toBe('Polled')
+  })
+})

package/tests/executor.spec.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from 'bun:test'
+import { CommitState, TransitionAction, WorkcardConflict, WorkcardKind } from '@owlmeans/planning'
+import { createProject, createTask, ENTITY, makeTestPlanning, PROFILE, TASK } from './context.js'
+
+describe('@owlmeans/server-planning — the executor', () => {
+  test('a create mints the id, the code and seq 1, and answers a committed receipt', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+
+    const receipt = await createTask(planning, project.id!)
+
+    expect(project.code).toBe('test-project')
+    expect(receipt.transition.seq).toBe(1)
+    expect(receipt.transition.commit.state).toBe(CommitState.Committed)
+    expect(receipt.transition.project).toBe(project.id)
+    expect(receipt.transition.actor).toEqual({ profileId: PROFILE, channel: 'test' })
+    expect(receipt.card!.id).toBe(receipt.transition.card)
+    expect(receipt.card!.code).toMatch(/^T-[0-9A-Z]{5}$/)
+    expect(receipt.card!.flows).toEqual({ 'test:task': 'todo', 'test:review': 'waiting' })
+    expect(receipt.card!.entityId).toBe(ENTITY)
+  })
+
+  test('the same idempotency key appends once and answers the first receipt', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const exec = {
+      card: { kind: WorkcardKind.Card, type: TASK, parent: project.id!, title: 'Once' },
+      action: TransitionAction.Create,
+      key: 'import:1',
+    }
+
+    const first = await planning.execute(exec, { wait: true })
+    const second = await planning.execute(exec, { wait: true })
+
+    expect(second.transition.id).toBe(first.transition.id!)
+    expect((await planning.cards.list({ parent: project.id, type: TASK })).total).toBe(1)
+  })
+
+  test('a stale expectSeq is a WorkcardConflict and appends nothing', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+
+    await planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { title: 'Renamed' }, expectSeq: 1 }, { wait: true })
+
+    await expect(planning.execute({
+      card: task.id!, action: TransitionAction.Update, changes: { title: 'Again' }, expectSeq: 1,
+    })).rejects.toBeInstanceOf(WorkcardConflict)
+    expect((await planning.transitions.list({ card: task.id })).total).toBe(2)
+    expect((await planning.cards.get(task.id!)).title).toBe('Renamed')
+  })
+
+  test('an update with the values the card already holds appends nothing', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!, 'Same', { fields: { area: 'user' } })).card!
+
+    const receipt = await planning.execute({
+      card: task.id!, action: TransitionAction.Update, changes: { title: 'Same', fields: { area: 'user' } },
+    }, { wait: true })
+
+    expect(receipt.transition.seq).toBe(1)
+    expect((await planning.transitions.list({ card: task.id })).total).toBe(1)
+  })
+})

package/tests/memory-store.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from 'bun:test'
+import { CommitState, IntrinsicStatus, SpecificationFormat, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { CommitEvent } from '@owlmeans/planning'
+import { createProject, createTask, ENTITY, makeTestPlanning, OTHER_ENTITY, SPEC } from './context.js'
+
+describe('@owlmeans/server-planning — the memory store', () => {
+  test('folds in seq order and publishes one commit per transition', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const events: CommitEvent[] = []
+    store.commits.subscribe(event => { events.push(event) })
+
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+    await planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { title: 'Renamed' } })
+    await planning.execute({ card: task.id!, action: TransitionAction.Transit, transition: 'start' })
+
+    const card = await planning.cards.get(task.id!)
+    expect(card.seq).toBe(3)
+    expect(card.head).toBe(3)
+    expect(card.title).toBe('Renamed')
+    expect(card.status).toBe('doing')
+    expect(card.intrinsic).toBe(IntrinsicStatus.InProgress)
+    expect(events.filter(event => event.card === task.id).map(event => [event.seq, event.state]))
+      .toEqual([[1, CommitState.Committed], [2, CommitState.Committed], [3, CommitState.Committed]])
+  })
+
+  test('deleting a project purges its cards, specifications, links and log — a sibling survives', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const doomed = await createProject(planning, 'Doomed')
+    const kept = await createProject(planning, 'Kept')
+    const first = (await createTask(planning, doomed.id!, 'First')).card!
+    const second = (await createTask(planning, doomed.id!, 'Second', {})).card!
+    await planning.execute({ card: second.id!, action: TransitionAction.Link, link: { type: 'follows', to: first.id! } }, { wait: true })
+    const spec = (await planning.execute({
+      card: { kind: WorkcardKind.Specification, type: SPEC, parent: first.id!, title: 'design', category: 'design', format: SpecificationFormat.Json, body: '{}' },
+      action: TransitionAction.Create,
+    }, { wait: true })).card!
+    const survivor = (await createTask(planning, kept.id!, 'Survivor')).card!
+
+    const deleted = await planning.execute({ card: doomed.id!, action: TransitionAction.Delete }, { wait: true })
+
+    for (const id of [doomed.id!, first.id!, second.id!, spec.id!]) {
+      expect(await planning.cards.load(id)).toBeNull()
+    }
+    expect((await planning.relationships.list({ from: second.id })).total).toBe(0)
+    expect((await planning.transitions.list({ project: doomed.id })).total).toBe(0)
+    expect((await planning.commits.status(deleted.transition.id!)).state).toBe(CommitState.Committed)
+    expect(await planning.cards.load(survivor.id!)).not.toBeNull()
+    // The kept project, its task and their two create transitions.
+    expect(await store.cards.purge(kept.id!, ENTITY)).toBe(4)
+  })
+
+  test('byKey answers the first transition under that key, within its entity only', async () => {
+    const { facade, store } = await makeTestPlanning()
+    const planning = facade()
+    const receipt = await planning.execute({
+      card: { kind: WorkcardKind.Project, type: 'test:project', title: 'Keyed' }, action: TransitionAction.Create, key: 'first',
+    })
+
+    expect((await store.transitions.byKey(ENTITY, 'first'))!.id).toBe(receipt.transition.id!)
+    expect(await store.transitions.byKey(OTHER_ENTITY, 'first')).toBeNull()
+  })
+
+  test('a list honours parents, labels, a flow status and a field', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning, 'Main')
+    const other = await createProject(planning, 'Other')
+    const urgent = (await createTask(planning, project.id!, 'Urgent', { labels: ['urgent'], fields: { area: 'guest' } })).card!
+    const shared = (await createTask(planning, project.id!, 'Shared', { labels: ['later'], parents: [other.id!], fields: { area: 'user' } })).card!
+    await planning.execute({ card: shared.id!, action: TransitionAction.Transit, flow: 'test:review', transition: 'approve' })
+
+    const ids = async (query: Parameters<typeof planning.cards.list>[0]) =>
+      (await planning.cards.list(query)).items.map(card => card.id)
+
+    expect(await ids({ labels: ['urgent'] })).toEqual([urgent.id])
+    expect(await ids({ within: other.id })).toEqual([shared.id])
+    expect(await ids({ flow: { id: 'test:review', status: 'approved' } })).toEqual([shared.id])
+    expect(await ids({ fields: { area: 'guest' } })).toEqual([urgent.id])
+    expect((await facade(OTHER_ENTITY).cards.list({ labels: ['urgent'] })).total).toBe(0)
+  })
+})

package/tests/plugins.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'bun:test'
+import { CommitState, PlanningRefused, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import { makeMemoryPlanningStore } from '../src/store/memory.js'
+import { BUG, createProject, createTask, ENTITY, makeTestPlanning, PROJECT, TASK } from './context.js'
+
+describe('@owlmeans/server-planning — plugins', () => {
+  test('before middlewares run in order, and a throw refuses with nothing appended', async () => {
+    const calls: string[] = []
+    const { facade, service } = await makeTestPlanning({
+      plugins: [
+        { name: 'second', order: 20, before: async () => { calls.push('second') } },
+        { name: 'first', order: 10, before: async exec => { calls.push('first'); return { ...exec, cause: 'first' } } },
+      ],
+    })
+    const planning = facade()
+
+    const project = await planning.execute({ card: { kind: WorkcardKind.Project, type: PROJECT, title: 'P' }, action: TransitionAction.Create }, { wait: true })
+    expect(calls).toEqual(['first', 'second'])
+    expect(project.transition.cause).toBe('first')
+
+    service.use({ name: 'refuser', order: 30, before: async () => { throw new Error('not today') } })
+    const refusal = await createTask(planning, project.card!.id!).catch(error => error)
+    expect(refusal).toBeInstanceOf(PlanningRefused)
+    expect(refusal.message).toContain('refuser:not today')
+    expect((await planning.cards.list({ parent: project.card!.id, type: TASK })).total).toBe(0)
+  })
+
+  test('the first plugin that mints a code wins', async () => {
+    const { facade } = await makeTestPlanning({
+      plugins: [
+        { name: 'late', order: 20, mintCode: async () => 'T-LATE' },
+        { name: 'early', order: 10, mintCode: async () => 'T-EARLY' },
+        { name: 'silent', order: 5, mintCode: async () => undefined },
+      ],
+    })
+    const planning = facade()
+    const project = await createProject(planning)
+
+    expect((await createTask(planning, project.id!)).card!.code).toBe('T-EARLY')
+  })
+
+  test('a plugin that owns a type receives its writes and answers its reads', async () => {
+    const bugs = makeMemoryPlanningStore()
+    const { facade, store } = await makeTestPlanning({ plugins: [{ name: 'bugs', owns: type => type === BUG, store: bugs }] })
+    const planning = facade()
+    const project = await createProject(planning)
+
+    const bug = (await planning.execute({
+      card: { kind: WorkcardKind.Card, type: BUG, parent: project.id!, title: 'Crash' }, action: TransitionAction.Create,
+    }, { wait: true })).card!
+
+    expect(await bugs.cards.get(bug.id!, ENTITY)).not.toBeNull()
+    expect(await store.cards.get(bug.id!, ENTITY)).toBeNull()
+    expect((await planning.cards.list({ type: BUG })).total).toBe(1)
+    expect((await planning.cards.load(bug.id!))!.title).toBe('Crash')
+    // A query naming no type is the default store's alone.
+    expect((await planning.cards.list({ parent: project.id })).total).toBe(0)
+  })
+
+  test('after hooks run once per committed transition, in the folding process, and never fail a write', async () => {
+    const seen: string[] = []
+    const { facade, store } = await makeTestPlanning({
+      plugins: [
+        { name: 'boom', order: 1, after: async () => { throw new Error('boom') } },
+        { name: 'counter', after: async (event, ctx) => { seen.push(`${event.card}:${event.state}:${ctx.transition?.actor.channel}`) } },
+      ],
+    }, { sync: false })
+    const planning = facade()
+    const errors = console.error
+    console.error = () => undefined
+    try {
+      const receipt = await planning.execute({ card: { kind: WorkcardKind.Project, type: PROJECT, title: 'Later' }, action: TransitionAction.Create })
+      expect(receipt.transition.commit.state).toBe(CommitState.Pending)
+      expect(seen).toEqual([])
+
+      await store.flush()
+      await store.flush()
+      await store.flush(receipt.transition.card)
+
+      expect(seen).toEqual([`${receipt.transition.card}:committed:test`])
+      expect((await receipt.committed({ timeout: 100 }))!.title).toBe('Later')
+    } finally {
+      console.error = errors
+    }
+  })
+})

package/tests/specifications.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  FieldsInvalid, SpecificationFormat, SpecificationRevisionConflict, SpecificationSlotUnknown, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type { Specification } from '@owlmeans/planning'
+import { createProject, makeTestPlanning, SPEC } from './context.js'
+
+describe('@owlmeans/server-planning — specifications', () => {
+  test('a revisioned slot written twice is revision 1 then 2 on one record', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await planning.model(await createProject(planning))
+
+    const first = (await project.write('plan', JSON.stringify({ steps: [1] }), { wait: true })).card as Specification
+    const second = (await (await project.reload()).write('plan', JSON.stringify({ steps: [1, 2] }), { wait: true })).card as Specification
+
+    expect(first.revision).toBe(1)
+    expect(second.id).toBe(first.id!)
+    expect(second.revision).toBe(2)
+    expect((await planning.specifications.list(project.id)).total).toBe(1)
+    expect((await planning.specifications.current(project.id, 'plan'))!.body).toBe(JSON.stringify({ steps: [1, 2] }))
+  })
+
+  test('revisions() replays every body from the log, newest first', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await planning.model(await createProject(planning))
+    const spec = (await project.write('plan', '{"steps":["a"]}', { wait: true })).card!
+    await (await project.reload()).write('plan', '{"steps":["a","b"]}', { wait: true })
+
+    const revisions = await planning.specifications.revisions(spec.id!)
+
+    expect(revisions.map(entry => [entry.revision, entry.body])).toEqual([[2, '{"steps":["a","b"]}'], [1, '{"steps":["a"]}']])
+    expect(revisions[0].by?.channel).toBe('test')
+  })
+
+  test('a second document for a slot that holds one is SpecificationRevisionConflict', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const create = (body: string) => planning.execute({
+      card: { kind: WorkcardKind.Specification, type: SPEC, parent: project.id!, title: 'Brief', category: 'brief', body },
+      action: TransitionAction.Create,
+    }, { wait: true })
+
+    await create('# one')
+
+    await expect(create('# two')).rejects.toBeInstanceOf(SpecificationRevisionConflict)
+    expect((await planning.specifications.current(project.id!, 'brief'))!.body).toBe('# one')
+  })
+
+  test('an undeclared slot and a body outside the slot schema are refused', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await planning.model(await createProject(planning))
+
+    await expect(project.write('roadmap', 'text')).rejects.toBeInstanceOf(SpecificationSlotUnknown)
+    await expect(project.write('plan', '{"steps":1}')).rejects.toBeInstanceOf(FieldsInvalid)
+    await expect(project.write('plan', 'not json', { format: SpecificationFormat.Json })).rejects.toBeInstanceOf(FieldsInvalid)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": [
+      "bun"
+    ],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": [
+    "./**/*",
+    "../src/**/*"
+  ]
+}

package/tests/validation.spec.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  CardTypeNotAllowed, FieldsInvalid, IllegalTransition, LabelNotAllowed, PlanningError, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import { createProject, createTask, makeTestPlanning, NOTE, TASK } from './context.js'
+
+describe('@owlmeans/server-planning — validation', () => {
+  test('a transition the flow does not offer from the current status is IllegalTransition', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+
+    await expect(planning.execute({ card: task.id!, action: TransitionAction.Transit, transition: 'finish' }))
+      .rejects.toBeInstanceOf(IllegalTransition)
+    await expect(planning.execute({ card: task.id!, action: TransitionAction.Transit, transition: 'approve' }))
+      .rejects.toBeInstanceOf(IllegalTransition)
+    expect((await planning.transitions.list({ card: task.id })).total).toBe(1)
+  })
+
+  test('fields outside the type schema are FieldsInvalid, labels outside the list LabelNotAllowed', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+
+    await expect(createTask(planning, project.id!, 'Bad', { fields: { area: 'moon' } })).rejects.toBeInstanceOf(FieldsInvalid)
+    await expect(createTask(planning, project.id!, 'Bad', { labels: ['someday'] })).rejects.toBeInstanceOf(LabelNotAllowed)
+
+    const task = (await createTask(planning, project.id!)).card!
+    await expect(planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { fields: { extra: 1 } } }))
+      .rejects.toBeInstanceOf(FieldsInvalid)
+    expect((await planning.cards.list({ parent: project.id })).total).toBe(1)
+  })
+
+  test('a card type the parent does not accept is CardTypeNotAllowed', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+
+    await expect(planning.execute({
+      card: { kind: WorkcardKind.Card, type: NOTE, parent: project.id!, title: 'Note' }, action: TransitionAction.Create,
+    })).rejects.toBeInstanceOf(CardTypeNotAllowed)
+    await expect(planning.execute({
+      card: { kind: WorkcardKind.Card, type: TASK, parent: task.id!, title: 'Sub' }, action: TransitionAction.Create,
+    })).rejects.toBeInstanceOf(CardTypeNotAllowed)
+  })
+
+  test('a status written by an update is refused as immutable', async () => {
+    const { facade } = await makeTestPlanning()
+    const planning = facade()
+    const project = await createProject(planning)
+    const task = (await createTask(planning, project.id!)).card!
+
+    const refusal = await planning.execute({ card: task.id!, action: TransitionAction.Update, changes: { status: 'done' } })
+      .catch(error => error)
+
+    expect(refusal).toBeInstanceOf(PlanningError)
+    expect(refusal.message).toContain('immutable:status')
+    expect((await planning.cards.get(task.id!)).status).toBe('todo')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
+}