@dotbep/core 0.2.7 → 0.2.8

package/examples/12-history.ts

@@ -1,166 +0,0 @@
-// part of: node --experimental-strip-types examples/run-all.ts  (use --12 to stop here)
-//
-// Covers: history — commit, status, hasPendingChanges, discard, compare,
-//         get, getStandardContent, revert, reset, squash.
-//
-// The history system versions the BEP using inverse RFC 6902 diffs. Each
-// commit stores how to go back to the previous version, so the current state
-// is always bep.json and older states are reconstructed on demand.
-//
-// Version numbers follow a {major}.{minor} scheme:
-//   patch commit  → bumps minor  (0.0 → 0.1 → 0.2)
-//   version commit → bumps major (0.x → 1.0), requires approvedBy[]
-//
-// Bep.open() auto-normalizes a BEP with no history by silently creating a v0.0
-// baseline from the current state. The first manual commit therefore lands at
-// v0.1, not v0.0. This example operates in memory only — it does not write back
-// to example.bep, so the history modifications are discarded after the run.
-//
-// Standards (.md files) are versioned separately from bep.json: the history
-// system snapshots each .md file only when it changes between commits, and
-// resolves the correct snapshot when getStandardContent(id, version) is called.
-
-import { readFileSync } from 'node:fs'
-import { Bep } from '../dist/index.js'
-
-const bep = await Bep.open(readFileSync('examples/example.bep'))
-
-const stdNamingId = bep.standards.list().find(s => s.name === 'Naming Convention')!.id
-
-// ─── v0.1: first manual commit ────────────────────────────────────────────────
-//
-// Bep.open() auto-normalizes a BEP without history by creating a v0.0 baseline
-// from the current state. The first manual commit therefore lands at v0.1.
-
-console.log('=== history ===')
-console.log('\n--- commit v0.1 (initial) ---')
-
-const v0 = await bep.history.commit({
-  type:        'patch',
-  author:      'alice@arc.com',
-  description: 'Initial BEP draft — all sections complete',
-})
-console.log('committed:', v0.version)  // 0.1
-
-// ─── v0.2: data changes + standard content update ─────────────────────────────
-
-console.log('\n--- changes for v0.2 ---')
-
-bep.roles.add([{ name: 'BIM Author', color: '#22CC88' }])
-bep.standards.setContent(stdNamingId, '# Naming Convention v3\nRevised rules after client review.')
-
-// status() reports what changed since the last commit
-const st02 = await bep.history.status()
-console.log('pending — standards:', st02.standards)
-// → [{ status: 'content-modified', id: stdNamingId }]
-
-const v1 = await bep.history.commit({
-  type:        'patch',
-  author:      'alice@arc.com',
-  description: 'Add BIM Author role + revise naming standard',
-})
-console.log('committed:', v1.version)  // 0.2
-
-// resolve standard content at specific historical versions
-const namingAtV01 = await bep.history.getStandardContent(stdNamingId, '0.1')
-const namingAtV02 = await bep.history.getStandardContent(stdNamingId, '0.2')
-console.log('naming @ v0.1 (first 35):', namingAtV01?.slice(0, 35))
-console.log('naming @ v0.2 (first 35):', namingAtV02?.slice(0, 35))
-
-// ─── v1.0: official version with approvers ────────────────────────────────────
-
-console.log('\n--- commit v1.0 (official version, requires approvedBy) ---')
-
-bep.standards.setContent(stdNamingId, '# Naming Convention v4\nFinal approved version.')
-bep.phases.add([{ name: 'Tender' }])
-
-const v2 = await bep.history.commit({
-  type:        'version',
-  author:      'alice@arc.com',
-  description: 'First official BEP release',
-  approvedBy:  ['alice@arc.com'],
-})
-console.log('committed:', v2.version)  // 1.0
-
-// ─── discard ──────────────────────────────────────────────────────────────────
-
-console.log('\n--- discard uncommitted changes ---')
-
-bep.phases.add([{ name: 'Temporary — will be discarded' }])
-bep.standards.setContent(stdNamingId, '# WILL BE DISCARDED')
-
-console.log('hasPendingChanges before discard:', await bep.history.hasPendingChanges())
-await bep.history.discard()
-console.log('hasPendingChanges after discard: ', await bep.history.hasPendingChanges())
-
-const namingAfterDiscard = await bep.standards.getContent(stdNamingId)
-console.log('naming std restored (first 35):', namingAfterDiscard.slice(0, 35))
-// → v4 content (restored from baseline at v1.0)
-
-// ─── list / get / compare ─────────────────────────────────────────────────────
-
-console.log('\n--- list / get / compare ---')
-
-const versions = await bep.history.list()
-console.log('versions:', versions.map(v => v.version))  // ['0.1', '0.2', '1.0']
-
-// get: reconstruct state at v0.1 — BIM Author role should not exist yet
-const atV01 = await bep.history.get('0.1')
-const bimAuthorInV01 = atV01.roles.find(r => r.name === 'BIM Author')
-console.log('BIM Author in v0.1:', bimAuthorInV01 ?? 'not found (correct)')
-
-// compare: RFC 6902 diff between two versions + standards diff
-const { diff: ops, standards: stdDiff } = await bep.history.compare('0.1', '0.2')
-console.log('ops v0.1→v0.2:', ops.length, 'operation(s)', ops.slice(0, 2).map(o => `${o.op} ${o.path}`))
-console.log('std  diff:     ', stdDiff)
-
-// ─── revert ───────────────────────────────────────────────────────────────────
-
-console.log('\n--- revert to v0.0 (non-destructive — creates a new version) ---')
-
-const v3 = await bep.history.revert('0.1', {
-  type:        'patch',
-  author:      'alice@arc.com',
-  description: 'Revert to initial draft',
-})
-console.log('reverted as:', v3.version)  // 1.1
-
-const bimAuthorAfterRevert = bep.roles.list().find(r => r.name === 'BIM Author')
-console.log('BIM Author after revert:', bimAuthorAfterRevert ?? 'not found (correct)')
-console.log('versions after revert:  ', (await bep.history.list()).map(v => v.version))
-// → ['0.0', '0.1', '0.2', '1.0', '1.1']
-
-// ─── reset ────────────────────────────────────────────────────────────────────
-
-console.log('\n--- reset to v0.2 (destructive — deletes all versions after v0.2) ---')
-
-console.log('versions before reset:', (await bep.history.list()).map(v => v.version))
-await bep.history.reset('0.2')
-console.log('versions after reset: ', (await bep.history.list()).map(v => v.version))
-// → ['0.0', '0.1', '0.2']
-
-// ─── squash ───────────────────────────────────────────────────────────────────
-
-console.log('\n--- squash (destructive — collapses all history into one terminus) ---')
-
-console.log('versions before squash:', (await bep.history.list()).map(v => v.version))
-
-const squashed = await bep.history.squash({
-  newBase:     '2.0',
-  author:      'alice@arc.com',
-  description: 'Clean start — squash all history into v2.0',
-  approvedBy:  ['alice@arc.com'],
-})
-console.log('squash result:', squashed.version)
-console.log('versions after squash:', (await bep.history.list()).map(v => v.version))
-// → ['2.0']
-
-// getStandardContent still works from the new terminus
-const namingAt20 = await bep.history.getStandardContent(stdNamingId, '2.0')
-console.log('\nnaming std @ 2.0 (first 35):', namingAt20?.slice(0, 35))
-
-// get() terminus works
-const atSquashed = await bep.history.get('2.0')
-console.log('get 2.0 — project name:', atSquashed.project.name)
-
-console.log('\nDone.')

