@yaos-git/blueprint-tui 126.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +15 -0
- package/README.md +513 -0
- package/dist/cli.js +1979 -0
- package/package.json +87 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 YAOSGit
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
10
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
11
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
12
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
13
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
14
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
15
|
+
PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,513 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/YAOSGit/blueprint-tui">
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/YAOSGit/.github/main/profile/images/blueprint-tui.svg">
|
|
5
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/YAOSGit/.github/main/profile/images/blueprint-tui-light.svg">
|
|
6
|
+
<img src="https://raw.githubusercontent.com/YAOSGit/.github/main/profile/images/blueprint-tui.svg" width="100%" alt="blueprint-tui" />
|
|
7
|
+
</picture>
|
|
8
|
+
</a>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<strong>Interactive codebase onboarding TUI -- turn docs into executable journeys</strong>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<div align="center">
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Table of Contents
|
|
31
|
+
|
|
32
|
+
### Getting Started
|
|
33
|
+
|
|
34
|
+
- [Overview](#overview)
|
|
35
|
+
- [Installation](#installation)
|
|
36
|
+
- [Quick Start](#quick-start)
|
|
37
|
+
- [CLI Usage](#cli-usage)
|
|
38
|
+
|
|
39
|
+
### Features
|
|
40
|
+
|
|
41
|
+
- [Two-Pane Layout](#two-pane-layout)
|
|
42
|
+
- [Teleport](#teleport)
|
|
43
|
+
- [Actions and Validation](#actions-and-validation)
|
|
44
|
+
- [Jump Navigation](#jump-navigation)
|
|
45
|
+
|
|
46
|
+
### Authoring
|
|
47
|
+
|
|
48
|
+
- [Blueprint Format](#blueprint-format)
|
|
49
|
+
- [Step Frontmatter](#step-frontmatter)
|
|
50
|
+
|
|
51
|
+
### Development
|
|
52
|
+
|
|
53
|
+
- [Available Scripts](#available-scripts)
|
|
54
|
+
- [Tech Stack](#tech-stack)
|
|
55
|
+
- [Project Structure](#project-structure)
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Overview
|
|
60
|
+
|
|
61
|
+
**blueprint-tui** is an interactive terminal UI for guided codebase onboarding. Define a `.blueprint/` directory in your repo with chapters and steps written in Markdown, and blueprint-tui renders them as an executable journey -- complete with file teleportation, runnable actions, and validation checks.
|
|
62
|
+
|
|
63
|
+
### What Makes This Project Unique
|
|
64
|
+
|
|
65
|
+
- **Docs That Do Things**: Steps aren't just text -- they open files in your editor, run commands, and verify completion
|
|
66
|
+
- **Editor-Aware Teleport**: Detects VS Code, JetBrains IDEs, Neovim, and Vim -- opens files at exact line numbers
|
|
67
|
+
- **Two-Pane TUI**: Narrative on the left, actions and process output on the right -- no context switching
|
|
68
|
+
- **Validation Gates**: Required steps must pass a validation command before the tour continues
|
|
69
|
+
- **Zero Config**: Drop a `.blueprint/` directory in any repo and run `blueprint-tui`
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Installation
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Install globally from npm
|
|
77
|
+
npm install -g @yaos-git/blueprint-tui
|
|
78
|
+
|
|
79
|
+
# Or install as a dev dependency
|
|
80
|
+
npm install -D @yaos-git/blueprint-tui
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### From Source
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# Clone the repository
|
|
87
|
+
git clone https://github.com/YAOSGit/blueprint-tui.git
|
|
88
|
+
cd blueprint-tui
|
|
89
|
+
|
|
90
|
+
# Install dependencies
|
|
91
|
+
npm install
|
|
92
|
+
|
|
93
|
+
# Build the project
|
|
94
|
+
npm run build
|
|
95
|
+
|
|
96
|
+
# Link globally (optional)
|
|
97
|
+
npm link
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Quick Start
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# Run a tour from the current directory
|
|
106
|
+
blueprint-tui
|
|
107
|
+
|
|
108
|
+
# Point at a specific .blueprint/ directory
|
|
109
|
+
blueprint-tui ./path/to/.blueprint
|
|
110
|
+
|
|
111
|
+
# Jump straight to a chapter and step
|
|
112
|
+
blueprint-tui --jump architecture:data-layer
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The TUI will parse the `.blueprint/` directory, validate all schemas and teleport targets, then render an interactive two-pane tour.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## CLI Usage
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
blueprint-tui [path] Open a .blueprint/ tour (defaults to .blueprint)
|
|
123
|
+
blueprint-tui --jump <chapter:step> Jump directly to a step
|
|
124
|
+
blueprint-tui --editor <editor> Override editor detection
|
|
125
|
+
blueprint-tui validate [path] Validate .blueprint/ without launching TUI
|
|
126
|
+
blueprint-tui list [path] Print tour outline to stdout
|
|
127
|
+
blueprint-tui --help, -h Show help message
|
|
128
|
+
blueprint-tui --version, -v Show version information
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Examples
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
# Run the tour in the current repo
|
|
135
|
+
blueprint-tui
|
|
136
|
+
|
|
137
|
+
# Validate the blueprint structure (for CI)
|
|
138
|
+
blueprint-tui validate
|
|
139
|
+
|
|
140
|
+
# Print the tour outline
|
|
141
|
+
blueprint-tui list
|
|
142
|
+
|
|
143
|
+
# Jump to a specific step
|
|
144
|
+
blueprint-tui --jump getting-started:setup
|
|
145
|
+
|
|
146
|
+
# Override editor (default: auto-detected)
|
|
147
|
+
blueprint-tui --editor nvim
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Two-Pane Layout
|
|
153
|
+
|
|
154
|
+
The TUI is organized into two panes:
|
|
155
|
+
|
|
156
|
+
### Narrative Pane (Left, 55%)
|
|
157
|
+
|
|
158
|
+
- Renders step Markdown with terminal-native formatting via marked + marked-terminal
|
|
159
|
+
- Scrollable content with keyboard navigation
|
|
160
|
+
- Visual focus indicator (bold cyan border when active)
|
|
161
|
+
|
|
162
|
+
### Activity Pane (Right, 45%)
|
|
163
|
+
|
|
164
|
+
- Action list with selectable items for steps with multiple actions
|
|
165
|
+
- Live process output for running commands (one-shot and persistent)
|
|
166
|
+
- Validation status with pass/fail indicators and hints
|
|
167
|
+
- Process output scrolling with keyboard navigation
|
|
168
|
+
|
|
169
|
+
### Keyboard Shortcuts
|
|
170
|
+
|
|
171
|
+
| Key | Action |
|
|
172
|
+
|-----|--------|
|
|
173
|
+
| `<-` / `h` | Previous step |
|
|
174
|
+
| `->` / `l` | Next step |
|
|
175
|
+
| `[` | Previous chapter |
|
|
176
|
+
| `]` | Next chapter |
|
|
177
|
+
| `o` | Teleport -- open file in IDE |
|
|
178
|
+
| `r` | Run action |
|
|
179
|
+
| `v` | Run validation |
|
|
180
|
+
| `j` | Jump to step |
|
|
181
|
+
| `Tab` | Cycle pane focus |
|
|
182
|
+
| `Up` / `Down` | Scroll focused pane |
|
|
183
|
+
| `?` | Show help overlay |
|
|
184
|
+
| `q` | Quit |
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Teleport
|
|
189
|
+
|
|
190
|
+
Each step can specify a `teleport` target -- a file and line number to open in the user's editor. blueprint-tui auto-detects the editor or accepts an override via `--editor` or the `editor` field in `blueprint.yaml`.
|
|
191
|
+
|
|
192
|
+
Supported editors:
|
|
193
|
+
|
|
194
|
+
| Editor | Detection | Open Command |
|
|
195
|
+
|--------|-----------|-------------|
|
|
196
|
+
| VS Code | `code` | `code --goto file:line` |
|
|
197
|
+
| JetBrains (IntelliJ, WebStorm, GoLand) | `idea`, `webstorm`, `goland` | `idea --line N file` |
|
|
198
|
+
| Neovim | `nvim` | `nvim +N file` |
|
|
199
|
+
| Vim | `vim` | `vim +N file` |
|
|
200
|
+
| Other | binary name | `editor file:line` |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Actions and Validation
|
|
205
|
+
|
|
206
|
+
### Actions
|
|
207
|
+
|
|
208
|
+
Steps can define one or more runnable shell commands:
|
|
209
|
+
|
|
210
|
+
- **One-shot actions**: Run to completion, capture stdout/stderr, report exit code
|
|
211
|
+
- **Persistent actions**: Spawn long-running processes (e.g., dev servers) with SIGTERM/SIGKILL cleanup
|
|
212
|
+
|
|
213
|
+
### Validation
|
|
214
|
+
|
|
215
|
+
Steps can include a validation command that determines whether the step was completed successfully. Required steps block progression until validation passes. A hint is shown when validation fails.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Jump Navigation
|
|
220
|
+
|
|
221
|
+
Press `j` to open the jump overlay -- a full-screen view of all chapters and steps with the current position highlighted. Select any step to jump directly to it.
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## Blueprint Format
|
|
226
|
+
|
|
227
|
+
A `.blueprint/` directory follows this structure:
|
|
228
|
+
|
|
229
|
+
```
|
|
230
|
+
.blueprint/
|
|
231
|
+
├── blueprint.yaml # Tour metadata
|
|
232
|
+
├── 00-getting-started/ # Chapter (prefix for ordering)
|
|
233
|
+
│ ├── chapter.yaml # Chapter metadata
|
|
234
|
+
│ ├── 01-overview.md # Step (prefix for ordering)
|
|
235
|
+
│ └── 02-setup.md # Step
|
|
236
|
+
└── 01-architecture/ # Chapter
|
|
237
|
+
├── chapter.yaml
|
|
238
|
+
└── 01-data-layer.md # Step
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### blueprint.yaml
|
|
242
|
+
|
|
243
|
+
```yaml
|
|
244
|
+
name: My Project Tour
|
|
245
|
+
version: 1.0.0
|
|
246
|
+
author: Team Name
|
|
247
|
+
editor: code # Optional: override editor detection
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### chapter.yaml
|
|
251
|
+
|
|
252
|
+
```yaml
|
|
253
|
+
title: Getting Started
|
|
254
|
+
description: First steps with the project.
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Step Frontmatter
|
|
260
|
+
|
|
261
|
+
Each step is a Markdown file with YAML frontmatter:
|
|
262
|
+
|
|
263
|
+
```markdown
|
|
264
|
+
---
|
|
265
|
+
title: Setup
|
|
266
|
+
teleport:
|
|
267
|
+
file: src/index.ts
|
|
268
|
+
line: 1
|
|
269
|
+
highlight: "createApp" # Optional: search term
|
|
270
|
+
actions:
|
|
271
|
+
- label: Install deps
|
|
272
|
+
command: npm install
|
|
273
|
+
- label: Start dev server
|
|
274
|
+
command: npm run dev
|
|
275
|
+
persistent: true # Long-running process
|
|
276
|
+
validate:
|
|
277
|
+
command: npm test
|
|
278
|
+
hint: Run npm install first
|
|
279
|
+
required: true # Must pass validation to proceed
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
# Setup
|
|
283
|
+
|
|
284
|
+
Install dependencies and run the tests to verify your environment.
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
### Frontmatter Fields
|
|
288
|
+
|
|
289
|
+
| Field | Type | Required | Description |
|
|
290
|
+
|-------|------|----------|-------------|
|
|
291
|
+
| `title` | string | yes | Step title shown in header and jump overlay |
|
|
292
|
+
| `teleport` | object | no | File and line to open in editor |
|
|
293
|
+
| `teleport.file` | string | yes (if teleport) | Relative path from project root |
|
|
294
|
+
| `teleport.line` | number | no | Line number (default: 1) |
|
|
295
|
+
| `teleport.highlight` | string | no | Search term for the editor |
|
|
296
|
+
| `actions` | array | no | Shell commands to run |
|
|
297
|
+
| `actions[].label` | string | yes (if actions) | Display label for the action |
|
|
298
|
+
| `actions[].command` | string | yes (if actions) | Shell command to execute |
|
|
299
|
+
| `actions[].persistent` | boolean | no | Keep process running (default: false) |
|
|
300
|
+
| `validate` | object | no | Validation command |
|
|
301
|
+
| `validate.command` | string | yes (if validate) | Shell command that must exit 0 |
|
|
302
|
+
| `validate.hint` | string | yes (if validate) | Help text shown on failure |
|
|
303
|
+
| `required` | boolean | no | Block progression until validated (default: false) |
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Available Scripts
|
|
308
|
+
|
|
309
|
+
### Development Scripts
|
|
310
|
+
|
|
311
|
+
| Script | Description |
|
|
312
|
+
|--------|-------------|
|
|
313
|
+
| `npm run dev` | Run TypeScript checking + test watcher concurrently |
|
|
314
|
+
| `npm run dev:typescript` | Run TypeScript type checking in watch mode |
|
|
315
|
+
| `npm run dev:test` | Run Vitest in watch mode |
|
|
316
|
+
|
|
317
|
+
### Build Scripts
|
|
318
|
+
|
|
319
|
+
| Script | Description |
|
|
320
|
+
|--------|-------------|
|
|
321
|
+
| `npm run build` | Bundle the CLI with esbuild |
|
|
322
|
+
|
|
323
|
+
### Lint Scripts
|
|
324
|
+
|
|
325
|
+
| Script | Description |
|
|
326
|
+
|--------|-------------|
|
|
327
|
+
| `npm run lint` | Run type checking, linting, formatting, and audit |
|
|
328
|
+
| `npm run lint:check` | Check code for linting issues with Biome |
|
|
329
|
+
| `npm run lint:fix` | Check and fix linting issues with Biome |
|
|
330
|
+
| `npm run lint:format` | Format all files with Biome |
|
|
331
|
+
| `npm run lint:types` | Run TypeScript type checking only |
|
|
332
|
+
| `npm run lint:audit` | Run npm audit |
|
|
333
|
+
|
|
334
|
+
### Testing Scripts
|
|
335
|
+
|
|
336
|
+
| Script | Description |
|
|
337
|
+
|--------|-------------|
|
|
338
|
+
| `npm test` | Run all tests (unit, react, types, e2e) |
|
|
339
|
+
| `npm run test:unit` | Run unit tests |
|
|
340
|
+
| `npm run test:react` | Run React component tests |
|
|
341
|
+
| `npm run test:types` | Run type-level tests |
|
|
342
|
+
| `npm run test:e2e` | Build and run end-to-end tests |
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
|
|
346
|
+
## Tech Stack
|
|
347
|
+
|
|
348
|
+
### Core
|
|
349
|
+
|
|
350
|
+
- **[React 19](https://react.dev/)** -- UI component library
|
|
351
|
+
- **[Ink 6](https://github.com/vadimdemedes/ink)** -- React for CLIs
|
|
352
|
+
- **[TypeScript 5](https://www.typescriptlang.org/)** -- Type-safe JavaScript
|
|
353
|
+
- **[Zod](https://zod.dev/)** -- Runtime schema validation for tour data
|
|
354
|
+
- **[marked](https://marked.js.org/)** + **[marked-terminal](https://github.com/mikaelbr/marked-terminal)** -- Markdown rendering in the terminal
|
|
355
|
+
- **[gray-matter](https://github.com/jonschlinkert/gray-matter)** -- Frontmatter parsing
|
|
356
|
+
- **[yaml](https://eemeli.org/yaml/)** -- YAML parsing for blueprint and chapter metadata
|
|
357
|
+
|
|
358
|
+
### Build and Development
|
|
359
|
+
|
|
360
|
+
- **[esbuild](https://esbuild.github.io/)** -- Fast bundler
|
|
361
|
+
- **[Vitest](https://vitest.dev/)** -- Unit testing framework
|
|
362
|
+
- **[Biome](https://biomejs.dev/)** -- Linter and formatter
|
|
363
|
+
|
|
364
|
+
### UI
|
|
365
|
+
|
|
366
|
+
- **[Chalk](https://github.com/chalk/chalk)** -- Terminal string styling
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## Project Structure
|
|
371
|
+
|
|
372
|
+
```
|
|
373
|
+
blueprint-tui/
|
|
374
|
+
├── src/
|
|
375
|
+
│ ├── app/ # Application entry points
|
|
376
|
+
│ │ ├── cli.tsx # CLI entry point (Commander)
|
|
377
|
+
│ │ ├── app.tsx # Main two-pane layout
|
|
378
|
+
│ │ ├── index.tsx # React app root
|
|
379
|
+
│ │ └── providers.tsx # Provider wrapper
|
|
380
|
+
│ ├── components/ # React (Ink) components
|
|
381
|
+
│ │ ├── ActionList/ # Action buttons in activity pane
|
|
382
|
+
│ │ ├── ActivityPane/ # Right pane -- actions + process output
|
|
383
|
+
│ │ ├── Header/ # Tour name, chapter, step counter
|
|
384
|
+
│ │ ├── HelpOverlay/ # Keyboard shortcut reference
|
|
385
|
+
│ │ ├── JumpOverlay/ # Chapter:step quick navigation
|
|
386
|
+
│ │ ├── NarrativePane/ # Left pane -- Markdown rendering
|
|
387
|
+
│ │ ├── ProcessOutput/ # Live command output display
|
|
388
|
+
│ │ ├── ProgressFooter/ # Step stepper and shortcut bar
|
|
389
|
+
│ │ └── ValidationStatus/ # Pass/fail indicator with hints
|
|
390
|
+
│ ├── hooks/ # React hooks
|
|
391
|
+
│ │ ├── useCommands/ # Keyboard command registry
|
|
392
|
+
│ │ ├── useMarkdown/ # Markdown rendering via marked
|
|
393
|
+
│ │ ├── useProcess/ # Process state management
|
|
394
|
+
│ │ ├── useTour/ # Tour navigation state
|
|
395
|
+
│ │ └── useUIState/ # UI focus and overlay state
|
|
396
|
+
│ ├── loader/ # .blueprint/ directory parser
|
|
397
|
+
│ │ ├── frontmatterParser.ts # YAML frontmatter extraction
|
|
398
|
+
│ │ └── walker.ts # Directory traversal and validation
|
|
399
|
+
│ ├── providers/ # React context providers
|
|
400
|
+
│ │ ├── CommandsProvider/ # Keyboard command registry
|
|
401
|
+
│ │ ├── ProcessProvider/ # Process spawning and lifecycle
|
|
402
|
+
│ │ ├── TourProvider/ # Tour state and navigation
|
|
403
|
+
│ │ └── UIStateProvider/ # Focus, scroll, and overlay state
|
|
404
|
+
│ ├── runner/ # Command execution
|
|
405
|
+
│ │ ├── oneShot.ts # Run-to-completion commands
|
|
406
|
+
│ │ └── persistent.ts # Long-running process management
|
|
407
|
+
│ ├── teleport/ # Editor integration
|
|
408
|
+
│ │ ├── editorDetector.ts # Auto-detect installed editor
|
|
409
|
+
│ │ └── index.ts # Build and execute editor commands
|
|
410
|
+
│ └── types/ # TypeScript type definitions
|
|
411
|
+
│ ├── Process/ # Process state types
|
|
412
|
+
│ ├── Tour/ # Tour, Chapter, Step Zod schemas
|
|
413
|
+
│ └── Validation/ # Validation result types
|
|
414
|
+
├── test/
|
|
415
|
+
│ └── fixtures/ # Test fixture .blueprint/ directories
|
|
416
|
+
├── biome.json # Biome configuration
|
|
417
|
+
├── tsconfig.json # TypeScript configuration
|
|
418
|
+
├── vitest.unit.config.ts # Unit test configuration
|
|
419
|
+
├── vitest.react.config.ts # React test configuration
|
|
420
|
+
├── vitest.type.config.ts # Type test configuration
|
|
421
|
+
├── vitest.e2e.config.ts # E2E test configuration
|
|
422
|
+
├── esbuild.config.js # esbuild bundler configuration
|
|
423
|
+
└── package.json
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
---
|
|
427
|
+
|
|
428
|
+
## Versioning
|
|
429
|
+
|
|
430
|
+
This project uses a custom versioning scheme: `MAJORYY.MINOR.PATCH`
|
|
431
|
+
|
|
432
|
+
| Part | Description | Example |
|
|
433
|
+
|------|-------------|---------|
|
|
434
|
+
| `MAJOR` | Major version number | `1` |
|
|
435
|
+
| `YY` | Year (last 2 digits) | `26` for 2026 |
|
|
436
|
+
| `MINOR` | Minor version | `0` |
|
|
437
|
+
| `PATCH` | Patch version | `0` |
|
|
438
|
+
|
|
439
|
+
**Example:** `126.0.0` = Major version 1, released in 2026, minor 0, patch 0
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## Style Guide
|
|
444
|
+
|
|
445
|
+
Conventions for contributing to this project. All rules are enforced by code review; Biome handles formatting and lint.
|
|
446
|
+
|
|
447
|
+
### Exports
|
|
448
|
+
|
|
449
|
+
- **Named exports only** -- no `export default`. Every module uses `export function`, `export const`, or `export type`.
|
|
450
|
+
- **`import type`** -- always use `import type` for type-only imports.
|
|
451
|
+
- **`.js` extensions** -- all relative imports use explicit `.js` extensions (ESM requirement).
|
|
452
|
+
|
|
453
|
+
### File Structure
|
|
454
|
+
|
|
455
|
+
```
|
|
456
|
+
src/
|
|
457
|
+
├── app/ # Entry points and root component
|
|
458
|
+
├── components/ # React components (PascalCase directories)
|
|
459
|
+
│ └── MyComponent/
|
|
460
|
+
│ ├── index.tsx
|
|
461
|
+
│ ├── MyComponent.types.ts
|
|
462
|
+
│ └── MyComponent.test.tsx
|
|
463
|
+
├── hooks/ # React hooks (camelCase directories)
|
|
464
|
+
│ └── useMyHook/
|
|
465
|
+
│ ├── index.ts
|
|
466
|
+
│ └── useMyHook.test.ts
|
|
467
|
+
├── providers/ # React context providers (PascalCase directories)
|
|
468
|
+
│ └── MyProvider/
|
|
469
|
+
│ ├── index.tsx
|
|
470
|
+
│ ├── MyProvider.types.ts
|
|
471
|
+
│ └── MyProvider.test.tsx
|
|
472
|
+
├── types/ # Shared type definitions (PascalCase directories)
|
|
473
|
+
│ └── MyType/
|
|
474
|
+
│ ├── index.ts
|
|
475
|
+
│ └── MyType.test-d.ts
|
|
476
|
+
└── utils/ # Pure utility functions (camelCase directories)
|
|
477
|
+
└── myUtil/
|
|
478
|
+
├── index.ts
|
|
479
|
+
└── myUtil.test.ts
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
### Components and Providers
|
|
483
|
+
|
|
484
|
+
- **Components** use `function` declarations: `export function MyComponent(props: MyComponentProps) {}`
|
|
485
|
+
- **Providers** use `React.FC` arrow syntax: `export const MyProvider: React.FC<Props> = ({ children }) => {}`
|
|
486
|
+
- **Props** are defined in a co-located `.types.ts` file using the `interface` keyword.
|
|
487
|
+
- Components receive data via props -- never read `process.stdout` or global state directly.
|
|
488
|
+
|
|
489
|
+
### Types
|
|
490
|
+
|
|
491
|
+
- Use `type` for data shapes and unions. Use `interface` for component props.
|
|
492
|
+
- Shared types live in `src/types/TypeName/index.ts` with a co-located `TypeName.test-d.ts`.
|
|
493
|
+
- Local types live in co-located `.types.ts` files -- never inline in implementation files.
|
|
494
|
+
- No duplicate type definitions -- import from the canonical source.
|
|
495
|
+
|
|
496
|
+
### Constants
|
|
497
|
+
|
|
498
|
+
- Named constants go in `.consts.ts` files (e.g., `MyComponent.consts.ts`).
|
|
499
|
+
- No magic numbers in implementation files -- extract to named constants.
|
|
500
|
+
- Cross-component constants belong in `src/utils/`, not in a specific component's `.consts.ts`.
|
|
501
|
+
|
|
502
|
+
### Testing
|
|
503
|
+
|
|
504
|
+
- Every module has a co-located test file.
|
|
505
|
+
- Components: `ComponentName.test.tsx`
|
|
506
|
+
- Utils: `utilName.test.ts`
|
|
507
|
+
- Types: `TypeName.test-d.ts` (type-level tests using `expectTypeOf`/`assertType`)
|
|
508
|
+
|
|
509
|
+
---
|
|
510
|
+
|
|
511
|
+
## License
|
|
512
|
+
|
|
513
|
+
ISC
|