@abraca/orchestrator 2.3.0

package/src/converters/types.ts

@@ -0,0 +1,179 @@
+export interface UserMetaField {
+  id: string
+  type: string
+  label?: string
+  key?: string
+  latKey?: string
+  lngKey?: string
+  startKey?: string
+  endKey?: string
+  allDayKey?: string
+  presets?: string[]
+  options?: string[]
+  min?: number
+  max?: number
+  step?: number
+  unit?: string
+}
+
+export interface PageMeta extends Record<string, unknown> {
+  // Universal display
+  color?: string
+  icon?: string
+  subtitle?: string
+  note?: string
+
+  // Datetime
+  datetimeStart?: string
+  datetimeEnd?: string
+  allDay?: boolean
+  dateStart?: string
+  dateEnd?: string
+  timeStart?: string
+  timeEnd?: string
+
+  // Task/status
+  checked?: boolean
+  priority?: number
+  status?: string
+  taskProgress?: number
+  rating?: number
+  tags?: string[]
+  members?: { id: string; label: string }[]
+
+  // Contact/value
+  url?: string
+  email?: string
+  phone?: string
+  number?: number
+  unit?: string
+
+  // Cover image
+  coverUploadId?: string
+  coverDocId?: string
+  coverMimeType?: string
+
+  // Geo/Map
+  geoType?: 'marker' | 'line' | 'measure'
+  geoLat?: number
+  geoLng?: number
+  geoDescription?: string
+
+  // Whiteboard
+  wbX?: number
+  wbY?: number
+  wbW?: number
+  wbH?: number
+  wbBg?: string
+
+  // Dashboard
+  deskX?: number
+  deskY?: number
+  deskZ?: number
+  deskMode?: string
+
+  // Mindmap
+  mmX?: number
+  mmY?: number
+
+  // Graph
+  graphX?: number
+  graphY?: number
+  graphPinned?: boolean
+  showRefEdges?: boolean
+
+  // Spatial (3D)
+  spShape?: string
+  spColor?: string
+  spOpacity?: number
+  spX?: number
+  spY?: number
+  spZ?: number
+  spRX?: number
+  spRY?: number
+  spRZ?: number
+  spSX?: number
+  spSY?: number
+  spSZ?: number
+  spModelUploadId?: string
+  spModelDocId?: string
+
+  // Slides
+  slidesTransition?: string
+  slidesTheme?: string
+
+  // Media metadata (extracted on import)
+  mediaDuration?: number
+  mediaWidth?: number
+  mediaHeight?: number
+  mediaCamera?: string
+  mediaLens?: string
+  mediaIso?: number
+  mediaFocalLength?: number
+  mediaAperture?: number
+  mediaShutterSpeed?: string
+  mediaArtist?: string
+  mediaAlbum?: string
+  mediaGenre?: string
+  mediaYear?: number
+  dateTaken?: string
+
+  // Sheets cell formatting
+  bold?: boolean
+  italic?: boolean
+  textColor?: string
+  bgColor?: string
+  align?: string
+  formula?: string
+
+  // Renderer config (set on the page doc itself, not children)
+  kanbanColumnWidth?: string
+  galleryColumns?: number
+  galleryAspect?: string
+  galleryCardStyle?: string
+  galleryShowLabels?: boolean
+  gallerySortBy?: string
+  calendarView?: string
+  calendarWeekStart?: string
+  calendarShowWeekNumbers?: boolean
+  tableMode?: string
+  tableSortDir?: string
+  tableColumns?: any[]
+  tableColumnWidths?: Record<string, number>
+  tableColumnOrder?: string[]
+  timelineZoom?: string
+  checklistFilter?: string
+  checklistSort?: string
+  mapShowLabels?: boolean
+  spatialGridVisible?: boolean
+  chartType?: string
+  chartMetric?: string
+  chartColorScheme?: string
+  chartLimit?: number
+  chartShowLegend?: boolean
+  chartShowValues?: boolean
+  mediaRepeat?: string
+  mediaShuffle?: boolean
+  sheetsDefaultColWidth?: number
+  sheetsDefaultRowHeight?: number
+  sheetsShowGridlines?: boolean
+  sheetsColumnWidths?: Record<string, number>
+  sheetsRowHeights?: Record<string, number>
+  sheetsFreezeRows?: number
+  sheetsFreezeCols?: number
+
+  // Internal
+  _metaFields?: UserMetaField[]
+  _metaInitialized?: boolean
+}
+
+export interface TreeEntry {
+  id: string
+  label: string
+  parentId: string | null
+  order: number
+  type?: string
+  meta?: PageMeta
+  createdAt?: number
+  updatedAt?: number
+}