package/examples/13-engine.ts

@@ -1,152 +0,0 @@
-// run: node --experimental-strip-types examples/13-engine.ts  (from core/)
-//
-// Covers: Engine, Runtime, workflow execution, type generation,
-//         getRemoteData, useAdapter.
-//
-// bep.generateRuntimeTypes() produces a TypeScript contract from the BEP's runtime handlers — with JSDoc from each description field.
-// Writing it to bep.d.ts gives full type safety in the Runtime development.
-//
-// Workflow (3 nodes):
-//
-//   start ──► review ──[submit / effect: notify-reviewer]──► end
-
-import { writeFileSync } from 'node:fs'
-import * as BEP from '../dist/index.js'
-import type { BepTypes } from './bep.js'
-
-// ─── 1. Build the BEP ─────────────────────────────────────────────────────────
-
-const bep = BEP.Bep.create({ name: 'Demo Project', code: 'DEMO', description: '' })
-
-const [{ id: roleManagerId }]  = bep.roles.add([{ name: 'BIM Manager' }]).succeeded
-bep.members.add([{ email: 'manager@demo.com', name: 'Ana García', roleId: roleManagerId }])
-const [{ id: assetTypeId }]    = bep.assetTypes.add([{ id: 'MDL', name: 'Model' }]).succeeded
-const [{ id: actionReviewId }] = bep.actions.add([{ name: 'Review model' }]).succeeded
-
-bep.events.add([
-  { id: 'submit',   name: 'Submit for review', payload: [{ key: 'comment', type: 'string', required: false }] },
-  { id: 'approved', name: 'Approved' },
-])
-bep.effects.add([
-  {
-    id: 'notify-reviewer', name: 'Notify reviewer',
-    description: 'Sends a notification to the assigned reviewer when a model is submitted. Uses the comment from the submit event payload.',
-    payload: [{ key: 'comment', type: 'string', required: false }],
-  },
-])
-bep.automations.add([
-  {
-    id: 'auto-approve', name: 'Auto approve',
-    description: 'Automatically approves the model if no blocking issues are found in the previous review cycle.',
-    payload: [{ key: 'threshold', type: 'number', required: true }],
-    output: [{ key: 'result', type: 'string', required: true }],
-  },
-])
-bep.resolvers.add([
-  {
-    id: 'fetch-json', name: 'Fetch JSON',
-    description: 'Fetches a JSON array from the remote data URL. Authenticates with an API key via Authorization header. Returns the raw parsed array.',
-    envKeys: ['API_KEY'],
-  },
-])
-bep.adapters.add([
-  {
-    id: 'pick-label-value', name: 'Pick label + value',
-    description: 'Maps an array of { name, count } objects to { label, value } pairs compatible with dotbep:pie-chart.',
-  },
-])
-bep.remoteData.add([
-  {
-    name: 'Model stats', url: 'https://example.com/stats.json',
-    description: 'Aggregated model statistics exported nightly from the project management tool.',
-    resolverId: 'fetch-json',
-  },
-])
-
-const [{ id: workflowId }] = bep.workflows.add([{
-  name: 'Model Review',
-  diagram: {
-    direction: 'LR',
-    nodes: {
-      start:  { type: 'start' },
-      review: { type: 'process', actionId: actionReviewId, responsibleRoleIds: [roleManagerId] },
-      end:    { type: 'end' },
-    },
-    edges: {
-      e1: { from: 'start',  to: 'review' },
-      e2: { from: 'review', to: 'end', triggerEventId: 'submit', effectIds: ['notify-reviewer'] },
-    },
-  },
-}]).succeeded
-
-// ─── 2. Generate types ────────────────────────────────────────────────────────
-//
-// bep.generateRuntimeTypes() produces a TypeScript contract from the BEP's effects and
-// automations. Commit bep.d.ts alongside your runtime so TypeScript can validate it.
-
-writeFileSync('examples/bep.d.ts', bep.generateRuntimeTypes())
-console.log('Generated examples/bep.d.ts')
-
-// ─── 3. Declare the BEP Runtime ───────────────────────────────────────────────
-//
-// BepTypes (from bep.d.ts) types each handler's payload automatically.
-
-class MyRuntime extends BEP.Runtime<BepTypes> {
-  constructor(options: BEP.RuntimeOptions) {
-    super(options)
-    this.effect('notify-reviewer', async (instance, payload) => {
-      console.log('  [effect] notify-reviewer fired')
-      console.log('  [effect] submitted by:', instance.history.at(-1)?.actor)
-      console.log('  [effect] comment:', payload.comment)  // string | undefined ← inferred
-    })
-    this.automation('auto-approve', async (_instance, payload) => {
-      console.log('  [automation] auto-approve running, threshold:', payload.threshold)
-      return { eventId: 'approved', result: 'passed' }
-    })
-    this.resolver('fetch-json', async (url, env) => {
-      const res = await fetch(url, { headers: { Authorization: `Bearer ${env.API_KEY}` } })
-      return res.json()
-    })
-    this.adapter('pick-label-value', (data) => {
-      return (data as { name: string; count: number }[]).map(d => ({ label: d.name, value: d.count }))
-    })
-  }
-}
-
-// ─── 4. Init the engine and run ───────────────────────────────────────────────
-
-bep.engine.init({ runtime: new MyRuntime({ env: {} }) })
-
-console.log('\n=== create instance ===')
-const instance = await bep.engine.createInstance(
-  workflowId,
-  { assetTypeId, id: 'model-001', label: 'Structural Model v3', source: 'bep:deliverables' },
-  'manager@demo.com',
-)
-console.log('status:', instance!.status)
-console.log('current node:', instance!.currentNodeId)
-
-console.log('\n=== emit: submit ===')
-const result = await bep.engine.emit(instance!.id, {
-  eventId: 'submit',
-  actor:   'manager@demo.com',
-  payload: { comment: 'Ready for review' },
-})
-console.log('ok:', result.ok)
-console.log('transitions:', result.transitionsApplied?.map(t => `${t.fromNodeId} → ${t.toNodeId}`))
-console.log('effects:', result.effects?.map(e => `${e.effectId}: ${e.status}`))
-console.log('final node:', result.instance?.currentNodeId)
-console.log('final status:', result.instance?.status)
-
-console.log('\n=== getRemoteData + useAdapter ===')
-// Uses a mock resolver so the demo works without a real endpoint.
-const remoteDataId = bep.data.remoteData[0]!.id
-try {
-  const raw     = await bep.engine.getRemoteData(remoteDataId)
-  const adapted = bep.engine.useAdapter('pick-label-value', raw)
-  console.log('raw data:', raw)
-  console.log('adapted:', adapted)
-} catch (err) {
-  // example.com/stats.json returns HTML — expected in this demo.
-  console.log('(resolver error, expected with placeholder URL):', (err as Error).message)
-}

