@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.21

package/src/helpers/wire.ts

@@ -0,0 +1,251 @@
+import type { ListOptions, Sort } from '@owlmeans/resource'
+import { IntrinsicStatus, WorkcardKind } from '../consts.js'
+import { PlanningError } from '../errors.js'
+import type { ListWire, RelationshipQuery, RelationshipQueryWire, Specification, SpecificationQuery, SpecificationQueryWire, SummaryQuery, SummaryQueryWire, TransitionQuery, TransitionQueryWire, Workcard, WorkcardQuery, WorkcardQueryWire } from '../types.js'
+import type { WireHelper } from './wire/types.js'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+export const createWireHelper = (): WireHelper => {
+  const encodeList = (value?: string | readonly string[] | null): string | undefined => {
+    if (value == null) {
+      return undefined
+    }
+    if (typeof value === 'string') {
+      return encodeList([value])
+    }
+    if (value.length === 0) {
+      return undefined
+    }
+
+    return value.some(entry => entry.includes(',') || entry.startsWith('['))
+      ? JSON.stringify(value)
+      : value.join(',')
+  }
+
+  const decodeList = (value: unknown, key: string = 'list'): string[] | undefined => {
+    if (value == null || value === '') {
+      return undefined
+    }
+    if (Array.isArray(value)) {
+      const entries = value.filter(entry => entry != null && entry !== '').map(entry => `${entry}`)
+      return entries.length > 0 ? entries : undefined
+    }
+    if (typeof value !== 'string') {
+      return [`${value}`]
+    }
+    if (value.startsWith('[')) {
+      const parsed: unknown = (() => {
+        try {
+          return JSON.parse(value)
+        } catch {
+          throw new PlanningError(`malformed:query:${key}`)
+        }
+      })()
+      return Array.isArray(parsed) ? parsed.map(entry => `${entry}`) : undefined
+    }
+    const entries = value.split(',').map(entry => entry.trim()).filter(entry => entry !== '')
+
+    return entries.length > 0 ? entries : undefined
+  }
+
+  /** A list decoded to a bare value when it holds one — the same criteria either way. */
+  const decodeOneOrMany = <T extends string>(value: unknown, key: string): T | T[] | undefined => {
+    const entries = decodeList(value, key) as T[] | undefined
+    return entries == null ? undefined : entries.length === 1 ? entries[0] : entries
+  }
+
+  const encodeJson = (value: unknown): string | undefined => value == null ? undefined : JSON.stringify(value)
+
+  const decodeJson = <T>(value: unknown, key: string): T | undefined => {
+    if (value == null || value === '') {
+      return undefined
+    }
+    if (typeof value !== 'string') {
+      return value as T
+    }
+    try {
+      return JSON.parse(value) as T
+    } catch {
+      throw new PlanningError(`malformed:query:${key}`)
+    }
+  }
+
+  const decodeNumber = (value: unknown, key: string): number | undefined => {
+    if (value == null || value === '') {
+      return undefined
+    }
+    const number = typeof value === 'number' ? value : Number(value)
+    if (Number.isNaN(number)) {
+      throw new PlanningError(`malformed:query:${key}`)
+    }
+
+    return number
+  }
+
+  const decodeBoolean = (value: unknown): boolean | undefined =>
+    value == null || value === '' ? undefined : value === true || value === 'true' || value === '1'
+
+  const decodeText = (value: unknown): string | undefined =>
+    value == null || value === '' ? undefined : `${Array.isArray(value) ? value[0] : value}`
+
+  const encodeSort = <T>(sort?: Sort<T>[] | null): string | undefined =>
+    sort == null || sort.length === 0 ? undefined : sort.map(entry => typeof entry === 'string'
+      ? entry
+      : `${entry.order === 'desc' ? '-' : ''}${entry.field}`).join(',')
+
+  const decodeSort = <T>(value: unknown): Sort<T>[] | undefined => {
+    if (value == null || value === '') {
+      return undefined
+    }
+    const entries: unknown[] = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [value]
+    const sort = entries.flatMap((entry): Sort<T>[] => {
+      if (typeof entry !== 'string') {
+        return entry != null && typeof entry === 'object' && 'field' in entry ? [entry as Sort<T>] : []
+      }
+      const field = entry.trim()
+      if (field === '' || field === '-') {
+        return []
+      }
+      return field.startsWith('-')
+        ? [{ field: field.slice(1) as Sort<T> & string, order: 'desc' } as Sort<T>]
+        : [field as Sort<T>]
+    })
+
+    return sort.length > 0 ? sort : undefined
+  }
+
+  const encodeListOptions = (query?: ListOptions<any> | null): ListWire => clean({
+    page: query?.page,
+    size: query?.size,
+    sort: encodeSort(query?.sort),
+  })
+
+  const decodeListOptions = <T>(wire: Record<string, unknown>): ListOptions<T> => clean({
+    page: decodeNumber(wire.page, 'page'),
+    size: decodeNumber(wire.size, 'size'),
+    sort: decodeSort<T>(wire.sort),
+  })
+
+  const asRecord = (wire: unknown): Record<string, unknown> =>
+    wire != null && typeof wire === 'object' ? wire as Record<string, unknown> : {}
+
+  const encodeWorkcardQuery = (query?: WorkcardQuery | null): WorkcardQueryWire => clean({
+    ...encodeListOptions(query),
+    kind: encodeList(query?.kind),
+    type: encodeList(query?.type),
+    parent: query?.parent,
+    within: query?.within,
+    status: encodeList(query?.status),
+    intrinsic: encodeList(query?.intrinsic),
+    flow: encodeJson(query?.flow),
+    labels: encodeList(query?.labels),
+    code: encodeList(query?.code),
+    ids: encodeList(query?.ids),
+    fields: query?.fields != null && Object.keys(query.fields).length > 0 ? encodeJson(query.fields) : undefined,
+    q: query?.q,
+    category: encodeList(query?.category),
+    updatedSince: query?.updatedSince,
+  })
+
+  const decodeWorkcardQuery = (wire?: WorkcardQueryWire | WorkcardQuery | null): WorkcardQuery => {
+    const value = asRecord(wire)
+    return clean({
+      ...decodeListOptions<Workcard>(value),
+      kind: decodeOneOrMany<WorkcardKind>(value.kind, 'kind'),
+      type: decodeOneOrMany(value.type, 'type'),
+      parent: decodeText(value.parent),
+      within: decodeText(value.within),
+      status: decodeOneOrMany(value.status, 'status'),
+      intrinsic: decodeOneOrMany<IntrinsicStatus>(value.intrinsic, 'intrinsic'),
+      flow: decodeJson<WorkcardQuery['flow']>(value.flow, 'flow'),
+      labels: decodeList(value.labels, 'labels'),
+      code: decodeOneOrMany(value.code, 'code'),
+      ids: decodeList(value.ids, 'ids'),
+      fields: decodeJson<Record<string, unknown>>(value.fields, 'fields'),
+      q: decodeText(value.q),
+      category: decodeOneOrMany(value.category, 'category'),
+      updatedSince: decodeText(value.updatedSince),
+    })
+  }
+
+  const encodeSummaryQuery = (query: SummaryQuery): SummaryQueryWire => clean({
+    parents: encodeList(query.parents) ?? '',
+    kind: query.kind,
+    type: encodeList(query.type),
+  })
+
+  const decodeSummaryQuery = (wire?: SummaryQueryWire | SummaryQuery | null): SummaryQuery => {
+    const value = asRecord(wire)
+    return clean({
+      parents: decodeList(value.parents, 'parents') ?? [],
+      kind: decodeText(value.kind) as WorkcardKind | undefined,
+      type: decodeOneOrMany(value.type, 'type'),
+    })
+  }
+
+  const encodeTransitionQuery = (query?: TransitionQuery | null): TransitionQueryWire => clean({
+    ...encodeListOptions(query),
+    card: query?.card,
+    project: query?.project,
+    sinceSeq: query?.sinceSeq,
+    action: encodeList(query?.action),
+    state: query?.state,
+  })
+
+  const decodeTransitionQuery = (wire?: TransitionQueryWire | TransitionQuery | null): TransitionQuery => {
+    const value = asRecord(wire)
+    return clean({
+      ...decodeListOptions(value),
+      card: decodeText(value.card),
+      project: decodeText(value.project),
+      sinceSeq: decodeNumber(value.sinceSeq, 'sinceSeq'),
+      action: decodeOneOrMany(value.action, 'action'),
+      state: decodeText(value.state),
+    }) as TransitionQuery
+  }
+
+  const encodeSpecificationQuery = (query?: SpecificationQuery | null): SpecificationQueryWire => clean({
+    ...encodeListOptions(query),
+    category: encodeList(query?.category),
+    all: query?.all,
+  })
+
+  const decodeSpecificationQuery = (wire?: SpecificationQueryWire | SpecificationQuery | null): SpecificationQuery => {
+    const value = asRecord(wire)
+    return clean({
+      ...decodeListOptions<Specification>(value),
+      category: decodeOneOrMany(value.category, 'category'),
+      all: decodeBoolean(value.all),
+    })
+  }
+
+  const encodeRelationshipQuery = (query?: RelationshipQuery | null): RelationshipQueryWire => clean({
+    ...encodeListOptions(query),
+    from: encodeList(query?.from),
+    to: encodeList(query?.to),
+    type: encodeList(query?.type),
+  })
+
+  const decodeRelationshipQuery = (wire?: RelationshipQueryWire | RelationshipQuery | null): RelationshipQuery => {
+    const value = asRecord(wire)
+    return clean({
+      ...decodeListOptions(value),
+      from: decodeOneOrMany(value.from, 'from'),
+      to: decodeOneOrMany(value.to, 'to'),
+      type: decodeOneOrMany(value.type, 'type'),
+    }) as RelationshipQuery
+  }
+
+  return {
+    encodeList, decodeList, encodeSort, decodeSort,
+    encodeWorkcardQuery, decodeWorkcardQuery,
+    encodeSummaryQuery, decodeSummaryQuery,
+    encodeTransitionQuery, decodeTransitionQuery,
+    encodeSpecificationQuery, decodeSpecificationQuery,
+    encodeRelationshipQuery, decodeRelationshipQuery,
+  }
+}
+
+export const wireHelper = createWireHelper()

