@owlmeans/server-planning 0.1.18-rc.0

package/src/actions/links.ts

@@ -0,0 +1,14 @@
+import { handlers } from '@owlmeans/server-api'
+import { decodeRelationshipQuery } from '@owlmeans/planning'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { concealed, handlerFacade } from '../utils/index.js'
+
+export const listLinks = (
+  protocol: PlanningProtocols['link']['list'], opts?: PlanningHandlerOptions
+): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
+  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
+    const facade = await handlerFacade(ctx, req, opts)
+
+    return await facade.relationships.list(decodeRelationshipQuery(req.query))
+  }))

package/src/actions/schemas.ts

@@ -0,0 +1,15 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { planningServiceOf, scopeOf } from '../utils/index.js'
+
+/** The schema bundle the service holds — what a client loads to answer `can()` with no round trip. */
+export const listSchemas = (
+  protocol: PlanningProtocols['schema']['list'], opts?: PlanningHandlerOptions
+): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
+  handlers<Context>().request(protocol, async (req, ctx) => {
+    // Scoped like every other leaf: no organization, no bundle.
+    scopeOf(req)
+
+    return planningServiceOf(ctx, opts).schemas.bundle()
+  })

package/src/actions/specs.ts

@@ -0,0 +1,23 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { concealed, handlerFacade } from '../utils/index.js'
+
+type RequestHandler = ReturnType<ReturnType<typeof handlers<Context>>['request']>
+
+/** @throws {WorkcardNotFound} */
+export const getSpecification = (protocol: PlanningProtocols['spec']['get'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
+    const facade = await handlerFacade(ctx, req, opts)
+
+    return await facade.specifications.get(`${req.params.id}`)
+  }))
+
+/** A document's history, newest first, replayed from its log. */
+export const listSpecificationRevisions = (protocol: PlanningProtocols['spec']['revisions'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
+    const facade = await handlerFacade(ctx, req, opts)
+    const limit = req.query?.limit == null ? undefined : Number(req.query.limit)
+
+    return { items: await facade.specifications.revisions(`${req.params.id}`, Number.isFinite(limit) ? limit : undefined) }
+  }))

package/src/actions/transitions.ts

@@ -0,0 +1,14 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { concealed, handlerFacade } from '../utils/index.js'
+
+/** @throws {WorkcardNotFound} for an absent transition and for another entity's alike */
+export const getTransition = (
+  protocol: PlanningProtocols['transition']['get'], opts?: PlanningHandlerOptions
+): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
+  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
+    const facade = await handlerFacade(ctx, req, opts)
+
+    return await facade.transitions.get(`${req.params.transition}`)
+  }))

package/src/actions/watch.ts

@@ -0,0 +1,52 @@
+import { PLANNING_COMMIT_EVENT } from '@owlmeans/planning'
+import type { CommitEvent, CommitFeedQuery, PlanningProtocols } from '@owlmeans/planning'
+import { connection } from '@owlmeans/server-socket'
+import type { EventMessage } from '@owlmeans/socket'
+import { MessageType } from '@owlmeans/socket'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { handlerFacade } from '../utils/index.js'
+
+const text = (value: unknown): string | undefined =>
+  value == null || value === '' ? undefined : `${value}`
+
+/**
+ * The notify tool: push the caller's entity's commits down a socket as `planning-commit` frames.
+ *
+ * The subscription is filtered by the authenticated entity (never a query value) and optionally by
+ * `project`/`card`. A frame without `record` — what a cross-process bus delivers — gets the card as
+ * it reads now (`null` once deleted), so a subscriber never re-reads per frame.
+ */
+export const watchCommits = (
+  protocol: PlanningProtocols['commit']['events'], opts?: PlanningHandlerOptions
+): ReturnType<typeof connection> => connection<typeof protocol, Context>(protocol, async (conn, ctx, req) => {
+  const facade = await handlerFacade(ctx, req, opts)
+  const query = (req.query ?? {}) as CommitFeedQuery
+  const frame = opts?.event ?? PLANNING_COMMIT_EVENT
+  const filter = {
+    ...(text(query.project) != null ? { project: text(query.project) } : {}),
+    ...(text(query.card) != null ? { card: text(query.card) } : {}),
+  }
+
+  const unsubscribe = await facade.commits.subscribe(async (event: CommitEvent) => {
+    try {
+      const enriched = event.record !== undefined ? event : { ...event, record: await facade.cards.load(event.card) }
+      await conn.notify(frame, enriched)
+    } catch (e) {
+      console.error('Planning commit notify error:', e)
+    }
+  }, filter)
+
+  conn.listen(async message => {
+    if (typeof message !== 'object') {
+      return
+    }
+    const msg = message as EventMessage<void>
+    if (msg.type === MessageType.System && msg.event === 'close') {
+      try {
+        unsubscribe()
+      } catch (e) {
+        console.error('Planning commit unsubscribe error:', e)
+      }
+    }
+  })
+})

