mirror of https://github.com/AgentSeal/codeburn.git synced 2026-05-17 03:56:45 +00:00

Add CONTRIBUTING.md, docs/architecture.md, and per-provider docs (#284 )

Document the contributor onboarding path:
- CONTRIBUTING.md: setup, npm scripts, coding conventions, PR process,
  the block-claude-coauthor enforcement, and the five providers without
  test coverage today (claude, gemini, goose, qwen, antigravity).
- docs/architecture.md: 12-command CLI surface, parser pipeline, three
  cache layers, 14 optimize detectors, and the mac / gnome / build
  layouts with cited line numbers.
- docs/providers/: one file per provider (17 providers plus the shared
  vscode-cline-parser helper). Each covers data path, storage format,
  caching, dedup key, quirks, and a "when fixing a bug here" checklist.

Also fix two pre-existing documentation issues surfaced while writing
the new docs:
- RELEASING.md claimed GitHub Actions auto-publishes the CLI when a
  v* tag is pushed. There is no such workflow; CLI publishing is
  manual via npm publish. Updated the CLI section to reflect reality
  and kept the menubar (mac-v* tag) automation accurate.
- .gitignore had CLAUDE.md unanchored, which on case-insensitive
  filesystems also matched docs/providers/claude.md. Anchored to
  /CLAUDE.md so the root-level memory file stays ignored without
  affecting subdirectory docs.

All cited file paths, line numbers, function names, and test counts
were verified against current code (41 test files, 558 tests passing).

2026-05-09 18:39:41 -07:00

2.4 KiB

Raw Permalink Blame History

Antigravity

Google Antigravity. The only provider that does not read files off disk: it speaks to a local language-server RPC endpoint instead.

Source: src/providers/antigravity.ts
Loading: lazy (src/providers/index.ts:14-27). Lazy because the protobuf dependency is heavy.
Test: none. Mocking the RPC endpoint cleanly is the open issue.

Where it reads from

A local HTTPS RPC endpoint exposed by Antigravity's language server. The parser:

Locates the running language-server process via ps.
Reads its port and CSRF token from process metadata.
Calls GetCascadeTrajectoryGeneratorMetadata over HTTPS.
Validates the response (capped at 5-15 MB depending on cascade size).

If the language server is not running, the parser falls back to the cached results file (antigravity.ts:262-272).

Storage format

Protobuf. Cascade and response objects map to ParsedProviderCall directly; see antigravity.ts:299-323.

Caching

Custom file cache at $CODEBURN_CACHE_DIR/antigravity-results.json (defaults to ~/.cache/codeburn/). The version constant is at antigravity.ts:12; the cache machinery (loadCache, flushCache) lives in antigravity.ts:75-125. The cache is also used as the data source when the RPC endpoint is unavailable, not just as an optimization. Bumping the cache version forces a recompute.

Deduplication

Per <cascadeId>:<responseId> (antigravity.ts:308).

Quirks

Antigravity is the only provider that requires a live process. A user who closes Antigravity loses the most-recent data until next launch (the cache covers older runs).
The 5-15 MB cap on RPC responses is necessary because individual cascades can balloon. Raising it risks OOM on the user's machine.
Token types are split across inputTokens, responseOutputTokens, and thinkingOutputTokens (antigravity.ts:313-323). Thinking is billed at output rate.

When fixing a bug here

Reproducing requires Antigravity running locally. There is no fixture for the RPC, which is a real testing gap.
Before any change, capture a sample protobuf response (anonymized) so future regressions can be tested against a recording.
If the bug is "no data after Antigravity update", the protobuf schema may have shifted. The parser's response handling at antigravity.ts:299-323 is the place to look.
If the bug is "stale data", check whether the RPC is reachable; the cache fallback can mask connectivity issues.

2.4 KiB Raw Permalink Blame History