package/examples/bep.d.ts

@@ -1,38 +0,0 @@
-// Generated by bep.generateTypes() — do not edit manually
-
-// ─── Effects ──────────────────────────────────────────────────────────────────
-
-export interface BepEffects {
-  /** Sends a notification to the assigned reviewer when a model is submitted. Uses the comment from the submit event payload. */
-  'notify-reviewer': (payload: { comment?: string }) => void
-}
-
-// ─── Automations ─────────────────────────────────────────────────────────────
-
-export interface BepAutomations {
-  /** Automatically approves the model if no blocking issues are found in the previous review cycle. */
-  'auto-approve': (payload: { threshold: number }) => { eventId: string; result: string }
-}
-
-// ─── Resolvers ────────────────────────────────────────────────────────────────
-
-export interface BepResolvers {
-  /** Fetches a JSON array from the remote data URL. Authenticates with an API key via Authorization header. Returns the raw parsed array. */
-  'fetch-json': (url: string, env: { API_KEY: string }) => unknown
-}
-
-// ─── Adapters ─────────────────────────────────────────────────────────────────
-
-export interface BepAdapters {
-  /** Maps an array of { name, count } objects to { label, value } pairs compatible with dotbep:pie-chart. */
-  'pick-label-value': (data: unknown) => unknown
-}
-
-// ─── Combined ─────────────────────────────────────────────────────────────────
-
-export interface BepTypes {
-  effects:     BepEffects
-  automations: BepAutomations
-  resolvers:   BepResolvers
-  adapters:    BepAdapters
-}