package/src/i18n/be.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "Змяненне яшчэ захоўваецца — праверце крыху пазней",
     "PlanningErrorCommitFailed": "Не ўдалося захаваць змяненне",
     "PlanningErrorScopeMismatch": "Гэты элемент не існуе або недаступны вам",
+    "PlanningErrorSchemaConflict": "Гэта вызначэнне змянілі за гэты час — абнавіце і паспрабуйце зноў",
+    "PlanningErrorSchemaInUse": "Гэта вызначэнне яшчэ выкарыстоўваецца і не можа быць выведзена з ужытку",
+    "PlanningErrorSchemaSealed": "Гэта вызначэнне замацавана і не можа быць зменена тут",
+    "PlanningErrorSchemaInvalid": "Гэта вызначэнне несапраўднае",
+    "PlanningErrorForbidden": "Вам не дазволена рабіць гэтую змену",
     "PlanningErrorUnsupported": "Гэтая аперацыя не падтрымліваецца для гэтага элемента"
   }
 }

package/src/i18n/de.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "Die Änderung wird noch gespeichert — prüfe es gleich noch einmal",
     "PlanningErrorCommitFailed": "Die Änderung konnte nicht gespeichert werden",
     "PlanningErrorScopeMismatch": "Dieses Element existiert nicht oder ist für dich nicht verfügbar",