package/src/consts.ts

@@ -0,0 +1,22 @@
+import { PLANNING_SERVICE } from '@owlmeans/planning'
+
+/** The alias `appendPlanningService` registers the host under — the same one a client uses. */
+export const DEFAULT_ALIAS = PLANNING_SERVICE
+
+/** The alias a memory store answers `PlanningStore.alias` with. */
+export const MEMORY_STORE_ALIAS = 'planning-memory'
+
+/**
+ * How many settled commits a hub remembers after their transition row may be gone.
+ *
+ * A project `delete` purges the project's own log, so without this a waiter that polls a moment
+ * after the fold would be told the transition never existed.
+ */
+export const DEFAULT_COMMIT_MEMORY = 1000
+
+/**
+ * The poll ladder `wait` climbs after its first immediate poll, in milliseconds. The last step
+ * repeats. The subscription answers first whenever the fold publishes where the hub hears it; the
+ * ladder is what answers when it folded somewhere the hub does not.
+ */
+export const COMMIT_POLL_LADDER: readonly number[] = Object.freeze([250, 1000, 2000])

package/src/executor/changes.ts

@@ -0,0 +1,78 @@
+import { CommitState, computeChanges, isEmptyChange, TransitionAction } from '@owlmeans/planning'
+import type {
+  ChangeSet, PlanningSchemaRegistry, PlanningScope, RelationshipDraft, Transition, TransitionActor,
+  TransitionExecution, WorkcardDraft,
+} from '@owlmeans/planning'
+import type { Resolved } from './resolve.js'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+/**
+ * Step 9: the recorded `changes`/`unset`, and whether an update wrote nothing.
+ *
+ * @throws {IllegalTransition | PlanningError}
+ */
+export const changeSetOf = (
+  exec: TransitionExecution, resolved: Resolved, schemas: PlanningSchemaRegistry, at: string
+): { set: ChangeSet, empty: boolean } => {
+  const set = computeChanges(resolved.card, exec, resolved.type, schemas, at, { slot: resolved.slot })
+  const empty = exec.action === TransitionAction.Update && isEmptyChange(set)
+
+  return { set, empty }
+}
+
+/**
+ * Who wrote it — the SCOPE's identity, never the execution's.
+ *
+ * `profileId`, `userId`, `service` and `channel` come only from the scope (the server builds it
+ * from the authenticated request); the descriptive `agent`/`runId` an in-process caller passes on
+ * the execution are kept unless the scope's own actor names them.
+ */
+export const actorOf = (scope: PlanningScope, exec: TransitionExecution): TransitionActor => clean({
+  agent: exec.actor?.agent,
+  runId: exec.actor?.runId,
+  ...clean({ profileId: scope.profileId, userId: scope.userId, service: scope.service }),
+  ...clean(scope.actor ?? {}),
+  channel: scope.channel ?? scope.actor?.channel,
+})
+
+const withFrom = (link: RelationshipDraft, card: string): RelationshipDraft => ({ ...link, from: link.from ?? card })
+
+/** Step 11's record: the event as it is appended, `pending`. */
+export const transitionOf = (params: {
+  exec: TransitionExecution
+  resolved: Resolved
+  scope: PlanningScope
+  set: ChangeSet
+  cardId: string
+  seq: number
+  project?: string
+  at: string
+}): Transition => {
+  const { exec, resolved, scope, set, cardId, seq, project, at } = params
+  const kind = resolved.create ? (exec.card as WorkcardDraft).kind : resolved.card!.kind
+
+  return clean({
+    entityId: scope.entityId,
+    card: cardId,
+    kind,
+    type: resolved.type.type,
+    project,
+    seq,
+    action: exec.action,
+    flow: set.flow,
+    transition: exec.action === TransitionAction.Transit ? exec.transition : undefined,
+    from: set.from,
+    to: set.to,
+    changes: set.changes,
+    unset: set.unset.length > 0 ? set.unset : undefined,
+    link: exec.link != null && exec.action !== TransitionAction.Create ? withFrom(exec.link, cardId) : undefined,
+    links: resolved.create && (exec.links?.length ?? 0) > 0 ? exec.links!.map(link => withFrom(link, cardId)) : undefined,
+    actor: actorOf(scope, exec),
+    cause: exec.cause,
+    key: exec.key,
+    at,
+    commit: { state: CommitState.Pending },
+  })
+}

