CLI Development Patterns
Tech Stack
- Runtime: Node.js 20+
- Language: TypeScript 5+
- CLI Framework: cac
- Prompts: @inquirer/prompts
- Testing: vitest
- Build: tsc + tsc-alias (no bundler)
Project Structure
epost-agent-kit-cli/ (standalone repo at /Users/than/Projects/epost-agent-kit-cli)
├── src/
│ ├── cli.ts — Entry point, cac setup + fuzzy command suggestions
│ ├── commands/ — Command implementations (init, onboard, update, doctor, lint, fix-refs, verify)
│ ├── domains/ — Domain-driven modules
│ │ ├── health-checks/ — integrity-checker, skill-health-checks, doctor checks
│ │ ├── packages/ — package-resolver, profile-loader
│ │ ├── validation/ — ref-validator (lint + fix-refs)
│ │ └── ...
│ ├── services/ — File operations, template engine, transformers
│ ├── shared/ — Cross-cutting: logger, file-system, constants, path-resolver
│ └── types/ — TypeScript interfaces (PackageManifest, FileOwnership, etc.)
├── tests/
│ ├── unit/ — Unit tests by domain
│ └── integration/ — Integration tests for commands
├── dist/ — Compiled output
└── package.json
Key Commands
lint — Validate references across installed agent/skill/command markdown filesfix-refs — Auto-fix stale references using rename maps from package.yaml (--apply to write)verify — Full pre-release audit: integrity + lint + health checks + dependency graph (--strict, --json)doctor — Verify installation and environment healthinit — Initialize epost-agent-kit in existing project
Key Conventions
- Custom lightweight YAML parser (
parseSimpleYaml() in package-resolver.ts) — no js-yaml dependency
- File ownership tracking with SHA256 checksums (
.epost-metadata.json)
- Settings merge strategies: base (overwrite), merge (deep), skip (no-op)
- Profile-based package selection via
profiles/profiles.yaml
- Topological sort for dependency resolution (layer-based install order)
- Skill index auto-generation from installed SKILL.md files
- Import paths use
@/ alias (e.g., @/shared/logger.js, @/domains/packages/package-resolver.js)
Testing
- Unit tests with vitest
- Run:
cd /Users/than/Projects/epost-agent-kit-cli && npm test
1---2name: kit-cli3description: (ePost) Use when developing the epost-kit CLI — cac commands, @inquirer/prompts, vitest tests, TypeScript patterns4---5
6# CLI Development Patterns
7
8## Tech Stack
9- **Runtime**: Node.js 20+
10- **Language**: TypeScript 5+
11- **CLI Framework**: cac
12- **Prompts**: @inquirer/prompts
13- **Testing**: vitest
14- **Build**: tsc + tsc-alias (no bundler)
15
16## Project Structure
17
18```
19epost-agent-kit-cli/ (standalone repo at /Users/than/Projects/epost-agent-kit-cli)
20├── src/
21│ ├── cli.ts — Entry point, cac setup + fuzzy command suggestions
22│ ├── commands/ — Command implementations (init, onboard, update, doctor, lint, fix-refs, verify)
23│ ├── domains/ — Domain-driven modules
24│ │ ├── health-checks/ — integrity-checker, skill-health-checks, doctor checks
25│ │ ├── packages/ — package-resolver, profile-loader
26│ │ ├── validation/ — ref-validator (lint + fix-refs)
27│ │ └── ...
28│ ├── services/ — File operations, template engine, transformers
29│ ├── shared/ — Cross-cutting: logger, file-system, constants, path-resolver
30│ └── types/ — TypeScript interfaces (PackageManifest, FileOwnership, etc.)
31├── tests/
32│ ├── unit/ — Unit tests by domain
33│ └── integration/ — Integration tests for commands
34├── dist/ — Compiled output
35└── package.json
36```
37
38## Key Commands
39- `lint` — Validate references across installed agent/skill/command markdown files
40- `fix-refs` — Auto-fix stale references using rename maps from package.yaml (`--apply` to write)
41- `verify` — Full pre-release audit: integrity + lint + health checks + dependency graph (`--strict`, `--json`)
42- `doctor` — Verify installation and environment health
43- `init` — Initialize epost-agent-kit in existing project
44
45## Key Conventions
46- Custom lightweight YAML parser (`parseSimpleYaml()` in package-resolver.ts) — no js-yaml dependency
47- File ownership tracking with SHA256 checksums (`.epost-metadata.json`)
48- Settings merge strategies: base (overwrite), merge (deep), skip (no-op)
49- Profile-based package selection via `profiles/profiles.yaml`
50- Topological sort for dependency resolution (layer-based install order)
51- Skill index auto-generation from installed SKILL.md files
52- Import paths use `@/` alias (e.g., `@/shared/logger.js`, `@/domains/packages/package-resolver.js`)
53
54## Testing
55- Unit tests with vitest
56- Run: `cd /Users/than/Projects/epost-agent-kit-cli && npm test`
majiayu000