Skip to content

REASONIX.md

Latest commit

 

History

History
73 lines (61 loc) · 3.61 KB

REASONIX.md

File metadata and controls

73 lines (61 loc) · 3.61 KB

Reasonix — working knowledge

TypeScript project. DeepSeek-native coding agent, cache-first loop. MIT-licensed. Node ≥22 required.

Stack

  • Language — TS 5.6+, ES2022, ESM ("type": "module")
  • CLI — Commander.js + Ink 5 (React 18) TUI
  • Test — Vitest 2.x
  • Lint / Format — Biome 1.9 (2-space, double quotes, semicolons always, 100 width)
  • Build — tsup (bundle), tsx (dev runner)
  • MCP — stdio + SSE transports, in-process fake in tests

Layout

Path What
src/cli/ CLI entry + commands (chat.tsx, code.tsx, diff.ts, etc.) + Ink TUI in ui/
src/tools/ Tool defs (filesystem, shell, MCP, plan, subagent, web, workspace)
src/mcp/ MCP client, transports (stdio, SSE), registry, spec
src/repair/ Tool-call repair pipeline (flatten, scavenge, storm, truncation)
src/index/ Semantic vector index
src/code/ SEARCH/REPLACE edit-block parser + apply gate
src/core/ Event-log kernel — events.ts (Event union), reducers.ts (pure projections), eventize.ts
src/ports/ Port interfaces — ModelClient, ToolHost, EventSink, MemoryStore, HookRunner, CheckpointStore
src/adapters/ Concrete adapters for the ports (e.g. event-sink-jsonl.ts, event-source-jsonl.ts)
src/frame/ Frame compiler (cell grid → ANSI) used by the TUI log renderer
src/memory/ Project / session / user / runtime memory stores
src/transcript/ Transcript log (write), diff, replay
src/telemetry/ Usage records + cross-session stats
src/server/ Dashboard HTTP server + REST API
tests/ Vitest tests, flat *.test.ts
examples/ basic-chat.ts, mcp-server-demo.ts, etc.
benchmarks/ Harvest + tau-bench harnesses
dashboard/ Compiled dashboard SPA assets
data/ Tokenizer data (deepseek-tokenizer.json.gz)
dist/ Build output — do not edit
.github/ CI + issue / PR templates

Commands

npm run build       # tsup → dist/
npm run dev         # tsx src/cli/index.ts
npm run chat        # tsx src/cli/index.ts chat
npm run test        # vitest run
npm run test:watch  # vitest
npm run lint        # biome check src tests
npm run lint:fix    # biome check --write src tests
npm run format      # biome format --write src tests
npm run typecheck   # tsc --noEmit

prepublishOnly: lint → typecheck → test → build.

Conventions

  • Imports — explicit import type for type-only imports (Biome useImportType: warn). Direct relative imports within project, no barrel re-exports.
  • Exports — named exports only; no export default. Entry: src/index.ts.
  • Tests — vitest describe/it/expect, no globals. Naming: <module>.test.ts flat in tests/.
  • JSX — .tsx for Ink components. jsx: "react" in tsconfig.
  • TypeScript — strict, noUncheckedIndexedAccess, noImplicitOverride. Tools accept ToolCallContext (abort signal).
  • MCP — All transports implement McpTransport interface. Tools registered via registry at startup.
  • Changelog — Keep a Changelog format. Semver.

Watch out for

  • This IS Reasonix — edits to src/loop.ts, src/repair/, src/tools/, src/mcp/ affect every session. Test before publishing.
  • SEARCH must match byte-for-byte — the edit-gate in src/code/edit-blocks.ts enforces exact match. Trailing whitespace or wrong indent = mismatch.
  • dist/ is generated by tsup. Never hand-edit.
  • .reasonix/semantic/ is auto-generated vector index. Never hand-edit.
  • sessions/ and .reasonix/sessions/ are user-private, git-ignored (per .gitignore).