package/src/executor/code.ts

@@ -0,0 +1,83 @@
+import {
+  CODE_MINT_ATTEMPTS, CodeScope, CodeStyle, CodeTaken, mintCode, TransitionAction,
+} from '@owlmeans/planning'
+import type {
+  CodePolicy, PlanningExecContext, PlanningPlugin, PlanningScope, TransitionExecution, WorkcardDraft,
+} from '@owlmeans/planning'
+import type { Criteria } from '@owlmeans/resource'
+import type { Workcard } from '@owlmeans/planning'
+import type { PluginRegistry } from '../registry.js'
+import type { Resolved } from './resolve.js'
+
+/** The criteria a code must be unique within — the policy's scope, `parent` when there is none. */
+const scopeCriteria = (
+  scope: PlanningScope, type: string, parent: string | undefined, policy?: CodePolicy
+): Criteria<Workcard> => ({
+  entityId: scope.entityId,
+  type,
+  ...((policy?.uniqueWithin ?? CodeScope.Parent) === CodeScope.Parent ? { parent: parent ?? null } : {}),
+}) as Criteria<Workcard>
+
+export const takenProbe = (resolved: Resolved, scope: PlanningScope, parent: string | undefined) => {
+  const base = scopeCriteria(scope, resolved.type.type, parent, resolved.type.code)
+
+  return async (code: string): Promise<boolean> =>
+    await resolved.store.cards.count({ ...base, code } as Criteria<Workcard>) > 0
+}
+
+/**
+ * Step 8: the code a new card gets, or the check a changed code passes.
+ *
+ * A caller-supplied code is checked for uniqueness; otherwise the plugins' `mintCode` chain answers
+ * (first answer wins, and is checked too); otherwise the type's policy mints one — a slug policy
+ * derives it from the title. A type with no policy and no supplied code gets none.
+ *
+ * @throws {CodeTaken}
+ */
+export const assignCode = async (
+  exec: TransitionExecution,
+  resolved: Resolved,
+  scope: PlanningScope,
+  registry: PluginRegistry,
+  contextOf: (plugin: PlanningPlugin) => PlanningExecContext
+): Promise<TransitionExecution> => {
+  const policy = resolved.type.code
+
+  if (exec.action !== TransitionAction.Create) {
+    const code = exec.changes?.code
+    if (code != null && code !== resolved.card?.code
+      && await takenProbe(resolved, scope, exec.changes?.parent ?? resolved.card?.parent)(code)) {
+      throw new CodeTaken(code)
+    }
+    return exec
+  }
+
+  const draft = exec.card as WorkcardDraft
+  const taken = takenProbe(resolved, scope, draft.parent)
+  if (draft.code != null && draft.code !== '') {
+    if (await taken(draft.code)) {
+      throw new CodeTaken(draft.code)
+    }
+    return exec
+  }
+  if (policy == null) {
+    return exec
+  }
+
+  let code = await registry.mintCode(draft, taken, contextOf)
+  if (code != null) {
+    if (await taken(code)) {
+      throw new CodeTaken(code)
+    }
+  } else {
+    const count = policy.style === CodeStyle.Sequential
+      ? await resolved.store.cards.count(scopeCriteria(scope, draft.type, draft.parent, policy))
+      : undefined
+    code = await mintCode(policy, taken, CODE_MINT_ATTEMPTS, {
+      ...(policy.style === CodeStyle.Slug ? { seed: draft.title } : {}),
+      ...(count != null ? { count } : {}),
+    })
+  }
+
+  return { ...exec, card: { ...draft, code } }
+}

package/src/executor/receipt.ts

