core-development

7nohe's avatarfrom 7nohe

Work on the core package (types, validation, normalization, diff). Use when modifying DSL processing logic or data flow.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

When & Why to Use This Skill

The Core Development skill is designed to assist developers in managing and evolving the foundational logic of DSL-driven systems. It specializes in TypeScript type definitions, YAML validation, data normalization, and complex diffing algorithms, ensuring a robust and scalable data flow from raw input to system patches.

Use Cases

  • Extending the Domain Specific Language (DSL) by adding new node or edge properties with corresponding validation and normalization rules.
  • Optimizing the core diffing algorithm to handle complex state transitions and generate efficient patch operations.
  • Refactoring the Intermediate Representation (IR) to support new architectural requirements while maintaining type safety across the package.
  • Implementing and testing WebSocket protocol updates to ensure reliable real-time communication between system components.
namecore-development
descriptionWork on the core package (types, validation, normalization, diff). Use when modifying DSL processing logic, adding new node/edge properties, changing validation rules, or updating the diff algorithm.

Core Package Development

The core package (packages/core/) is dependency-free and handles all DSL processing.

Data Flow

DSL (YAML input) → validate() → normalize() → IR → diff() → Patch

Key Files

File Purpose Exports
types.ts Type definitions DSL*, IR*, Patch, WebSocket protocol
validate.ts YAML validation validate(dsl): ValidationResult
normalize.ts DSL → IR conversion normalize(dsl): IRDocument
diff.ts IR diff calculation diff(prev, next): Patch

Type Hierarchy

DSL Types (user input)      IR Types (normalized)
─────────────────────       ────────────────────
DSLDocument                 IRDocument
  ├─ version: number          ├─ version: number
  ├─ docId: string            ├─ docId: string
  ├─ title?: string           ├─ title: string
  ├─ nodes: DSLNode[]         ├─ nodes: Record<string, IRNode>
  └─ edges?: DSLEdge[]        └─ edges: Record<string, IREdge>

DSLNode                     IRNode
  ├─ id: string               ├─ id: string
  ├─ provider: string         ├─ provider: string
  ├─ kind: string             ├─ kind: string
  ├─ label?: string           ├─ label: string (default: id)
  ├─ parent?: string          ├─ parent: string | null
  └─ layout: DSLLayout        └─ layout: { x, y, w, h }

DSLEdge                     IREdge
  ├─ id: string               ├─ id: string
  ├─ from: string             ├─ from: string
  ├─ to: string               ├─ to: string
  └─ label?: string           └─ label: string (default: "")

Patch Operations

type PatchOp =
  | { op: "upsertNode"; node: IRNode }
  | { op: "removeNode"; id: string }
  | { op: "upsertEdge"; edge: IREdge }
  | { op: "removeEdge"; id: string };

interface Patch {
  baseRev: number;
  nextRev: number;
  ops: PatchOp[];
}

WebSocket Protocol Types

// Plugin → CLI
interface HelloMessage {
  type: "hello";
  docId: string;
  secret?: string;
}

interface RequestFullMessage {
  type: "requestFull";
  docId: string;
}

// CLI → Plugin
interface FullMessage {
  type: "full";
  rev: number;
  ir: IRDocument;
}

interface PatchMessage {
  type: "patch";
  baseRev: number;
  nextRev: number;
  ops: PatchOp[];
}

interface ErrorMessage {
  type: "error";
  message: string;
}

Development Workflow

  1. Modify types → Update types.ts
  2. Update validation → Ensure validate.ts catches invalid input
  3. Update normalization → Handle new fields/defaults in normalize.ts
  4. Update diff → Handle new patch scenarios in diff.ts
  5. Add tests → Co-located *.test.ts files
  6. Run tests → bun test packages/core/

Testing

# All core tests
bun test packages/core/

# Specific test file
bun test packages/core/src/diff.test.ts
bun test packages/core/src/validate.test.ts
bun test packages/core/src/normalize.test.ts

# Watch mode
bun test --watch packages/core/

Common Patterns

Adding a new node property

  1. Add to DSLNode and IRNode in types.ts
  2. Add validation in validate.ts
  3. Add default value handling in normalize.ts
  4. Update diff logic if property affects equality
  5. Add test cases for validation, normalization, and diff

Adding a new edge property

  1. Add to DSLEdge and IREdge in types.ts
  2. Add validation in validate.ts
  3. Add default value handling in normalize.ts
  4. Update diff logic for edge equality check
  5. Add test cases