package/src/crypto.ts

@@ -0,0 +1,71 @@
+/**
+ * Ed25519 key generation, persistence, and challenge signing for actor auth.
+ * Copied from packages/mcp/src/crypto.ts
+ */
+import * as ed from '@noble/ed25519'
+import { sha512 } from '@noble/hashes/sha2.js'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+
+// @noble/ed25519 v3 hash hook
+ed.hashes.sha512 = sha512
+ed.hashes.sha512Async = (m: Uint8Array) => Promise.resolve(sha512(m))
+import { existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+function toBase64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64url')
+}
+
+function fromBase64url(b64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(b64, 'base64url'))
+}
+
+export interface AgentKeypair {
+  privateKey: Uint8Array
+  publicKeyB64: string
+}
+
+/**
+ * Load an existing Ed25519 keypair from disk, or generate and persist a new one.
+ */
+export async function loadOrCreateKeypair(keyPath: string): Promise<AgentKeypair> {
+  if (existsSync(keyPath)) {
+    const seed = await readFile(keyPath)
+    if (seed.length !== 32) {
+      throw new Error(`Invalid key file at ${keyPath}: expected 32 bytes, got ${seed.length}`)
+    }
+    const privateKey = new Uint8Array(seed)
+    const publicKey = ed.getPublicKey(privateKey)
+    return { privateKey, publicKeyB64: toBase64url(publicKey) }
+  }
+
+  const privateKey = ed.utils.randomSecretKey()
+  const publicKey = ed.getPublicKey(privateKey)
+
+  const dir = dirname(keyPath)
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+  }
+  await writeFile(keyPath, Buffer.from(privateKey), { mode: 0o600 })
+
+  console.error(`[orchestrator] Generated new keypair at ${keyPath}`)
+  return { privateKey, publicKeyB64: toBase64url(publicKey) }
+}
+
+/**
+ * Generate a deterministic Ed25519 keypair from a seed string (e.g. actor name).
+ * The same seed always produces the same keypair.
+ */
+export function deterministicKeypair(seed: string): AgentKeypair {
+  const hash = sha512(new TextEncoder().encode(seed + ':orchestrator-salt'))
+  const privateKey = hash.slice(0, 32)
+  const publicKey = ed.getPublicKey(privateKey)
+  return { privateKey, publicKeyB64: toBase64url(publicKey) }
+}
+
+/** Sign a base64url challenge with the agent's private key; returns base64url signature. */
+export function signChallenge(challengeB64: string, privateKey: Uint8Array): string {
+  const challenge = fromBase64url(challengeB64)
+  const sig = ed.sign(challenge, privateKey)
+  return toBase64url(sig)
+}

package/src/define.ts