@@ -0,0 +1,66 @@
+import { CommitState, DEFAULT_COMMIT_TIMEOUT, TransitionAction } from '@owlmeans/planning'
+import type {
+  CommitStatus, ExecuteOptions, PlanningStore, Transition, TransitionReceipt, TransitionReceiptView, Workcard,
+} from '@owlmeans/planning'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+const statusOf = async (store: PlanningStore, transition: Transition): Promise<CommitStatus | null> => {
+  if (store.commits == null || transition.id == null) {
+    return null
+  }
+  try {
+    return await store.commits.status(transition.id)
+  } catch {
+    return null
+  }
+}
+
+/** The transition as its latest commit status reports it, and the card when that commit landed. */
+const viewOf = async (store: PlanningStore, transition: Transition): Promise<TransitionReceiptView> => {
+  const status = await statusOf(store, transition)
+  if (status == null) {
+    return { transition }
+  }
+  const view: TransitionReceiptView = {
+    transition: { ...transition, commit: clean({ state: status.state, at: status.at, error: status.error }) },
+  }
+  if (status.state === CommitState.Committed) {
+    view.card = status.card !== undefined
+      ? status.card
+      : transition.action === TransitionAction.Delete
+        ? null
+        : await store.cards.get(transition.card, transition.entityId)
+  }
+  return view
+}
+
+/**
+ * A receipt for an appended (or idempotently found) transition.
+ *
+ * `committed()` waits on the store's commit source; a store without one (a foreign provider that
+ * applies writes itself) answers the card as it reads now. With `wait: true` the receipt is
+ * returned only once the commit landed — `CommitFailed` / `CommitTimeout` otherwise.
+ *
+ * @throws {CommitFailed | CommitTimeout} in wait mode
+ */
+export const makeReceipt = async (
+  store: PlanningStore, transition: Transition, opts?: ExecuteOptions
+): Promise<TransitionReceipt> => {
+  const committed = async (waitOpts?: { timeout?: number }): Promise<Workcard | null> => {
+    if (store.commits == null || transition.id == null) {
+      return await store.cards.get(transition.card, transition.entityId)
+    }
+    return await store.commits.wait(transition.id, { timeout: waitOpts?.timeout ?? DEFAULT_COMMIT_TIMEOUT })
+  }
+
+  let view = await viewOf(store, transition)
+  if (opts?.wait === true && view.transition.commit.state !== CommitState.Committed) {
+    const card = await committed({ timeout: opts.timeout })
+    view = await viewOf(store, transition)
+    view.card = card
+  }
+
+  return { ...view, committed }
+}

package/src/executor/resolve.ts

