Skip to content

Commit c06c41e

Browse files
jdaltonjdalton
committed
docs: add coverage badges and onboarding guide
- Add test coverage (90%) and type coverage (95%) badges to README - Create comprehensive onboarding guide for CLI contributors - Guide covers: monorepo structure, package organization, commands, binary builds Tailored for monorepo complexity with clear navigation paths.
1 parent 30231ae commit c06c41e

File tree

2 files changed

+325
-0
lines changed

2 files changed

+325
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
[![Socket Badge](https://socket.dev/api/badge/npm/package/socket)](https://socket.dev/npm/package/socket)
44
[![CI](https://github.com/SocketDev/socket-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-cli/actions/workflows/ci.yml)
5+
![Test Coverage](https://img.shields.io/badge/test--coverage-90%25-brightgreen)
6+
![Type Coverage](https://img.shields.io/badge/type--coverage-95%25-brightgreen)
57

68
[![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
79

‎docs/onboarding-guide.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
# Onboarding Guide
2+
3+
**New Contributor Quickstart** — Get started with Socket CLI development in 10 minutes.
4+
5+
---
6+
7+
## 📋 Prerequisites
8+
9+
```
10+
Required:
11+
✓ Node.js 20+ (LTS recommended)
12+
✓ pnpm 9+
13+
✓ Git
14+
✓ Socket.dev API key
15+
16+
Optional (for binary builds):
17+
✓ Python 3.11+ (for SEA builds)
18+
✓ Docker (for cross-platform builds)
19+
```
20+
21+
---
22+
23+
## 🚀 Quick Start
24+
25+
### 1. Clone & Setup
26+
27+
```bash
28+
# Clone
29+
git clone https://github.com/SocketDev/socket-cli.git
30+
cd socket-cli
31+
32+
# Install & verify
33+
pnpm install
34+
pnpm test
35+
```
36+
37+
**This is a monorepo** with multiple packages!
38+
39+
---
40+
41+
### 2. Monorepo Structure
42+
43+
```
44+
socket-cli/
45+
├── packages/
46+
│ ├── cli/ # Main CLI package (@socketsecurity/cli)
47+
│ │ ├── src/
48+
│ │ │ ├── commands/ # CLI commands (scan, install, etc.)
49+
│ │ │ ├── utils/ # Utilities
50+
│ │ │ └── index.mts # Entry point
51+
│ │ └── test/
52+
│ │
53+
│ ├── bootstrap/ # CLI bootstrapper
54+
│ ├── cli-with-sentry/ # Sentry integration
55+
│ ├── socket/ # Published npm package wrapper
56+
│ ├── node-sea-builder/ # Single Executable Application builder
57+
│ ├── node-smol-builder/ # Optimized Node.js binary builder
58+
│ └── sbom-generator/ # SBOM generation utilities
59+
│
60+
├── scripts/ # Build and dev scripts
61+
├── docs/ # Extensive documentation
62+
│ ├── architecture/ # System architecture
63+
│ ├── build/ # Build system docs
64+
│ ├── development/ # Developer guides
65+
│ ├── node-smol-builder/ # Binary optimization
66+
│ └── ...
67+
│
68+
└── pnpm-workspace.yaml # Monorepo configuration
69+
```
70+
71+
---
72+
73+
### 3. Essential Commands
74+
75+
```bash
76+
# Development
77+
pnpm run dev # Watch mode (all packages)
78+
pnpm build # Build all packages
79+
80+
# Testing
81+
pnpm test # Run all tests
82+
pnpm test:unit # Unit tests only
83+
pnpm test:integration # Integration tests
84+
pnpm run cover:all # Coverage for all packages
85+
86+
# Working with specific packages
87+
pnpm --filter @socketsecurity/cli test # Test CLI package only
88+
pnpm --filter socket build # Build socket package only
89+
90+
# Quality
91+
pnpm run check # Type check + lint all packages
92+
pnpm run lint # Lint all packages
93+
pnpm run fix # Auto-fix issues
94+
95+
# Binary builds (advanced)
96+
pnpm run build:sea # Build Single Executable Application
97+
pnpm run build:smol # Build optimized Node.js binary
98+
```
99+
100+
---
101+
102+
## 🎯 Key Packages
103+
104+
### @socketsecurity/cli (packages/cli/)
105+
106+
**The main CLI implementation**
107+
108+
- All CLI commands (`socket scan`, `socket install`, etc.)
109+
- Interactive console features
110+
- Package manager integrations (npm, pnpm, yarn, bun)
111+
112+
### socket (packages/socket/)
113+
114+
**Published npm package**
115+
116+
- Wraps @socketsecurity/cli
117+
- Handles installation and updates
118+
- The package users actually `npm install -g socket`
119+
120+
### node-smol-builder (packages/node-smol-builder/)
121+
122+
**Optimized Node.js binary builder**
123+
124+
- Creates ~35MB Node.js binaries (vs 60MB+ standard)
125+
- V8 Lite mode, ICU removal, SEA removal
126+
- Custom patches for Windows, macOS, Linux
127+
128+
See [docs/node-smol-builder/](./node-smol-builder/) for details.
129+
130+
---
131+
132+
## 💡 Development Workflow
133+
134+
### Making Changes to CLI
135+
136+
```
137+
1. Branch → git checkout -b feature/my-change
138+
2. Navigate → cd packages/cli
139+
3. Implement → Edit src/commands/ or src/utils/
140+
4. Test → pnpm test (in packages/cli/)
141+
5. Verify → pnpm run fix && pnpm test (from root)
142+
6. Commit → Conventional commits
143+
7. PR → Submit pull request
144+
```
145+
146+
### Adding New Commands
147+
148+
```typescript
149+
// packages/cli/src/commands/my-command/index.mts
150+
export async function handleMyCommand(argv, ctx) {
151+
// Command implementation
152+
}
153+
154+
// packages/cli/src/commands/my-command/cli.mts
155+
export const cliConfig = {
156+
command: 'my-command',
157+
description: 'Does something awesome',
158+
// ... command configuration
159+
}
160+
```
161+
162+
See [docs/development/](./development/) for detailed patterns.
163+
164+
---
165+
166+
## 🔑 API Key Setup
167+
168+
```bash
169+
# .env file
170+
SOCKET_SECURITY_API_KEY=your-api-key-here
171+
172+
# Or configure via CLI
173+
socket config set apiKey your-api-key-here
174+
```
175+
176+
Get your API key at [socket.dev/settings/api-keys](https://socket.dev/settings/api-keys)
177+
178+
---
179+
180+
## 📚 Key Concepts
181+
182+
### 1. Monorepo Workflow
183+
184+
Use pnpm workspaces for package management:
185+
186+
```bash
187+
# Run command in specific package
188+
pnpm --filter @socketsecurity/cli test
189+
190+
# Run command in all packages
191+
pnpm -r test
192+
```
193+
194+
### 2. Package Manager Integrations
195+
196+
CLI supports npm, pnpm, yarn, and bun:
197+
198+
```typescript
199+
import { detectPackageManager } from '@socketsecurity/cli/utils/pm'
200+
201+
const pm = await detectPackageManager(cwd)
202+
// 'npm' | 'pnpm' | 'yarn' | 'bun'
203+
```
204+
205+
### 3. Interactive Console
206+
207+
Built with Ink (React for CLI):
208+
209+
```typescript
210+
// packages/cli/src/commands/console/InteractiveConsoleApp.tsx
211+
import { Text, Box } from 'ink'
212+
213+
export function InteractiveConsoleApp() {
214+
return (
215+
<Box>
216+
<Text>Interactive console</Text>
217+
</Box>
218+
)
219+
}
220+
```
221+
222+
### 4. Binary Distribution
223+
224+
The CLI can be distributed as:
225+
- npm package (standard)
226+
- Single Executable Application (SEA)
227+
- Optimized Node.js binary (smol)
228+
229+
Each has different build processes. See [docs/build/](./build/).
230+
231+
---
232+
233+
## 🧪 Testing
234+
235+
### Unit Tests
236+
237+
```bash
238+
# All unit tests
239+
pnpm test:unit
240+
241+
# Specific package
242+
pnpm --filter @socketsecurity/cli test:unit
243+
```
244+
245+
### Integration Tests
246+
247+
```bash
248+
# All integration tests (requires API key)
249+
pnpm test:integration
250+
251+
# Specific test file
252+
pnpm test test/integration/commands/scan.test.mts
253+
```
254+
255+
### Coverage
256+
257+
```bash
258+
# Coverage for all packages
259+
pnpm run cover:all
260+
261+
# Coverage for CLI package only
262+
pnpm --filter @socketsecurity/cli run test:unit:coverage
263+
```
264+
265+
---
266+
267+
## 📖 Documentation Structure
268+
269+
Socket CLI has **extensive documentation**:
270+
271+
```
272+
docs/
273+
├── architecture/ # System design, bootstrap flow
274+
├── build/ # Build processes, WASM, patches
275+
├── configuration/ # Config management
276+
├── development/ # Setup, linking, platform support
277+
├── node-smol-builder/ # Binary optimization details
278+
├── sbom-generator/ # SBOM generation
279+
├── testing/ # Test strategies
280+
└── yoga-layout/ # Terminal layout engine
281+
```
282+
283+
**Start with:**
284+
1. [docs/development/getting-started.md](./development/getting-started.md) - Dev setup
285+
2. [docs/architecture/](./architecture/) - How it all works
286+
3. [docs/build/](./build/) - Build system deep dive
287+
288+
---
289+
290+
## 🆘 Getting Help
291+
292+
- **Issues:** [GitHub Issues](https://github.com/SocketDev/socket-cli/issues)
293+
- **Discussions:** Ask in PR comments
294+
- **Standards:** [CLAUDE.md](../CLAUDE.md) for conventions
295+
- **Docs:** Extensive docs in [docs/](.)
296+
297+
---
298+
299+
## ✅ Checklist
300+
301+
- [ ] Installed dependencies (`pnpm install` from root)
302+
- [ ] Tests passing (`pnpm test`)
303+
- [ ] Set up API key
304+
- [ ] Read [docs/development/getting-started.md](./development/getting-started.md)
305+
- [ ] Understand monorepo structure
306+
- [ ] Know pnpm workspace commands
307+
- [ ] Understand commit format (conventional commits)
308+
- [ ] Explored [docs/](.) for relevant guides
309+
- [ ] Ready to contribute!
310+
311+
**Welcome to Socket CLI!** 🎉
312+
313+
---
314+
315+
## 🚀 Advanced Topics
316+
317+
Once you're comfortable with basics:
318+
319+
- **Binary Builds:** [docs/build/](./build/) - SEA and smol builds
320+
- **Node Patches:** [docs/node-smol-builder/patches.md](./node-smol-builder/patches.md)
321+
- **Performance:** [docs/node-smol-builder/performance.md](./node-smol-builder/performance.md)
322+
- **WASM Integration:** [docs/build/wasm-integration.md](./build/wasm-integration.md)
323+
- **NLP Features:** [docs/cli/nlp-context-optimization.md](./cli/nlp-context-optimization.md)

0 commit comments

Comments
 (0)