@@ -0,0 +1,147 @@
+/**
+ * Script definition helpers — typed factory functions for building scenes.
+ */
+import type {
+  Scene,
+  ActorDef,
+  ConnectAction,
+  DisconnectAction,
+  NavigateAction,
+  TypeAction,
+  TypeDeleteAction,
+  SelectAction,
+  MoveCursorAction,
+  SetStatusAction,
+  SetAwarenessAction,
+  ClearAwarenessAction,
+  CreateDocumentAction,
+  MoveDocumentAction,
+  RenameDocumentAction,
+  WriteContentAction,
+  DeleteContentAction,
+  SetMetaAction,
+  PointerMoveAction,
+  ScrollToAction,
+  KanbanHoverAction,
+  KanbanDragAction,
+  SendChatAction,
+  WaitAction,
+  ParallelAction,
+  SequenceAction,
+  RepeatAction,
+  TimelineEntry,
+  EasingName,
+} from './types.ts'
+
+/** Define a complete scene. */
+export function defineScene(scene: Scene): Scene {
+  return scene
+}
+
+/** Define an actor. */
+export function actor(name: string, opts: Omit<ActorDef, 'name'>): ActorDef {
+  return { name, ...opts }
+}
+
+/** Factory functions for all action types. */
+export const actions = {
+  connect(): ConnectAction {
+    return { type: 'connect' }
+  },
+
+  disconnect(): DisconnectAction {
+    return { type: 'disconnect' }
+  },
+
+  navigate(docId: string): NavigateAction {
+    return { type: 'navigate', docId }
+  },
+
+  type(docId: string, text: string, opts?: { speed?: number; variance?: number; position?: number }): TypeAction {
+    return { type: 'type', docId, text, ...opts }
+  },
+
+  typeDelete(docId: string, count: number, opts?: { speed?: number; variance?: number; position?: number }): TypeDeleteAction {
+    return { type: 'typeDelete', docId, count, ...opts }
+  },
+
+  select(docId: string, anchor: number, head: number): SelectAction {
+    return { type: 'select', docId, anchor, head }
+  },
+
+  moveCursor(docId: string, from: number, to: number, duration: number, easing?: EasingName): MoveCursorAction {
+    return { type: 'moveCursor', docId, from, to, duration, easing }
+  },
+
+  setStatus(status: string | null): SetStatusAction {
+    return { type: 'setStatus', status }
+  },
+
+  setAwareness(fields: Record<string, unknown>, docId?: string): SetAwarenessAction {
+    return { type: 'setAwareness', docId, fields }
+  },
+
+  clearAwareness(fields: string[], docId?: string): ClearAwarenessAction {
+    return { type: 'clearAwareness', docId, fields }
+  },
+
+  createDocument(parentId: string, label: string, opts?: { docType?: string; meta?: Record<string, unknown>; assignId?: string }): CreateDocumentAction {
+    return { type: 'createDocument', parentId, label, ...opts }
+  },
+
+  moveDocument(docId: string, newParentId: string, order?: number): MoveDocumentAction {
+    return { type: 'moveDocument', docId, newParentId, order }
+  },
+
+  renameDocument(docId: string, label: string): RenameDocumentAction {
+    return { type: 'renameDocument', docId, label }
+  },
+
+  writeContent(docId: string, markdown: string): WriteContentAction {
+    return { type: 'writeContent', docId, markdown }
+  },
+
+  deleteContent(docId: string, from: number, length: number): DeleteContentAction {
+    return { type: 'deleteContent', docId, from, length }
+  },
+
+  setMeta(docId: string, meta: Record<string, unknown>): SetMetaAction {
+    return { type: 'setMeta', docId, meta }
+  },
+
+  pointerMove(docId: string, from: { x: number; y: number }, to: { x: number; y: number }, duration: number, easing?: EasingName): PointerMoveAction {
+    return { type: 'pointerMove', docId, from, to, duration, easing }
+  },
+
+  scrollTo(docId: string, position: number): ScrollToAction {
+    return { type: 'scrollTo', docId, position }
+  },
+
+  kanbanHover(docId: string, cardId: string | null): KanbanHoverAction {
+    return { type: 'kanbanHover', docId, cardId }
+  },
+
+  kanbanDrag(docId: string, cardId: string, toColumnId: string, duration: number): KanbanDragAction {
+    return { type: 'kanbanDrag', docId, cardId, toColumnId, duration }
+  },
+
+  sendChat(channel: string, message: string): SendChatAction {
+    return { type: 'sendChat', channel, message }
+  },
+
+  wait(duration: number): WaitAction {
+    return { type: 'wait', duration }
+  },
+
+  parallel(entries: TimelineEntry[]): ParallelAction {
+    return { type: 'parallel', actions: entries }
+  },
+
+  sequence(entries: TimelineEntry[]): SequenceAction {
+    return { type: 'sequence', actions: entries }
+  },
+
+  repeat(times: number, entries: TimelineEntry[]): RepeatAction {
+    return { type: 'repeat', times, actions: entries }
+  },
+}

package/src/easing.ts