+    "PlanningErrorSchemaConflict": "Diese Definition wurde inzwischen geändert — neu laden und erneut versuchen",
+    "PlanningErrorSchemaInUse": "Diese Definition wird noch verwendet und kann nicht zurückgezogen werden",
+    "PlanningErrorSchemaSealed": "Diese Definition ist festgelegt und kann hier nicht geändert werden",
+    "PlanningErrorSchemaInvalid": "Diese Definition ist ungültig",
+    "PlanningErrorForbidden": "Du darfst diese Änderung nicht vornehmen",
     "PlanningErrorUnsupported": "Dieser Vorgang wird für dieses Element nicht unterstützt"
   }
 }

package/src/i18n/en.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "The change is still being saved — check again shortly",
     "PlanningErrorCommitFailed": "The change could not be saved",
     "PlanningErrorScopeMismatch": "This item does not exist or is not available to you",
+    "PlanningErrorSchemaConflict": "This definition was changed in the meantime — reload and try again",
+    "PlanningErrorSchemaInUse": "This definition is still in use and cannot be retired",
+    "PlanningErrorSchemaSealed": "This definition is fixed and cannot be changed here",
+    "PlanningErrorSchemaInvalid": "This definition is not valid",
+    "PlanningErrorForbidden": "You are not allowed to make this change",
     "PlanningErrorUnsupported": "This operation is not supported for this item"
   }
 }

