markbennett.ca
WIP: A simple cli for daily tangled use cases and AI integration. This is for my personal use right now, but happy if others get mileage from it! :)
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Commands
6
7```bash
8npm run dev -- <args> # Run CLI in development (use this, not ./tangled)
9npm run build # Compile TypeScript to dist/
10npm test # Run all tests once
11npm run test:watch # Run tests in watch mode
12npm run typecheck # Type-check without building (prefer over npx tsc --noEmit)
13npm run lint # Check with Biome
14npm run lint:fix # Auto-fix lint/format issues
15```
16
17Run a single test file:
18```bash
19npx vitest run tests/commands/issue.test.ts
20```
21
22## Architecture
23
24`src/index.ts` is the entry point — it registers all commands and parses `process.argv`.
25
26### Layer structure
27
28- **`src/commands/`** — Commander.js command factories (e.g. `createIssueCommand()`). Each command: resumes session, gets repo context, calls lib functions, outputs results.
29- **`src/lib/`** — Business logic with no Commander dependency:
30 - `api-client.ts` — `TangledApiClient` wraps `AtpAgent`; `isAuthenticated()` is **synchronous**
31 - `session.ts` — OS keychain storage via `@napi-rs/keyring`; throws `KeychainAccessError` if keychain is inaccessible (not just missing)
32 - `context.ts` — Infers repo from `git remote` URLs; resolves `RepositoryContext` with owner DID/handle and repo name
33 - `issues-api.ts` — All issue CRUD; exports `IssueData` (canonical JSON shape), `getCompleteIssueData`, `resolveSequentialNumber`
34- **`src/utils/`** — Stateless helpers:
35 - `auth-helpers.ts` — `requireAuth(client)` throws if unauthenticated (use in lib functions); `ensureAuthenticated(client)` for commands (calls `resumeSession`, exits on failure)
36 - `validation.ts` — **All** validation logic lives here (Zod schemas + boolean helpers)
37 - `formatting.ts` — `outputJson<T extends object>(data, fields?)`, `formatDate`, `formatIssueState`
38 - `at-uri.ts` — Parse/build AT-URIs and repo AT-URIs
39 - `body-input.ts` — Reads `--body` / `--body-file` / stdin (`-F -`)
40- **`src/lexicon/`** — Auto-generated AT Protocol type definitions; regenerate with `npm run codegen`
41
42### Key patterns
43
44**Issue numbering** — Sequential numbers are not stored; they are computed by sorting all issues for a repo by `createdAt` ascending. The 1-based index is the display number.
45
46**Issue state** — Stored as separate `sh.tangled.repo.issue.state` records. The latest record wins; default is `'open'` if no record exists.
47
48**JSON output** — All issue sub-commands use `IssueCommand extends Command` (in `issue.ts`) to share a `--json [fields]` option. The canonical field set is: `number, title, body, state, author, createdAt, uri, cid`. Use `getCompleteIssueData()` to populate all fields.
49
50**Auth flow** — Commands call `client.resumeSession()` directly, then proceed. Lib functions call `requireAuth(client)`. `KeychainAccessError` from `session.ts` propagates through `resumeSession()` without clearing metadata.
51
52### Tests
53
54Tests mirror `src/` under `tests/`. Command tests mock the entire `issuesApi` module:
55```typescript
56vi.mock('../../src/lib/issues-api.js');
57// Use importOriginal to preserve exported classes/errors if needed
58```
59`isAuthenticated()` is synchronous — mock as `vi.fn(() => true)`, not `vi.fn(async () => true)`.
60
61### Version Control
62
63* Use small meaningful commits with clear messages.
64* Break work down into logical steps, committing each step separately.
65* Use feature branches when addressing issues. Include the issue number and a description of changes in the branch name (e.g., `issue-123-fix-auth`).
66* When work is complete push commits to remote and open a pull request for review. Include the issue number and a description of changes in the PR title (e.g., `Fix authentication flow for issue #123`).