solpbc.org
open source is social v-it.org
6.4 kB
116 lines
1# CLAUDE.md
2
3Development guidelines for vit, a social toolkit for personalized software built with Bun.
4
5## Project Overview
6
7vit is a Node CLI for discovering, vetting, remixing, and shipping software capabilities:
8- `vit login`, `vit init`, `vit doctor` — authentication and environment setup
9- `vit beacon`, `vit config` — project beacon inspection and user configuration
10- `vit firehose` — listen to Jetstream for cap events
11- `vit ship`, `vit skim` — publish and read caps
12
13Source layout:
14- `bin/vit.js` - executable entrypoint
15- `src/cli.js` - root Commander program
16- `src/cmd/` - subcommand modules
17- `src/lib/` - shared helpers
18
19## Commands
20
21```bash
22make install # Install dependencies with bun
23make test # Run tests with bun
24make clean # Remove node_modules
25```
26
27## Development Principles
28
29- **Simple code** - Prefer plain functions. Keep scripts self-contained.
30- **DRY, KISS** - Extract common logic, prefer simple solutions.
31- **YAGNI** - Don't build for cases that don't exist yet; no speculative flags, options, or abstractions. No backwards-compatibility shims — update call sites directly when you rename or move something.
32- **Fail fast** - Validate inputs and external state early. Clear error messages. Surface failures, don't swallow them into a success-looking result.
33- **Verify before you claim** - Recall is a hypothesis, not evidence. Verify atproto/Jetstream behavior, an API shape, or a dependency's defaults against the live source before it lands in code or a commit — a quick check beats a reversal. Contract tests round-trip the real serialization boundary, not a mock of both sides.
34- **Vocabulary alignment** - `VOCAB.md` is the source of truth for all project terminology. All project descriptions, CLI help strings, documentation, and skill files must use terminology consistent with VOCAB.md. When VOCAB.md is updated, propagate changes to every file that references vit's vocabulary in the same commit.
35
36## Testing Standards
37
381. **No real home access** — tests must never read or write `~/.local`, `~/.config`, `~/.claude`, or any path under the real `$HOME`. Use `HOME` and `XDG_CONFIG_HOME` env overrides to redirect to temp dirs.
392. **No live HTTP** — tests must not make requests to external hosts (`github.com`, `explore.v-it.org`, etc.). Use `Bun.serve()` local servers with canned responses, or `mock.module()` for dependencies that make HTTP calls.
403. **No global mutation** — tests must not call `process.chdir()`. Pass directory arguments to functions instead. If `process.chdir` is unavoidable, wrap in `try/finally`.
414. **Temp dir lifecycle** — create temp dirs with `join(tmpdir(), '.test-{name}-{random}')` in `beforeEach`, clean up with `rmSync(dir, { recursive: true, force: true })` in `afterEach`.
425. **Subprocess isolation** — tests using `run()` isolate via env overrides and CLI flags. In-process tests may use `mock.module()` only when env/flag isolation is impossible (e.g., mocking `isomorphic-git` in beacon tests).
43
44## Verification
45
46- Always run `make test` before committing — all tests must pass.
47- Hand-test affected CLI commands (`./bin/vit.js <command>`) to verify behavior beyond what tests cover.
48
49## Releasing
50
51Every commit that changes files in `bin/` or `src/` — the packaged CLI code — **must** be followed by a release and publish to npm:
52
53```bash
54make ship # bump patch version, tag, push, publish to npm
55make ship BUMP=minor # for new commands or features
56make ship BUMP=major # for breaking changes
57```
58
59**This is non-negotiable.** If your commit touches `bin/` or `src/`, run `make ship` before you're done. Use `patch` (default) for fixes and small improvements, `minor` for new commands or features, `major` for breaking changes.
60
61`make ship` runs tests, bumps the version in `package.json`, creates a git commit and tag (`vX.Y.Z`), pushes to origin, and publishes to npm — all in one step.
62
63Individual targets if needed:
64- `make release` — test, bump, commit, tag, push (no npm publish)
65- `make publish` — npm publish only (assumes version is already bumped)
66
67## Hosting
68
69This repo contains three deployable things:
70
71| what | directory | domain | deploy |
72|------|-----------|--------|--------|
73| CLI | `bin/`, `src/` | npm `vit` | `make ship` |
74| site | `docs/` (served by `site/`) | v-it.org | `make deploy-site` |
75| explore | `explore/` | explore.v-it.org | `make deploy-explore` |
76
77**The site does NOT auto-deploy.** After changing anything in `docs/` (pages, decks, assets), you must run `make deploy-site` to publish. Both site and explore are Cloudflare Workers — deployment requires a `wrangler login` OAuth session.
78
79## File Headers
80
81All JS source files must include this header immediately after the shebang line:
82
83```
84// SPDX-License-Identifier: MIT
85// Copyright (c) 2026 sol pbc
86```
87
88Add this header to `.js` files in `bin/` and `src/`. Do not add headers to docs/, node_modules/, or non-source files.
89
90## Skills
91
92Agent skills for this project live in `skills/`. When authoring or updating skills, follow the [Claude agent skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices):
93
94- Keep SKILL.md concise — under 500 lines. Only add context Claude doesn't already have.
95- Use progressive disclosure: essentials inline, details in referenced files one level deep.
96- Use gerund or action-oriented naming (lowercase-hyphens only) for skill names.
97- Write descriptions in third person that specify both what the skill does and when to use it.
98- Test with all target models (Haiku, Sonnet, Opus) as effectiveness varies.
99
100## Dogfooding
101
102Ship meaningful work as caps. Use `vit ship` after completing a feature, fix, or improvement — not for typos or formatting.
103
104```
105vit ship --title "Short Title" --description "One sentence of value." --ref "three-word-slug" --kind feat <<'EOF'
106Body paragraph explaining what the cap does and how it works.
107EOF
108```
109
110Flags:
111- `--title`: concise noun phrase (2–5 words)
112- `--description`: one sentence explaining the value
113- `--ref`: three lowercase hyphenated words — a memorable discovery slug
114- `--kind`: one of `feat`, `fix`, `test`, `docs`, `refactor`, `chore`, `perf`, `style`
115- `--recap <ref>`: link to a prior cap this one derives from (e.g. after `vit remix`)
116- Body (stdin): short paragraph for another developer or agent who might adopt it