CLAUDE.md · diff
git:20260325.1473346 to git:20260326.88c6c14
13 added, 0 removed. Audit A to A.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Commands
```sh
npm install # install dependencies
npm run build # compile TypeScript to dist/
npm run dev # watch mode (rebuild on changes)
npm run type-check # typecheck without emitting
npm run test # run all tests
npx vitest run src/__tests__/output.test.ts # run a single test file
npm run format # biome lint + format (auto-fix)
```
After building, `npm link` makes the `ol` binary available globally.
## Architecture
ESM-only TypeScript CLI using Commander.js. Entry point: `src/index.ts` creates the program and registers four command modules.
### Command pattern
Each file in `src/commands/` exports a `registerXxxCommand(program)` function that defines subcommands with Commander's chaining API. Commands use async action handlers.
### Lib modules
- **api.ts**: Single `apiRequest<T>(path, body)` function. All Outline API calls are POST with Bearer auth. Wraps requests in spinner with per-endpoint messages (SPINNER_MESSAGES map).
- **auth.ts**: Config stored at `~/.config/outline-cli/config.json`. Token/URL resolution: env var → config file → default.
- **output.ts**: `outputItem()` and `outputList()` handle three output modes (human/json/ndjson). Commands define a `humanFormatter` function and an `essentialKeys` array for JSON field filtering.
- **spinner.ts**: `withSpinner(opts, fn)` wrapper using yocto-spinner. Auto-disables on non-TTY, JSON output, CI, `--no-spinner` flag.
- **markdown.ts**: Terminal markdown rendering via marked + marked-terminal.
### Key patterns
- Document IDs are resolved from full URLs or slugs via regex extraction in `resolveId()`.
- Text input for create/update supports `--text` inline or `--file` path, with auto title extraction from markdown headings.
- Delete operations require `--confirm` flag.
## Testing
Vitest with module mocking. Tests live in `src/__tests__/`. Common patterns:
- Mock `apiRequest` with `vi.mock()`
- Stub `fetch` globally for API tests
- Capture `console.log` calls in an array for output assertions
- Use `program.exitOverride()` + `program.parseAsync()` to test command parsing
- Auth tests use tmpdir with `process.pid` for filesystem isolation
+ ## Skill Content (Agent Command Reference)
+
+ The file `src/lib/skills/content.ts` exports `SKILL_CONTENT` — a comprehensive command reference that gets installed into AI agent skill directories via `ol skill install`. This is the source of truth that agents use to understand available CLI commands.
+
+ **Whenever commands, subcommands, flags, or options are added, updated, or removed in `src/commands/`, the `SKILL_CONTENT` in `src/lib/skills/content.ts` must be updated to match.**
+
+ After updating `SKILL_CONTENT`:
+
+ 1. Run `npm run build && npm run sync:skill` to regenerate `skills/outline-cli/SKILL.md` (the standalone skill file used by `npx skills add`)
+ 2. Run `ol skill update claude-code` (and any other installed agents) to propagate changes to installed skill files
+
+ A CI check (`npm run check:skill-sync`) runs on pull requests and will fail if `skills/outline-cli/SKILL.md` is out of sync with `content.ts`.
+
## Style
- Biome: tabs for indentation, auto-sorted imports
- TypeScript strict mode, target ES2022, NodeNext modules
- Avoid `any` types and forced typecasts
- Prefer `for` loops over `.forEach()`