inside repo

Overview

This repo’s core is a TypeScript DSL that transpiles directly into executable, type‑safe RxJS code. Agents will ultimately generate DSL programs and orchestrate sub‑agents, but today the DSL → transpilation → generated code pipeline is the mature foundation.

Scope & Status

• Core: DSL authoring, transpilation, and generated code checks are working
• Supporting: storage clients and Anthropic client are scaffolding for future integration
• Focus: reliability primitives (retry/backoff/recover) and composable, testable workflows

Setup (per‑project tools)

• Use mise to pin tools locally (no globals):
  • bun (runtime, test runner, bundler)
  • just (task runner)

# inside repo
mise use bun latest
mise use just latest
mise install

If using Homebrew instead: brew install bun just.

Developer Workflow

• Author check: just dsl-check-author examples/risk_pipe.ts
• Transpile: just dsl-transpile examples/risk_pipe.ts ./.tmp/risk_pipe.gen.ts
• Generated check: just dsl-check-generated ./.tmp/risk_pipe.gen.ts
• Tests: just test (set POC_AGENT_DSL=1 to run only PoC tests)
• UUID benchmarks: UUID_BENCHMARK_TESTS=1 just bench-id (intensive performance tests)
• UUID randomness analysis: UUID_RANDOMNESS_TESTS=1 just analyze-id-randomness (intensive crypto tests)

Debugging with Bun + VS Code

Bun exposes a WebKit‑Inspector compatible with VS Code and a web debugger at debug.bun.sh.

Prereqs

• Bun ≥ 1.x (bun --version)
• VS Code “Bun for Visual Studio Code” extension
• "sourceMap": true in tsconfig.json

Just commands

• All tests, wait for attach

  just debug-tests
  

• Single test file

  just debug-tests-file tests/append.azurite.test.ts
  

Both commands start bun test with --inspect-wait=6499, pausing until the debugger attaches.

VS Code

1. Use the "Attach: Bun tests (port 6499)" config to attach.
2. Set breakpoints in .ts files; run continues on attach.

Tip: If attach is flaky on your platform, run bun test --inspect=6499 and follow the printed debug.bun.sh link.

Ports & alternatives

• Change the inspector port by editing the just recipes, e.g. --inspect-wait=9230.
• For “break on first line”, replace with --inspect-brk=PORT.

Supporting Infrastructure (Optional)

An Azure Append Blob client and Azurite setup exist to support future storage operations and end‑to‑end demos. They are not the primary focus of the DSL pipeline. If you need Azurite to run blob‑related tests locally, consult the test files for connection string usage (AZURE_STORAGE_CONNECTION_STRING=UseDevelopmentStorage=true).

Intensive Tests (Opt-in)

Some tests are computationally intensive and disabled by default:

• UUID Benchmark Tests: Performance validation (500K+ UUIDs/second claims). Enable with UUID_BENCHMARK_TESTS=1
• UUID Randomness Tests: Cryptographic randomness quality analysis. Enable with UUID_RANDOMNESS_TESTS=1
• PoC Tests: Core DSL pipeline tests only. Enable with POC_AGENT_DSL=1

These flags follow the same pattern as AZURE_STORAGE_CONNECTION_STRING - set the environment variable to enable specific test suites.

CRITICAL: There must be no scripts in package.json. just and the justfile are the single source of truth for tasks.