document-editor/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

bun install                              # install dependencies
bun run check                            # Biome lint + format (run before committing)
bun test                                 # run all tests
bun test <path>                          # run a single test file
bun run bundle                           # bundle all *-entry.ts files → dist/*.esm.js
uncaged-workflow add <name> <bundle.esm.js>  # register a workflow bundle
uncaged-workflow run <name>              # run a registered workflow

One-time setup for docx-diff binary

cd /Users/yanjiayi/workspace/docx-diff && npm install && npm run build && npm link

The @uncaged scoped packages resolve from a private registry configured in bunfig.toml (https://git.shazhou.work/api/packages/shazhou/npm/).

Architecture

This is a Bun monorepo (workspaces: ["templates/*", "workflows"]) for developing @uncaged/workflow-runtime workflows.

Two layers:

• templates/<name>/ — pure data packages: WorkflowDefinition (roles + ModeratorTable), no agent binding. Exported from src/index.ts.
• workflows/ — binds a template's WorkflowDefinition to an AdapterFn and ExtractFn; each workflow instance is a *-entry.ts file that the bundle script turns into a single dist/*.esm.js.

Bundle script (scripts/bundle.ts): scans workflows/ for *-entry.ts files, bundles each with Bun into dist/<stem>.esm.js (ESM, Node target, no splitting). All @uncaged/workflow-* packages are kept external. Also emits a .d.ts shim per bundle.

Engine loop: ModeratorTable routes from START → role → … → END. Each step: Adapter produces typed meta via the role's Zod schema; engine appends the step and selects the next role.

Core types (from @uncaged/workflow-runtime):

• RoleMeta — Record<string, Record<string, unknown>>: role name → meta shape
• RoleDefinition<Meta> — description, systemPrompt, schema (Zod v4)
• WorkflowDefinition<M> — description + roles + ModeratorTable
• ModeratorTable — declarative, serializable routing table; maps START/role names to ordered transition lists (check + next role or END)
• AdapterFn — receives system prompt + Zod schema, returns a RoleFn
• ExtractFn — resolves structured data from a CAS content hash

Coding Conventions

• type not interface — use type aliases everywhere.
• T | null not ?: — write nullable fields as field: T | null, not field?: T.
• function not class — no classes except third-party requirements or Error subclasses.
• Named exports only — no default exports. Workflow bundles must export run and descriptor by name.
• No console.log — use structured logger in library code.
• No dynamic import() — bundles must be statically analyzable; dynamic imports break hash and loading constraints.
• No import() in business code — the only exception is the engine's own bundle loader.