package/src/i18n/es.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "El cambio aún se está guardando — vuelve a comprobarlo en breve",
     "PlanningErrorCommitFailed": "No se pudo guardar el cambio",
     "PlanningErrorScopeMismatch": "Este elemento no existe o no está disponible para ti",
+    "PlanningErrorSchemaConflict": "Esta definición cambió mientras tanto — recarga e inténtalo de nuevo",
+    "PlanningErrorSchemaInUse": "Esta definición todavía está en uso y no se puede retirar",
+    "PlanningErrorSchemaSealed": "Esta definición es fija y no se puede cambiar aquí",
+    "PlanningErrorSchemaInvalid": "Esta definición no es válida",
+    "PlanningErrorForbidden": "No tienes permiso para hacer este cambio",
     "PlanningErrorUnsupported": "Esta operación no es compatible con este elemento"
   }
 }

package/src/i18n/fr.json

@@ -0,0 +1,56 @@
+{
+  "kind": {
+    "card": "Carte",
+    "project": "Projet",
+    "specification": "Spécification"
+  },
+  "intrinsic": {
+    "planned": "Planifié",
+    "in-progress": "En cours",
+    "closed": "Fermé"
+  },
+  "action": {
+    "create": "Créé",
+    "update": "Mis à jour",
+    "transit": "Statut modifié",
+    "link": "Lié",
+    "unlink": "Délié",
+    "delete": "Supprimé"
+  },
+  "commit": {
+    "pending": "Enregistrement…",
+    "committed": "Enregistré",
+    "failed": "Non enregistré"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Texte brut"
+  },
+  "errors": {
+    "PlanningError": "La demande de planification n’a pas pu être traitée",
+    "PlanningErrorWorkcardNotFound": "Cet élément n’existe pas ou ne vous est pas accessible",
+    "PlanningErrorUnknownWorkcardType": "Ce type d’élément est inconnu",
+    "PlanningErrorUnknownStatusFlow": "Ce flux de statut est inconnu",
+    "PlanningErrorParentNotFound": "L’élément parent n’existe pas",
+    "PlanningErrorCardTypeNotAllowed": "Ce type d’élément ne peut pas être ajouté ici",
+    "PlanningErrorRefused": "La modification a été refusée",
+    "PlanningErrorIllegalTransition": "Ce changement de statut n’est pas autorisé depuis le statut actuel",
+    "PlanningErrorFieldsInvalid": "Certains champs ont des valeurs non valides",
+    "PlanningErrorLabelNotAllowed": "Cette étiquette n’est pas autorisée ici",
+    "PlanningErrorSpecificationSlotUnknown": "Ce type de document n’est pas autorisé ici",
+    "PlanningErrorSpecificationRevisionConflict": "Ce document existe déjà : modifiez-le plutôt",
+    "PlanningErrorRelationshipRefused": "Ce lien n’est pas autorisé",
+    "PlanningErrorCodeTaken": "Ce code est déjà utilisé",
+    "PlanningErrorWorkcardConflict": "Quelqu’un a modifié cet élément entre-temps. Actualisez la page puis réessayez.",
+    "PlanningErrorCommitTimeout": "La modification est encore en cours d’enregistrement. Vérifiez de nouveau dans un instant.",
+    "PlanningErrorCommitFailed": "La modification n’a pas pu être enregistrée",
+    "PlanningErrorScopeMismatch": "Cet élément n’existe pas ou ne vous est pas accessible",
+    "PlanningErrorSchemaConflict": "Cette définition a été modifiée entre-temps. Actualisez la page puis réessayez.",
+    "PlanningErrorSchemaInUse": "Cette définition est encore utilisée et ne peut pas être retirée",
+    "PlanningErrorSchemaSealed": "Cette définition est figée et ne peut pas être modifiée ici",
+    "PlanningErrorSchemaInvalid": "Cette définition n’est pas valide",
+    "PlanningErrorForbidden": "Vous n’êtes pas autorisé à effectuer cette modification",
+    "PlanningErrorUnsupported": "Cette opération n’est pas prise en charge pour cet élément"
+  }
+}