package/examples/run-all.ts

@@ -1,38 +0,0 @@
-// run: node --experimental-strip-types examples/run-all.ts  (from core/)
-// Runs all examples in sequence. Each example builds on the .bep saved by the previous one.
-// Optional: --NN  runs only examples 01 through NN (e.g. --05 stops after 05-standards).
-import { execSync } from 'node:child_process'
-
-const examples = [
-  '01-participants',
-  '02-files',
-  '03-workflows',
-  '04-bim-uses',
-  '05-standards',
-  '06-schedule',
-  '07-loin',
-  '08-deliverables',
-  '09-notes',
-  '10-llm',
-  '11-resolved',
-  '12-history',
-]
-
-const untilArg = process.argv.find(a => /^--\d{2}$/.test(a))
-const untilPrefix = untilArg ? untilArg.slice(2) : null
-const toRun = untilPrefix ? examples.filter(e => e.slice(0, 2) <= untilPrefix) : examples
-
-for (const ex of toRun) {
-  console.log(`\n${'─'.repeat(60)}`)
-  console.log(`  examples/${ex}.ts`)
-  console.log('─'.repeat(60))
-  execSync(`node --experimental-strip-types examples/${ex}.ts`, {
-    stdio: 'inherit',
-    cwd:   process.cwd(),
-    env:   { ...process.env, DOTBEP_RUN_ALL: '1' },
-  })
-}
-
-console.log(`\n${'─'.repeat(60)}`)
-console.log(untilPrefix ? `  Done (up to ${untilPrefix}).` : '  All examples completed.')
-console.log('─'.repeat(60))