@@ -0,0 +1,15 @@
+/**
+ * Easing functions for animated actions (cursor movement, pointer, etc.)
+ */
+import type { EasingName, EasingFn } from './types.ts'
+
+export const easings: Record<EasingName, EasingFn> = {
+  linear: (t) => t,
+  easeIn: (t) => t * t,
+  easeOut: (t) => t * (2 - t),
+  easeInOut: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
+}
+
+export function getEasing(name?: EasingName): EasingFn {
+  return easings[name ?? 'easeInOut']
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Abracadabra Orchestrator — CouShell commercial director.
+ *
+ * Usage (after pnpm build:packages):
+ *   node --experimental-transform-types \
+ *     packages/orchestrator/dist/abracadabra-orchestrator.esm.js ./scripts/demo.ts
+ *
+ * Dry run:
+ *   node --experimental-transform-types \
+ *     packages/orchestrator/dist/abracadabra-orchestrator.esm.js --dry-run ./scripts/demo.ts
+ */
+import { Orchestrator } from './orchestrator.ts'
+
+// Re-export public API for script files
+export { defineScene, actor, actions } from './define.ts'
+export { Orchestrator } from './orchestrator.ts'
+export type {
+  Scene,
+  ActorDef,
+  ServerConfig,
+  Action,
+  TimelineEntry,
+  ConnectAction,
+  DisconnectAction,
+  NavigateAction,
+  TypeAction,
+  TypeDeleteAction,
+  SelectAction,
+  MoveCursorAction,
+  SetStatusAction,
+  SetAwarenessAction,
+  ClearAwarenessAction,
+  CreateDocumentAction,
+  MoveDocumentAction,
+  RenameDocumentAction,
+  WriteContentAction,
+  DeleteContentAction,
+  SetMetaAction,
+  PointerMoveAction,
+  ScrollToAction,
+  KanbanHoverAction,
+  KanbanDragAction,
+  SendChatAction,
+  RepeatAction,
+  WaitAction,
+  ParallelAction,
+  SequenceAction,
+  EasingName,
+} from './types.ts'
+
+async function main() {
+  const args = process.argv.slice(2)
+  const dryRun = args.includes('--dry-run')
+  const scriptPath = args.find(a => !a.startsWith('--'))
+
+  if (!scriptPath) {
+    console.error('Usage: abracadabra-orchestrator [--dry-run] <script.ts>')
+    console.error('')
+    console.error('  The script file should export a Scene object (use defineScene()).')
+    console.error('')
+    console.error('Options:')
+    console.error('  --dry-run  Validate the scene without connecting to the server')
+    console.error('')
+    console.error('Example:')
+    console.error('  node --conditions=source --experimental-transform-types \\')
+    console.error('    packages/orchestrator/src/index.ts ./scripts/demo.ts')
+    process.exit(1)
+  }
+
+  const orchestrator = new Orchestrator()
+
+  try {
+    await orchestrator.load(scriptPath)
+    orchestrator.prepare()
+
+    if (dryRun) {
+      orchestrator.dryRun()
+    } else {
+      await orchestrator.run()
+    }
+  } catch (err: any) {
+    console.error(`[orchestrator] Fatal: ${err.message}`)
+    process.exit(1)
+  } finally {
+    if (!dryRun) {
+      await orchestrator.cleanup()
+    }
+  }
+}
+
+// Only run CLI when executed directly (not imported as a library)
+// Check if argv[1] points to a file within this package's directory
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+if (process.argv[1]) {
+  const resolved = resolve(process.argv[1])
+  if (resolved.startsWith(__dirname) || resolved.includes('abracadabra-orchestrator')) {
+    main()
+  }
+}

package/src/orchestrator.ts

@@ -0,0 +1,153 @@
+/**
+ * Orchestrator — top-level class that loads a scene, manages actors, and runs the timeline.
+ */
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Scene } from './types.ts'
+import { ActorConnection } from './actor-connection.ts'
+import { TimelineRunner, type ErrorStrategy } from './timeline-runner.ts'
+import { createExecutor } from './actions/index.ts'
+import { log } from './utils.ts'
+
+export class Orchestrator {
+  private scene: Scene | null = null
+  private actors = new Map<string, ActorConnection>()
+  private vars = new Map<string, string>()
+
+  /** Load a scene from a TypeScript file. */
+  async load(scriptPath: string): Promise<void> {
+    const absPath = resolve(scriptPath)
+    const fileUrl = pathToFileURL(absPath).href
+    const mod = await import(fileUrl)
+    const scene: Scene = mod.default ?? mod
+
+    if (!scene.server?.url) {
+      throw new Error('Scene must have server.url')
+    }
+    if (!scene.actors?.length) {
+      throw new Error('Scene must have at least one actor')
+    }
+    if (!scene.timeline?.length) {
+      throw new Error('Scene must have at least one timeline entry')
+    }
+
+    this.scene = scene
+    log(`Loaded scene: ${scene.actors.length} actors, ${scene.timeline.length} timeline entries`)
+  }
+
+  /** Prepare actor connections (does not connect yet — that's a timeline action). */
+  prepare(): void {
+    if (!this.scene) throw new Error('No scene loaded')
+
+    if (this.scene.vars) {
+      for (const [k, v] of Object.entries(this.scene.vars)) {
+        this.vars.set(k, v)
+      }
+    }
+
+    for (const actorDef of this.scene.actors) {
+      if (this.actors.has(actorDef.name)) {
+        throw new Error(`Duplicate actor name: ${actorDef.name}`)
+      }
+      const conn = new ActorConnection(actorDef, this.scene.server)
+      this.actors.set(actorDef.name, conn)
+    }
+
+    log(`Prepared ${this.actors.size} actors: ${[...this.actors.keys()].join(', ')}`)
+  }
+
+  /** Validate the scene without connecting. Logs the timeline structure. */
+  dryRun(): void {
+    if (!this.scene) throw new Error('No scene loaded')
+
+    const actorNames = new Set(this.scene.actors.map(a => a.name))
+    const errors: string[] = []
+
+    for (let i = 0; i < this.scene.timeline.length; i++) {
+      const entry = this.scene.timeline[i]!
+      const prefix = `timeline[${i}]`
+
+      if (entry.actor && !actorNames.has(entry.actor)) {
+        errors.push(`${prefix}: unknown actor "${entry.actor}"`)
+      }
+
+      const needsActor = !['wait', 'parallel', 'sequence', 'repeat'].includes(entry.action.type)
+      if (needsActor && !entry.actor) {
+        errors.push(`${prefix}: ${entry.action.type} requires an actor`)
+      }
+    }
+
+    if (errors.length) {
+      log(`Dry run found ${errors.length} issue(s):`)
+      for (const e of errors) log(`  - ${e}`)
+    } else {
+      log('Dry run: no issues found')
+    }
+
+    // Print timeline summary
+    const sorted = [...this.scene.timeline].sort((a, b) => (a.at ?? 0) - (b.at ?? 0))
+    log('Timeline:')
+    for (const entry of sorted) {
+      const ts = `${((entry.at ?? 0) / 1000).toFixed(1)}s`
+      const actorLabel = entry.actor ?? '—'
+      log(`  [${ts}] ${actorLabel}: ${entry.action.type}`)
+    }
+
+    if (this.scene.duration) {
+      log(`Scene duration: ${(this.scene.duration / 1000).toFixed(1)}s`)
+    }
+  }
+
+  /** Run the timeline. */
+  async run(): Promise<void> {
+    if (!this.scene) throw new Error('No scene loaded')
+
+    // Run onStart hook
+    if (this.scene.onStart) {
+      log('Running onStart hook...')
+      await this.scene.onStart()
+    }
+
+    const executor = createExecutor({
+      actors: this.actors,
+      serverConfig: this.scene.server,
+      vars: this.vars,
+    })
+
+    const runner = new TimelineRunner()
+    log('Starting timeline...')
+    const startTime = Date.now()
+
+    if (this.scene.duration) {
+      // Race timeline against duration timeout
+      const timelinePromise = runner.run(this.scene.timeline, executor)
+      const timeoutPromise = new Promise<void>(resolve => {
+        setTimeout(() => {
+          log(`Scene duration reached (${this.scene!.duration}ms), stopping...`)
+          resolve()
+        }, this.scene.duration)
+      })
+      await Promise.race([timelinePromise, timeoutPromise])
+    } else {
+      await runner.run(this.scene.timeline, executor)
+    }
+
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1)
+    log(`Timeline complete in ${elapsed}s`)
+
+    // Run onEnd hook
+    if (this.scene.onEnd) {
+      log('Running onEnd hook...')
+      await this.scene.onEnd()
+    }
+  }
+
+  /** Disconnect all actors gracefully. */
+  async cleanup(): Promise<void> {
+    const disconnects = [...this.actors.values()].map(a => a.disconnect().catch(() => {}))
+    await Promise.all(disconnects)
+    this.actors.clear()
+    this.vars.clear()
+    log('All actors disconnected')
+  }
+}