package/src/i18n/pl.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "Zmiana jest nadal zapisywana — sprawdź ponownie za chwilę",
     "PlanningErrorCommitFailed": "Nie udało się zapisać zmiany",
     "PlanningErrorScopeMismatch": "Ten element nie istnieje lub nie jest dla Ciebie dostępny",
+    "PlanningErrorSchemaConflict": "Ta definicja została w międzyczasie zmieniona — odśwież i spróbuj ponownie",
+    "PlanningErrorSchemaInUse": "Ta definicja jest nadal używana i nie może zostać wycofana",
+    "PlanningErrorSchemaSealed": "Ta definicja jest stała i nie można jej tu zmienić",
+    "PlanningErrorSchemaInvalid": "Ta definicja jest nieprawidłowa",
+    "PlanningErrorForbidden": "Nie masz uprawnień do wprowadzenia tej zmiany",
     "PlanningErrorUnsupported": "Ta operacja nie jest obsługiwana dla tego elementu"
   }
 }

package/src/i18n/ru.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "Изменение ещё сохраняется — проверьте чуть позже",
     "PlanningErrorCommitFailed": "Не удалось сохранить изменение",
     "PlanningErrorScopeMismatch": "Этот элемент не существует или недоступен вам",
+    "PlanningErrorSchemaConflict": "Это определение изменили за это время — обновите и попробуйте снова",
+    "PlanningErrorSchemaInUse": "Это определение ещё используется и не может быть выведено из употребления",
+    "PlanningErrorSchemaSealed": "Это определение закреплено и не может быть изменено здесь",
+    "PlanningErrorSchemaInvalid": "Это определение недействительно",
+    "PlanningErrorForbidden": "У вас нет прав на это изменение",
     "PlanningErrorUnsupported": "Эта операция не поддерживается для этого элемента"
   }
 }

package/src/i18n/uk.json

@@ -46,6 +46,11 @@
     "PlanningErrorCommitTimeout": "Зміна ще зберігається — перевірте трохи пізніше",
     "PlanningErrorCommitFailed": "Не вдалося зберегти зміну",
     "PlanningErrorScopeMismatch": "Цей елемент не існує або недоступний вам",
+    "PlanningErrorSchemaConflict": "Це визначення змінили тим часом — оновіть і спробуйте знову",
+    "PlanningErrorSchemaInUse": "Це визначення ще використовується і не може бути виведене з ужитку",
+    "PlanningErrorSchemaSealed": "Це визначення закріплене і не може бути змінене тут",
+    "PlanningErrorSchemaInvalid": "Це визначення недійсне",
+    "PlanningErrorForbidden": "Вам не дозволено вносити цю зміну",
     "PlanningErrorUnsupported": "Ця операція не підтримується для цього елемента"
   }
 }

package/src/i18n.ts

@@ -1,4 +1,4 @@
-import { addI18nLib } from '@owlmeans/i18n'
+
 import { PLANNING_I18N } from './consts.js'
 
 import en from './i18n/en.json' with { type: 'json' }