package/src/base/entity.ts

@@ -1,148 +0,0 @@
-import { z, ZodError } from 'zod'
-import type { BEP } from '../types/schema.js'
-import { type ArrayKeys, checkRefs, checkOutgoingRefs } from '../utils/integrity.js'
-
-function errMsg(e: unknown): string {
-  if (e instanceof ZodError)
-    return e.issues.map(i => (i.path.length ? i.path.join('.') + ': ' : '') + i.message).join('; ')
-  return (e as Error).message
-}
-
-export type BulkResult<T> = {
-  succeeded: T[]
-  failed: { id: string; error: string }[]
-}
-
-/** Input type for add() on non-autoId entities — id is optional, validated by the Zod schema */
-export type AddInput<T extends object> = Omit<T, 'id'> & { id?: string }
-
-export type EntityConfig<T extends object, AutoId extends boolean = false> = {
-  /** Key of this entity's array in BEP — used for automatic referential integrity checks */
-  key: ArrayKeys<BEP>
-  /** Field used as the unique identifier. Defaults to 'id' */
-  idField?: keyof T
-  /** Zod schema for this entity — used to validate input on add and merged result on update */
-  schema: z.ZodType<T>
-  /**
-   * When true, a UUID is auto-generated for the id field.
-   * add() will not accept an id in its input — callers capture it from the result.
-   * Use for entities whose id is opaque (not part of nomenclature and not user-facing).
-   */
-  autoId?: AutoId
-  /**
-   * Custom validation called after schema parse (on add) and after merge (on update).
-   * Use for nested reference checks not covered by the standard integrity rules.
-   * Returns a list of error messages; empty array means valid.
-   */
-  validate?: (item: T, bep: BEP) => string[]
-  /** Called before removing an entity, after ref checks pass. Use for custom logic not covered by integrity rules. */
-  beforeRemove?: (id: string, bep: BEP) => void
-}
-
-export class Entity<T extends object, AutoId extends boolean = false> {
-  private idField: keyof T
-
-  constructor(
-    private getItems: () => T[],
-    protected getBep: () => BEP,
-    private config: EntityConfig<T, AutoId>,
-  ) {
-    this.idField = config.idField ?? ('id' as keyof T)
-  }
-
-  private getId(entity: T): string {
-    return String(entity[this.idField])
-  }
-
-  list(): T[] {
-    return this.getItems()
-  }
-
-  get(ids: string[]): BulkResult<T> {
-    const succeeded: T[] = []
-    const failed: { id: string; error: string }[] = []
-    for (const id of ids) {
-      const entity = this.getItems().find(e => this.getId(e) === id)
-      if (entity) succeeded.push(entity)
-      else failed.push({ id, error: `Not found: ${id}` })
-    }
-    return { succeeded, failed }
-  }
-
-  add(inputs: (AutoId extends true ? Omit<T, 'id'> : AddInput<T>)[]): BulkResult<T> {
-    const succeeded: T[] = []
-    const failed: { id: string; error: string }[] = []
-    for (const input of inputs) {
-      const raw = { ...input } as Record<string, unknown>
-      if (this.config.autoId && !raw[this.idField as string])
-        raw[this.idField as string] = globalThis.crypto.randomUUID()
-      const id = String(raw[this.idField as string] ?? '(unknown)')
-      try {
-        const entity = this.config.schema.parse(raw)
-        if (this.getItems().some(e => this.getId(e) === this.getId(entity)))
-          throw new Error(`Already exists: ${this.getId(entity)}`)
-        const outgoing = checkOutgoingRefs(entity as Record<string, unknown>, this.config.key, this.getBep())
-        if (outgoing.length) throw new Error(outgoing.join('; '))
-        const custom = this.config.validate?.(entity, this.getBep()) ?? []
-        if (custom.length) throw new Error(custom.join('; '))
-        this.getItems().push(entity)
-        succeeded.push(entity)
-      } catch (e) {
-        failed.push({ id, error: errMsg(e) })
-      }
-    }
-    return { succeeded, failed }
-  }
-
-  update(patches: ({ [K in keyof T]?: T[K] } & Record<string, unknown>)[]): BulkResult<T> {
-    const succeeded: T[] = []
-    const failed: { id: string; error: string }[] = []
-    for (const patch of patches) {
-      const id = String(patch[this.idField as string])
-      const items = this.getItems()
-      const index = items.findIndex(e => this.getId(e) === id)
-      if (index === -1) {
-        failed.push({ id, error: `Not found: ${id}` })
-        continue
-      }
-      const outgoing = checkOutgoingRefs(patch as Record<string, unknown>, this.config.key, this.getBep())
-      if (outgoing.length) {
-        failed.push({ id, error: outgoing.join('; ') })
-        continue
-      }
-      try {
-        const merged = this.config.schema.parse({ ...items[index], ...patch })
-        const custom = this.config.validate?.(merged, this.getBep()) ?? []
-        if (custom.length) throw new Error(custom.join('; '))
-        items[index] = merged
-        succeeded.push(items[index])
-      } catch (e) {
-        failed.push({ id, error: errMsg(e) })
-      }
-    }
-    return { succeeded, failed }
-  }
-
-  remove(ids: string[]): BulkResult<string> {
-    const succeeded: string[] = []
-    const failed: { id: string; error: string }[] = []
-    for (const id of ids) {
-      const items = this.getItems()
-      const index = items.findIndex(e => this.getId(e) === id)
-      if (index === -1) {
-        failed.push({ id, error: `Not found: ${id}` })
-        continue
-      }
-      try {
-        const active = checkRefs(id, this.config.key, this.getBep())
-        if (active.length) throw new Error(`Referenced by: ${active.join(', ')}`)
-        this.config.beforeRemove?.(id, this.getBep())
-        items.splice(index, 1)
-        succeeded.push(id)
-      } catch (e) {
-        failed.push({ id, error: errMsg(e) })
-      }
-    }
-    return { succeeded, failed }
-  }
-}