solpbc.org
open source is social v-it.org
5.8 kB
114 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 Bun 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- **Fail fast** - Validate inputs and external state early. Clear error messages.
32- **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.
33
34## Testing Standards
35
361. **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.
372. **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.
383. **No global mutation** — tests must not call `process.chdir()`. Pass directory arguments to functions instead. If `process.chdir` is unavoidable, wrap in `try/finally`.
394. **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`.
405. **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).
41
42## Verification
43
44- Always run `make test` before committing — all tests must pass.
45- Hand-test affected CLI commands (`./bin/vit.js <command>`) to verify behavior beyond what tests cover.
46
47## Releasing
48
49Every commit that changes files in `bin/` or `src/` — the packaged CLI code — **must** be followed by a release and publish to npm:
50
51```bash
52make ship # bump patch version, tag, push, publish to npm
53make ship BUMP=minor # for new commands or features
54make ship BUMP=major # for breaking changes
55```
56
57**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.
58
59`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.
60
61Individual targets if needed:
62- `make release` — test, bump, commit, tag, push (no npm publish)
63- `make publish` — npm publish only (assumes version is already bumped)
64
65## Hosting
66
67This repo contains three deployable things:
68
69| what | directory | domain | deploy |
70|------|-----------|--------|--------|
71| CLI | `bin/`, `src/` | npm `vit` | `make ship` |
72| site | `docs/` (served by `site/`) | v-it.org | `make deploy-site` |
73| explore | `explore/` | explore.v-it.org | `make deploy-explore` |
74
75**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.
76
77## File Headers
78
79All JS source files must include this header immediately after the shebang line:
80
81```
82// SPDX-License-Identifier: MIT
83// Copyright (c) 2026 sol pbc
84```
85
86Add this header to `.js` files in `bin/` and `src/`. Do not add headers to docs/, node_modules/, or non-source files.
87
88## Skills
89
90Agent 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):
91
92- Keep SKILL.md concise — under 500 lines. Only add context Claude doesn't already have.
93- Use progressive disclosure: essentials inline, details in referenced files one level deep.
94- Use gerund or action-oriented naming (lowercase-hyphens only) for skill names.
95- Write descriptions in third person that specify both what the skill does and when to use it.
96- Test with all target models (Haiku, Sonnet, Opus) as effectiveness varies.
97
98## Dogfooding
99
100Ship meaningful work as caps. Use `vit ship` after completing a feature, fix, or improvement — not for typos or formatting.
101
102```
103vit ship --title "Short Title" --description "One sentence of value." --ref "three-word-slug" --kind feat <<'EOF'
104Body paragraph explaining what the cap does and how it works.
105EOF
106```
107
108Flags:
109- `--title`: concise noun phrase (2–5 words)
110- `--description`: one sentence explaining the value
111- `--ref`: three lowercase hyphenated words — a memorable discovery slug
112- `--kind`: one of `feat`, `fix`, `test`, `docs`, `refactor`, `chore`, `perf`, `style`
113- `--recap <ref>`: link to a prior cap this one derives from (e.g. after `vit remix`)
114- Body (stdin): short paragraph for another developer or agent who might adopt it