@@ -8,14 +8,16 @@ import be from './i18n/be.json' with { type: 'json' }
 import uk from './i18n/uk.json' with { type: 'json' }
 import es from './i18n/es.json' with { type: 'json' }
 import de from './i18n/de.json' with { type: 'json' }
+import fr from './i18n/fr.json' with { type: 'json' }
+import { i18nHelper } from '@owlmeans/i18n'
 
 /**
  * Labels under `lib:planning.*`, and every refusal under the shared `errors` resource keyed by its
  * type name — which is where a panel's error lookup (`errors.<type>`) finds them.
  */
-const LANGUAGES = { en, pl, ru, be, uk, es, de }
+const LANGUAGES = { en, pl, ru, be, uk, es, de, fr }
 
 Object.entries(LANGUAGES).forEach(([lng, data]) => {
-  addI18nLib(lng, PLANNING_I18N, data)
-  addI18nLib(lng, 'errors', data.errors)
+  i18nHelper.addI18nLib(lng, PLANNING_I18N, data)
+  i18nHelper.addI18nLib(lng, 'errors', data.errors)
 })

package/src/index.ts

@@ -1,5 +1,9 @@
 export type * from './types.js'
+export type * from './aliases/types.js'
+export type * from './entrypoints/types.js'
 export * from './consts.js'
+export * from './aliases.js'
+export * from './utils.js'
 export * from './schemas.js'
 export * from './errors.js'
 export * from './entrypoints.js'

package/src/models/index.ts

@@ -1,21 +1,6 @@
-import { WorkcardKind } from '../consts.js'
-import type { PlanningFacade, Project, Specification, Workcard, WorkcardModel } from '../types.js'
-import { makeProjectModel } from './project.js'
-import { makeSpecificationModel } from './specification.js'
-import { makeWorkcardModel } from './workcard.js'
+export type * from './types.js'
 
 export { executeFor, makeWorkcardModel } from './workcard.js'
 export { makeProjectModel } from './project.js'
 export { makeSpecificationModel } from './specification.js'
-
-/** The model a record's kind calls for — what a facade's `model()` answers. */
-export const modelOf = <T extends Workcard = Workcard>(record: T, facade: PlanningFacade): WorkcardModel<T> => {
-  switch (record.kind) {
-    case WorkcardKind.Project:
-      return makeProjectModel(record as unknown as Project, facade) as unknown as WorkcardModel<T>
-    case WorkcardKind.Specification:
-      return makeSpecificationModel(record as unknown as Specification, facade) as unknown as WorkcardModel<T>
-    default:
-      return makeWorkcardModel(record, facade)
-  }
-}
+export { modelOf } from './model.js'

package/src/models/model.ts

@@ -0,0 +1,18 @@
+import { WorkcardKind } from '../consts.js'
+import type { PlanningFacade, Project, Specification, Workcard } from '../types.js'
+import { makeProjectModel } from './project.js'
+import { makeSpecificationModel } from './specification.js'
+import type { WorkcardModel } from './types.js'
+import { makeWorkcardModel } from './workcard.js'
+
+/** The model a record's kind calls for — what a facade's `model()` answers. */
+export const modelOf = <T extends Workcard = Workcard>(record: T, facade: PlanningFacade): WorkcardModel<T> => {
+  switch (record.kind) {
+    case WorkcardKind.Project:
+      return makeProjectModel(record as unknown as Project, facade) as unknown as WorkcardModel<T>
+    case WorkcardKind.Specification:
+      return makeSpecificationModel(record as unknown as Specification, facade) as unknown as WorkcardModel<T>
+    default:
+      return makeWorkcardModel(record, facade)
+  }
+}

package/src/models/project.ts

@@ -1,5 +1,6 @@
 import { IntrinsicStatus, WorkcardKind } from '../consts.js'
-import type { PlanningFacade, Project, ProjectModel } from '../types.js'
+import type { PlanningFacade, Project } from '../types.js'
+import type { ProjectModel } from './types.js'
 import { makeWorkcardModel } from './workcard.js'
 
 /** A workcard model plus the project's own reads: its cards, its sub-projects, its summary. */

package/src/models/specification.ts