@@ -0,0 +1,174 @@
+import {
+  CardTypeNotAllowed, isProject, normalizeParents, ParentNotFound, PlanningError, PlanningScopeMismatch,
+  primaryFlowOf, projectOf, slotOf, TransitionAction, UnknownStatusFlow, WorkcardKind, WorkcardNotFound,
+} from '@owlmeans/planning'
+import type {
+  AnyTypeSchema, PlanningFacade, PlanningStore, ProjectTypeSchema, Specification, SpecificationSlot,
+  StatusFlowSchema, TransitionExecution, Workcard, WorkcardDraft,
+} from '@owlmeans/planning'
+import type { PlanningRuntime } from '../service.js'
+
+/** Everything the steps after resolution read about an execution. */
+export interface Resolved {
+  create: boolean
+  /** The existing card (not a create). */
+  card?: Workcard
+  type: AnyTypeSchema
+  flowId: string
+  flow: StatusFlowSchema
+  /** The primary parent, when it resolves. */
+  parent?: Workcard
+  /** The slot a specification belongs to. */
+  slot?: SpecificationSlot
+  /** The store the type is written to. */
+  store: PlanningStore
+}
+
+const trimmed = (value: unknown): unknown => typeof value === 'string' ? value.trim() : value
+
+const TRIMMED = ['title', 'description', 'code'] as const
+
+const trim = <T extends object>(record: T | undefined): T | undefined => {
+  if (record == null) {
+    return record
+  }
+  const copy = { ...record } as Record<string, unknown>
+  for (const key of TRIMMED) {
+    if (typeof copy[key] === 'string') {
+      copy[key] = trimmed(copy[key])
+    }
+  }
+  return copy as T
+}
+
+/**
+ * Step 1: a deep copy with trimmed text, `parents ∋ parent` on a draft, and no duplicate `unset`
+ * paths. The caller's object is never touched.
+ */
+export const normalizeExecution = (input: TransitionExecution): TransitionExecution => {
+  const exec = structuredClone(input) as TransitionExecution
+  if (exec.card != null && typeof exec.card === 'object') {
+    const draft = trim(exec.card) as WorkcardDraft
+    const parents = normalizeParents(draft.parent, draft.parents)
+    exec.card = { ...draft, ...(parents.length > 0 ? { parents, parent: draft.parent ?? parents[0] } : {}) }
+  }
+  if (exec.changes != null) {
+    exec.changes = trim(exec.changes)
+  }
+  if (exec.unset != null) {
+    exec.unset = [...new Set(exec.unset)]
+  }
+  return exec
+}
+
+/** The parent type's rule for a child of `kind`/`type`. @throws {CardTypeNotAllowed} */
+export const assertChildAllowed = (
+  runtime: PlanningRuntime, parent: Workcard, kind: WorkcardKind, type: string
+): void => {
+  if (kind === WorkcardKind.Specification) {
+    return
+  }
+  if (!isProject(parent)) {
+    throw new CardTypeNotAllowed(`${parent.type}:${type}`)
+  }
+  const parentType = runtime.service().schemas.type(parent.type) as ProjectTypeSchema
+  const allowed = kind === WorkcardKind.Project ? parentType.projectTypes ?? [] : parentType.cardTypes ?? []
+  if (!allowed.includes(type)) {
+    throw new CardTypeNotAllowed(`${parent.type}:${type}`)
+  }
+}
+
+/**
+ * Step 4: the card, its type and flow, its parent and — for a specification — its slot.
+ *
+ * @throws {WorkcardNotFound | PlanningScopeMismatch | UnknownWorkcardType | UnknownStatusFlow}
+ * @throws {ParentNotFound | CardTypeNotAllowed | PlanningError}
+ */
+export const resolveExecution = async (
+  runtime: PlanningRuntime, facade: PlanningFacade, exec: TransitionExecution
+): Promise<Resolved> => {
+  const service = runtime.service()
+  const schemas = service.schemas
+  const entityId = facade.scope.entityId
+  const create = exec.action === TransitionAction.Create
+
+  let card: Workcard | undefined
+  let type: AnyTypeSchema
+  let parent: Workcard | undefined
+
+  if (create) {
+    if (exec.card == null || typeof exec.card !== 'object') {
+      throw new PlanningError('malformed:create-without-draft')
+    }
+    const draft = exec.card
+    type = schemas.type(draft.type)
+    if (type.kind !== draft.kind) {
+      throw new PlanningError(`malformed:kind:${draft.type}:${draft.kind}`)
+    }
+    // Normalized: the primary parent is first. It must accept the child; so must every project
+    // among the secondary parents.
+    for (const [index, id] of normalizeParents(draft.parent, draft.parents).entries()) {
+      const found = await facade.cards.load(id)
+      if (found == null) {
+        throw new ParentNotFound(id)
+      }
+      if (index === 0) {
+        parent = found
+      }
+      if (index === 0 || isProject(found)) {
+        assertChildAllowed(runtime, found, draft.kind, draft.type)
+      }
+    }
+    if (draft.kind === WorkcardKind.Specification && parent == null) {
+      throw new PlanningError('malformed:specification-without-parent')
+    }
+  } else {
+    if (typeof exec.card !== 'string' || exec.card === '') {
+      throw new PlanningError(`malformed:${exec.action}-without-card`)
+    }
+    const found = await runtime.reader().cards.get(exec.card, entityId)
+    if (found == null) {
+      throw new WorkcardNotFound(exec.card)
+    }
+    if (found.entityId !== entityId) {
+      throw new PlanningScopeMismatch(exec.card)
+    }
+    card = found
+    type = schemas.type(card.type)
+    parent = card.parent != null ? await facade.cards.load(card.parent) ?? undefined : undefined
+  }
+
+  const flowId = exec.flow ?? primaryFlowOf(type)
+  if (!type.flows.includes(flowId)) {
+    throw new UnknownStatusFlow(`${type.type}:${flowId}`)
+  }
+
+  const kind = create ? (exec.card as WorkcardDraft).kind : card!.kind
+  const category = create ? (exec.card as WorkcardDraft).category : (card as Specification | undefined)?.category
+  const slot = kind === WorkcardKind.Specification && parent != null && category != null
+    ? slotOf(schemas.type(parent.type), category)
+    : undefined
+
+  return {
+    create,
+    ...(card != null ? { card } : {}),
+    type,
+    flowId,
+    flow: schemas.flow(flowId),
+    ...(parent != null ? { parent } : {}),
+    ...(slot != null ? { slot } : {}),
+    store: service.store(type.type),
+  }
+}
+
+/** The project a transition is filed under: a project's own id, else its parent's project. */
+export const projectFor = (resolved: Resolved, exec: TransitionExecution, cardId: string): string | undefined => {
+  if (resolved.card != null) {
+    return isProject(resolved.card) ? resolved.card.id : projectOf(resolved.card, resolved.parent)
+  }
+  const draft = exec.card as WorkcardDraft
+  if (draft.kind === WorkcardKind.Project) {
+    return cardId
+  }
+  return projectOf({ kind: draft.kind, parent: draft.parent, parents: draft.parents ?? [] } as unknown as Workcard, resolved.parent)
+}