@@ -1,4 +1,5 @@
-import type { PlanningFacade, Specification, SpecificationModel } from '../types.js'
+import type { PlanningFacade, Specification } from '../types.js'
+import type { SpecificationModel } from './types.js'
 import { makeWorkcardModel } from './workcard.js'
 
 /** A workcard model over one document: its body, a revision of it, and its history from the log. */

package/src/models/types.ts

@@ -0,0 +1,70 @@
+import type { ListResult } from '@owlmeans/resource'
+import type { IntrinsicStatus, SpecificationFormat, WorkcardKind } from '../consts.js'
+import type {
+  AnyTypeSchema, ExecuteOptions, IntrinsicCounts, Project, Relationship, RelationshipQuery, Specification,
+  SpecificationQuery, SpecificationRevision, StatusFlowSchema, StatusTransitionRule, SummaryQuery, Transition,
+  TransitionActor, TransitionQuery, TransitionReceipt, Workcard, WorkcardChanges, WorkcardQuery,
+} from '../types.js'
+
+export interface ExecuteMeta {
+  actor?: TransitionActor
+  cause?: string
+  key?: string
+  expectSeq?: number | null
+}
+
+export interface ModelExecuteOptions extends ExecuteOptions, ExecuteMeta {}
+
+export interface SpecificationWriteOptions extends ModelExecuteOptions {
+  format?: SpecificationFormat
+  version?: number
+  ref?: string
+  /** The title a new document gets; the category when omitted. */
+  title?: string
+  /** The specification type; resolved from the slot and the registry when omitted. */
+  type?: string
+}
+
+export interface WorkcardModel<T extends Workcard = Workcard> {
+  record: T
+  id: string
+  kind: WorkcardKind
+  type: string
+  schema: () => AnyTypeSchema
+  flow: (id?: string) => StatusFlowSchema
+  statusOf: (flowId?: string) => string
+  intrinsicOf: (flowId?: string) => IntrinsicStatus
+  can: (transition: string, flowId?: string) => boolean
+  available: (flowId?: string) => StatusTransitionRule[]
+  pending: () => boolean
+  transit: (transition: string, changes?: WorkcardChanges, opts?: ModelExecuteOptions & { flow?: string }) => Promise<TransitionReceipt>
+  update: (changes: WorkcardChanges, opts?: ModelExecuteOptions & { unset?: string[] }) => Promise<TransitionReceipt>
+  remove: (opts?: ModelExecuteOptions) => Promise<TransitionReceipt>
+  link: (type: string, to: string, fields?: Record<string, unknown>, opts?: ModelExecuteOptions) => Promise<TransitionReceipt>
+  unlink: (type: string, to: string, opts?: ModelExecuteOptions) => Promise<TransitionReceipt>
+  children: (query?: Omit<WorkcardQuery, 'parent'>) => Promise<ListResult<Workcard>>
+  relationships: (query?: RelationshipQuery) => Promise<ListResult<Relationship>>
+  transitions: (query?: Omit<TransitionQuery, 'card'>) => Promise<ListResult<Transition>>
+  specification: (category: string) => Promise<Specification | null>
+  specifications: (query?: SpecificationQuery) => Promise<ListResult<Specification>>
+  revisions: (category: string, limit?: number) => Promise<SpecificationRevision[]>
+  /** Create the slot's document, or revise it when it already exists. */
+  write: (category: string, body: string, opts?: SpecificationWriteOptions) => Promise<TransitionReceipt>
+  reload: () => Promise<WorkcardModel<T>>
+}
+
+export interface ProjectModel extends WorkcardModel<Project> {
+  cards: (query?: Omit<WorkcardQuery, 'within' | 'kind'>) => Promise<ListResult<Workcard>>
+  projects: (query?: Omit<WorkcardQuery, 'within' | 'kind'>) => Promise<ListResult<Workcard>>
+  summary: (query?: Omit<SummaryQuery, 'parents'>) => Promise<IntrinsicCounts>
+  /** A `delete` of the project — the store removes everything under it. */
+  purge: (opts?: ModelExecuteOptions) => Promise<TransitionReceipt>
+  reload: () => Promise<ProjectModel>
+}
+
+export interface SpecificationModel extends WorkcardModel<Specification> {
+  body: () => string | undefined
+  revise: (body: string, opts?: ModelExecuteOptions & { version?: number, ref?: string }) => Promise<TransitionReceipt>
+  history: (limit?: number) => Promise<SpecificationRevision[]>
+  reload: () => Promise<SpecificationModel>
+}

package/src/models/workcard.ts

@@ -1,14 +1,12 @@
 import { IntrinsicStatus, TransitionAction, WorkcardKind } from '../consts.js'
 import { PlanningError } from '../errors.js'
-import { isPending } from '../helpers/card.js'
-import { slotOf, specificationTypeOf } from '../helpers/specification.js'
-import {
-  canTransit, initialStatusOf, intrinsicOf, primaryFlowOf, transitionsFrom,
-} from '../helpers/status.js'
+import { cardHelper } from '../helpers/card.js'
+import { specificationHelper } from '../helpers/specification.js'
+import { statusHelper } from '../helpers/status.js'
 import type {
-  ExecuteOptions, ModelExecuteOptions, PlanningFacade, TransitionExecution, TransitionReceipt,
-  Workcard, WorkcardModel,
+  ExecuteOptions, PlanningFacade, TransitionExecution, TransitionReceipt, Workcard,
 } from '../types.js'
+import type { ModelExecuteOptions, WorkcardModel } from './types.js'
 
 /**
  * Run an execution with a model's defaults: `expectSeq` is the record's head (its seq when nothing
@@ -53,25 +51,25 @@ export const makeWorkcardModel = <T extends Workcard = Workcard>(record: T, faca
 
     schema: () => facade.schemas.type(record.type),
 
-    flow: flowId => facade.schemas.flow(flowId ?? primaryFlowOf(model.schema())),
+    flow: flowId => facade.schemas.flow(flowId ?? statusHelper.primaryFlowOf(model.schema())),
 
     statusOf: flowId => {
-      const primary = primaryFlowOf(model.schema())
+      const primary = statusHelper.primaryFlowOf(model.schema())
       if (flowId == null || flowId === primary) {
         return record.status
       }
-      return record.flows[flowId] ?? initialStatusOf(model.flow(flowId))
+      return record.flows[flowId] ?? statusHelper.initialStatusOf(model.flow(flowId))
     },
 
     intrinsicOf: flowId => flowId == null
       ? record.intrinsic
-      : intrinsicOf(model.flow(flowId), model.statusOf(flowId)) ?? IntrinsicStatus.Planned,
+      : statusHelper.intrinsicOf(model.flow(flowId), model.statusOf(flowId)) ?? IntrinsicStatus.Planned,
 
-    can: (transition, flowId) => canTransit(model.flow(flowId), transition, model.statusOf(flowId)),
+    can: (transition, flowId) => statusHelper.canTransit(model.flow(flowId), transition, model.statusOf(flowId)),
 
-    available: flowId => transitionsFrom(model.flow(flowId), model.statusOf(flowId)),
+    available: flowId => statusHelper.transitionsFrom(model.flow(flowId), model.statusOf(flowId)),
 
-    pending: () => isPending(record),
+    pending: () => cardHelper.isPending(record),
 
     transit: (transition, changes, opts) => run({
       action: TransitionAction.Transit, transition, flow: opts?.flow, changes,
@@ -114,11 +112,11 @@ export const makeWorkcardModel = <T extends Workcard = Workcard>(record: T, faca
         }, opts)
       }
 
-      const slot = slotOf(model.schema(), category)
+      const slot = specificationHelper.slotOf(model.schema(), category)
       return executeFor(facade, null, {
         card: Object.fromEntries(Object.entries({
           kind: WorkcardKind.Specification,
-          type: opts?.type ?? specificationTypeOf(facade.schemas, record.type, slot),
+          type: opts?.type ?? specificationHelper.specificationTypeOf(facade.schemas, record.type, slot),
           parent: id,
           title: opts?.title ?? category,
           category,