@techninja/clearstack 0.2.0 → 0.2.1

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.
Files changed (4) hide show
  1. package/README.md +12 -9
  2. package/docs/QUICKSTART.md +89 -102
  3. package/package.json +1 -1
  4. package/templates/shared/docs/clearstack/QUICKSTART.md +89 -102
package/README.md CHANGED
@@ -13,10 +13,10 @@ This entire repository — the specification, the file structure, every componen
13
13
  ## Quick Start
14
14
 
15
15
  ```bash
16
+ npm install -D @techninja/clearstack
17
+ npx clearstack init # scaffold a spec-compliant project
16
18
  npm install
17
- npm start # http://localhost:3000
18
- npm test # node + browser tests
19
- npm run spec # interactive spec compliance checker
19
+ npm run dev # http://localhost:3000
20
20
  ```
21
21
 
22
22
  ## What's In The Box
@@ -37,14 +37,16 @@ A project/task tracker that exercises every pattern in the spec: API-backed enti
37
37
  | [BUILD_LOG.md](./docs/BUILD_LOG.md) | How this project was built — LLM-human collaboration proof |
38
38
  | [QUICKSTART.md](./docs/QUICKSTART.md) | Scaffolder setup, development workflow, updating, compliance |
39
39
 
40
- ## Start a New Project
40
+ ## Using Clearstack
41
41
 
42
- The Clearstack scaffolder generates a spec-compliant project from templates and keeps it in sync as the spec evolves.
42
+ Install as a dev dependency, scaffold, and keep in sync:
43
43
 
44
44
  ```bash
45
- npx clearstack init # interactive project scaffolder
46
- npx clearstack update # sync spec docs + configs from upstream
47
- npx clearstack check # run spec compliance checks
45
+ npm install -D @techninja/clearstack # add to your project
46
+ npx clearstack init # scaffold (interactive)
47
+ npx clearstack init -y # scaffold (defaults)
48
+ npm run spec # check compliance
49
+ npm run spec:update # sync docs + configs on upgrade
48
50
  ```
49
51
 
50
52
  Two modes: **fullstack** (Express + WebSocket + JSON DB + SSE) or **static** (localStorage, no server).
@@ -71,9 +73,10 @@ npm run lint # ESLint check
71
73
  npm run lint:fix # ESLint auto-fix
72
74
  npm run format # Prettier auto-format
73
75
  npm run typecheck # JSDoc type validation via tsc
74
- npm run spec # Interactive spec compliance checker
76
+ npm run spec # Spec compliance check
75
77
  npm run spec:code # Check code files ≤150 lines
76
78
  npm run spec:docs # Check doc files ≤500 lines
79
+ npm run spec:update # Sync docs + configs from upstream
77
80
  ```
78
81
 
79
82
  ## License
package/docs/QUICKSTART.md CHANGED
@@ -4,157 +4,143 @@ Get a spec-compliant project running, develop against it, and keep it in sync as
4
4
 
5
5
  ## Prerequisites
6
6
 
7
- - Node.js ≥ 20
8
- - npm ≥ 10
7
+ - Node.js ≥ 22
8
+ - npm, pnpm, or yarn
9
9
 
10
- ## 1. Scaffold a New Project
10
+ ## 1. Install Clearstack
11
+
12
+ Clearstack is a dev dependency — it lives in your project and manages spec docs, configs, and compliance checks.
11
13
 
12
14
  ```bash
13
- npx clearstack init
15
+ npm install --save-dev @techninja/clearstack
16
+ # or
17
+ pnpm add -D @techninja/clearstack
18
+ ```
19
+
20
+ ## 2. Scaffold Your Project
21
+
22
+ From your project root:
23
+
24
+ ```bash
25
+ npx clearstack init # interactive
26
+ npx clearstack init -y # non-interactive (defaults)
14
27
  ```
15
28
 
16
29
  The interactive prompt asks for:
17
30
 
18
31
  | Prompt | Default | Notes |
19
32
  |---|---|---|
20
- | Project name | `my-app` | Creates a directory with this name |
33
+ | Project name | current directory name | Used in package.json and templates |
21
34
  | Description | `A Clearstack project` | Goes into package.json |
22
- | Mode | — | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only, no server |
35
+ | Mode | — | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only |
23
36
  | Port | `3000` | Fullstack only. Set in `.env` |
24
- | Include examples? | Yes | Starter components demonstrating spec patterns |
25
37
 
26
- This generates a complete project directory:
38
+ If a `package.json` already exists, Clearstack merges into it — your existing fields (`author`, `license`, `engines`, `keywords`, etc.) are preserved.
39
+
40
+ ## 3. What Gets Created
27
41
 
28
42
  ```
29
- my-app/
30
- ├── .configs/ # eslint, prettier, jsconfig, web-test-runner
31
- ├── .github/ # CI workflow, PR + issue templates
32
- ├── docs/ # Spec docs (upstream-managed)
33
- │ ├── clearstack/ # Clearstack spec docs (synced on update)
34
- │ └── app-spec/ # Your project-specific specs (never overwritten)
35
- ├── public/ # Static assets, index.html, import map
36
- ├── scripts/ # vendor-deps, build-icons, spec checker
43
+ your-project/
44
+ ├── .configs/ # ⟳ Managed — synced on update
45
+ │ ├── eslint.config.js
46
+ │ ├── .prettierrc
47
+ │ ├── jsconfig.json
48
+ │ └── web-test-runner.config.js
49
+ ├── .github/ # CI workflow, PR + issue templates
50
+ ├── docs/
51
+ │ ├── clearstack/ # ⟳ Managed — spec docs, synced on update
52
+ │ └── app-spec/ # ✏️ Yours — project-specific specs
53
+ ├── public/ # ✏️ Yours — static assets, index.html, import map
54
+ ├── scripts/ # ✏️ Yours — vendor-deps, build-icons
37
55
  ├── src/
38
- │ ├── components/ # atoms/, molecules/, organisms/, pages/
39
- │ ├── store/ # Hybrids store models
40
- │ ├── styles/ # Global CSS with native nesting
41
- │ ├── router/ # Client-side routing
42
- │ └── utils/ # Shared helpers
43
- ├── tests/ # Node + browser tests
44
- ├── data/ # JSON DB (fullstack only)
45
- ├── src/server.js # Express server (fullstack only)
46
- ├── .env # PORT, spec thresholds
47
- └── package.json
56
+ │ ├── api/ # ✏️ Yours — server routes (fullstack only)
57
+ │ ├── components/ # ✏️ Yours — atoms/, molecules/, organisms/
58
+ │ ├── pages/ # ✏️ Yours — route-level views
59
+ │ ├── store/ # ✏️ Yours — Hybrids store models
60
+ │ ├── styles/ # ✏️ Yours — global CSS
61
+ │ ├── router/ # ✏️ Yours — client-side routing
62
+ │ ├── utils/ # ✏️ Yours — shared helpers
63
+ │ └── server.js # ✏️ Yours — Express entry (fullstack only)
64
+ ├── data/ # ✏️ Yours — JSON DB seed (fullstack only)
65
+ ├── .env # ✏️ Yours — PORT, spec thresholds
66
+ └── package.json # ✏️ Yours (spec scripts merged in)
48
67
  ```
49
68
 
50
- ## 2. Install and Run
69
+ **⟳ Managed** files are updated when you run `clearstack update`. Review changes via `git diff`.
70
+
71
+ **✏️ Yours** files are scaffolded once and never touched by updates. They're your code.
72
+
73
+ ## 4. Install and Run
51
74
 
52
75
  ```bash
53
- cd my-app
54
76
  npm install
55
77
  ```
56
78
 
57
- `postinstall` automatically runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
79
+ `postinstall` runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
58
80
 
59
- ### Fullstack mode
81
+ ### Fullstack
60
82
 
61
83
  ```bash
62
- npm run dev # node --watch src/server.js
63
- # → http://localhost:3000
84
+ npm run dev # node --watch --env-file=.env src/server.js
64
85
  ```
65
86
 
66
- ### Static mode
87
+ ### Static
67
88
 
68
89
  ```bash
69
90
  npx serve public # or any static file server
70
91
  ```
71
92
 
72
- ## 3. Development Workflow
93
+ ## 5. Development Rules
73
94
 
74
- ### Create a component
75
-
76
- Every component is a plain ES module that exports a Hybrids descriptor. Place it in the appropriate atomic design tier:
77
-
78
- ```
79
- src/components/atoms/ # buttons, icons, badges
80
- src/components/molecules/ # form fields, cards
81
- src/components/organisms/ # lists, editors, canvases
82
- src/components/pages/ # route-level views
83
- ```
84
-
85
- Register it in `src/components/index.js` and add a `<script>` or import map entry in `public/index.html` if needed.
86
-
87
- ### Key rules while coding
88
-
89
- - **≤150 lines per `.js` / `.css` file.** Add `// SPLIT CANDIDATE:` at 120 lines. When you hit the limit, extract a module.
95
+ - **≤150 lines per `.js` / `.css` file.** Add `// SPLIT CANDIDATE:` at ~120 lines.
90
96
  - **Light DOM by default.** No `shadowRoot`. Shared styles in `src/styles/` apply everywhere.
91
97
  - **JSDoc for types.** `@typedef`, `@param`, `@returns` — validated by `tsc --checkJs`.
92
98
  - **No build step.** Every file runs as-is in the browser via ES modules and import maps.
93
99
 
94
- ### Run checks during development
95
-
96
- ```bash
97
- npm run lint:fix # ESLint auto-fix
98
- npm run format # Prettier auto-format
99
- npm run typecheck # JSDoc type validation
100
- npm test # Node + browser tests
101
- npm run spec # Full interactive spec compliance check
102
- ```
103
-
104
- Or run individual spec checks:
105
-
106
- ```bash
107
- npm run spec:code # Code files ≤150 lines
108
- npm run spec:docs # Doc files ≤500 lines
109
- ```
110
-
111
- ## 4. Project-Specific Specs
100
+ ## 6. Project-Specific Specs
112
101
 
113
- The `docs/app-spec/` directory is yours. Upstream updates never touch it. Use it for:
102
+ `docs/app-spec/` is yours. Upstream updates never touch it. Use it for:
114
103
 
115
104
  - Entity schemas and relationships
116
- - Project-specific patterns or conventions
105
+ - Project-specific component patterns
117
106
  - API documentation beyond the base spec
118
107
  - Architecture decisions (ADRs)
119
- - Deviations from the spec (with rationale)
108
+ - Deviations from the base spec (with rationale)
120
109
 
121
- See [docs/app-spec/README.md](./app-spec/README.md) for the full guide.
110
+ See [docs/app-spec/README.md](./app-spec/README.md) for examples.
122
111
 
123
- ## 5. Update Spec Docs
112
+ ## 7. Updating
124
113
 
125
- When the spec evolves upstream, pull the latest docs into your project:
114
+ When Clearstack releases a new version:
126
115
 
127
116
  ```bash
128
- npx clearstack update
117
+ npm update @techninja/clearstack # bump the package
118
+ npm run spec:update # sync docs + configs
119
+ git diff docs/ .configs/ # review what changed
129
120
  ```
130
121
 
131
- This:
132
- - Copies updated spec docs from the package into your `docs/clearstack/` directory
133
- - Syncs `.configs/` to latest standards
134
- - Skips `docs/app-spec/` entirely — your project-specific specs are safe
135
- - Writes a `.specversion` file so you can track which version you're on
136
- - Prints which files changed so you can review with `git diff docs/ .configs/`
137
-
138
- Review the diff, adjust your code if needed, then commit.
122
+ This updates:
123
+ - `docs/clearstack/*.md` — spec documentation
124
+ - `.configs/*` — linter, formatter, type checker, test runner configs
139
125
 
140
- ## 6. Check Spec Compliance
126
+ This never touches:
127
+ - `docs/app-spec/` — your project specs
128
+ - `src/` — your code
129
+ - `scripts/` — your build scripts
130
+ - `.env` — your thresholds and settings
141
131
 
142
- Run the full compliance suite at any time:
132
+ ## 8. Spec Compliance
143
133
 
144
134
  ```bash
145
- npx clearstack check
135
+ npm run spec # full check via clearstack binary
136
+ npm run spec:code # code files ≤150 lines
137
+ npm run spec:docs # doc files ≤500 lines
138
+ npm run lint:fix # ESLint auto-fix
139
+ npm run format # Prettier auto-format
140
+ npm run typecheck # JSDoc type validation
141
+ npm test # Node + browser tests
146
142
  ```
147
143
 
148
- This runs from the scaffolder package itself (no local scripts needed). It checks:
149
-
150
- 1. **Code line counts** — all `.js` / `.css` files ≤150 lines
151
- 2. **Doc line counts** — all `.md` files ≤500 lines
152
- 3. **ESLint** — linting with the spec's config
153
- 4. **Prettier** — formatting with the spec's config
154
- 5. **JSDoc types** — `tsc --checkJs` against jsconfig
155
-
156
- The same checks run in CI via the GitHub Actions workflow scaffolded into `.github/`.
157
-
158
144
  ### Configuring thresholds
159
145
 
160
146
  Override defaults in `.env`:
@@ -167,24 +153,25 @@ SPEC_DOCS_EXTENSIONS=.md
167
153
  SPEC_IGNORE_DIRS=node_modules,public/vendor,.git,.configs
168
154
  ```
169
155
 
170
- ## 7. CI Pipeline
156
+ ## 9. CI Pipeline
171
157
 
172
- The scaffolded `.github/workflows/` runs all spec checks on every PR. A PR cannot merge unless all checks pass. The workflow runs:
158
+ The scaffolded `.github/workflows/spec.yml` runs all checks on every PR:
173
159
 
174
160
  ```
175
- npm run spec:code → npm run spec:docs → npm run lint → npm run format → npm run typecheck → npm test
161
+ spec:code → spec:docs → lint → format → typecheck → test
176
162
  ```
177
163
 
178
164
  ## Summary
179
165
 
180
166
  | Task | Command |
181
167
  |---|---|
168
+ | Install Clearstack | `npm install -D @techninja/clearstack` |
182
169
  | Scaffold a project | `npx clearstack init` |
183
170
  | Install dependencies | `npm install` |
184
- | Start dev server | `npm run dev` (fullstack) / `npx serve public` (static) |
171
+ | Start dev server | `npm run dev` / `npx serve public` |
185
172
  | Lint + format | `npm run lint:fix && npm run format` |
186
173
  | Type check | `npm run typecheck` |
187
174
  | Run tests | `npm test` |
188
- | Full spec check | `npm run spec` or `npx clearstack check` |
189
- | Update spec docs | `npx clearstack update` |
175
+ | Full spec check | `npm run spec` |
176
+ | Update spec + configs | `npm run spec:update` |
190
177
  | Review spec changes | `git diff docs/ .configs/` |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@techninja/clearstack",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "type": "module",
5
5
  "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
6
6
  "bin": {
package/templates/shared/docs/clearstack/QUICKSTART.md CHANGED
@@ -4,157 +4,143 @@ Get a spec-compliant project running, develop against it, and keep it in sync as
4
4
 
5
5
  ## Prerequisites
6
6
 
7
- - Node.js ≥ 20
8
- - npm ≥ 10
7
+ - Node.js ≥ 22
8
+ - npm, pnpm, or yarn
9
9
 
10
- ## 1. Scaffold a New Project
10
+ ## 1. Install Clearstack
11
+
12
+ Clearstack is a dev dependency — it lives in your project and manages spec docs, configs, and compliance checks.
11
13
 
12
14
  ```bash
13
- npx clearstack init
15
+ npm install --save-dev @techninja/clearstack
16
+ # or
17
+ pnpm add -D @techninja/clearstack
18
+ ```
19
+
20
+ ## 2. Scaffold Your Project
21
+
22
+ From your project root:
23
+
24
+ ```bash
25
+ npx clearstack init # interactive
26
+ npx clearstack init -y # non-interactive (defaults)
14
27
  ```
15
28
 
16
29
  The interactive prompt asks for:
17
30
 
18
31
  | Prompt | Default | Notes |
19
32
  |---|---|---|
20
- | Project name | `my-app` | Creates a directory with this name |
33
+ | Project name | current directory name | Used in package.json and templates |
21
34
  | Description | `A Clearstack project` | Goes into package.json |
22
- | Mode | — | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only, no server |
35
+ | Mode | — | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only |
23
36
  | Port | `3000` | Fullstack only. Set in `.env` |
24
- | Include examples? | Yes | Starter components demonstrating spec patterns |
25
37
 
26
- This generates a complete project directory:
38
+ If a `package.json` already exists, Clearstack merges into it — your existing fields (`author`, `license`, `engines`, `keywords`, etc.) are preserved.
39
+
40
+ ## 3. What Gets Created
27
41
 
28
42
  ```
29
- my-app/
30
- ├── .configs/ # eslint, prettier, jsconfig, web-test-runner
31
- ├── .github/ # CI workflow, PR + issue templates
32
- ├── docs/ # Spec docs (upstream-managed)
33
- │ ├── clearstack/ # Clearstack spec docs (synced on update)
34
- │ └── app-spec/ # Your project-specific specs (never overwritten)
35
- ├── public/ # Static assets, index.html, import map
36
- ├── scripts/ # vendor-deps, build-icons, spec checker
43
+ your-project/
44
+ ├── .configs/ # ⟳ Managed — synced on update
45
+ │ ├── eslint.config.js
46
+ │ ├── .prettierrc
47
+ │ ├── jsconfig.json
48
+ │ └── web-test-runner.config.js
49
+ ├── .github/ # CI workflow, PR + issue templates
50
+ ├── docs/
51
+ │ ├── clearstack/ # ⟳ Managed — spec docs, synced on update
52
+ │ └── app-spec/ # ✏️ Yours — project-specific specs
53
+ ├── public/ # ✏️ Yours — static assets, index.html, import map
54
+ ├── scripts/ # ✏️ Yours — vendor-deps, build-icons
37
55
  ├── src/
38
- │ ├── components/ # atoms/, molecules/, organisms/, pages/
39
- │ ├── store/ # Hybrids store models
40
- │ ├── styles/ # Global CSS with native nesting
41
- │ ├── router/ # Client-side routing
42
- │ └── utils/ # Shared helpers
43
- ├── tests/ # Node + browser tests
44
- ├── data/ # JSON DB (fullstack only)
45
- ├── src/server.js # Express server (fullstack only)
46
- ├── .env # PORT, spec thresholds
47
- └── package.json
56
+ │ ├── api/ # ✏️ Yours — server routes (fullstack only)
57
+ │ ├── components/ # ✏️ Yours — atoms/, molecules/, organisms/
58
+ │ ├── pages/ # ✏️ Yours — route-level views
59
+ │ ├── store/ # ✏️ Yours — Hybrids store models
60
+ │ ├── styles/ # ✏️ Yours — global CSS
61
+ │ ├── router/ # ✏️ Yours — client-side routing
62
+ │ ├── utils/ # ✏️ Yours — shared helpers
63
+ │ └── server.js # ✏️ Yours — Express entry (fullstack only)
64
+ ├── data/ # ✏️ Yours — JSON DB seed (fullstack only)
65
+ ├── .env # ✏️ Yours — PORT, spec thresholds
66
+ └── package.json # ✏️ Yours (spec scripts merged in)
48
67
  ```
49
68
 
50
- ## 2. Install and Run
69
+ **⟳ Managed** files are updated when you run `clearstack update`. Review changes via `git diff`.
70
+
71
+ **✏️ Yours** files are scaffolded once and never touched by updates. They're your code.
72
+
73
+ ## 4. Install and Run
51
74
 
52
75
  ```bash
53
- cd my-app
54
76
  npm install
55
77
  ```
56
78
 
57
- `postinstall` automatically runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
79
+ `postinstall` runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
58
80
 
59
- ### Fullstack mode
81
+ ### Fullstack
60
82
 
61
83
  ```bash
62
- npm run dev # node --watch src/server.js
63
- # → http://localhost:3000
84
+ npm run dev # node --watch --env-file=.env src/server.js
64
85
  ```
65
86
 
66
- ### Static mode
87
+ ### Static
67
88
 
68
89
  ```bash
69
90
  npx serve public # or any static file server
70
91
  ```
71
92
 
72
- ## 3. Development Workflow
93
+ ## 5. Development Rules
73
94
 
74
- ### Create a component
75
-
76
- Every component is a plain ES module that exports a Hybrids descriptor. Place it in the appropriate atomic design tier:
77
-
78
- ```
79
- src/components/atoms/ # buttons, icons, badges
80
- src/components/molecules/ # form fields, cards
81
- src/components/organisms/ # lists, editors, canvases
82
- src/components/pages/ # route-level views
83
- ```
84
-
85
- Register it in `src/components/index.js` and add a `<script>` or import map entry in `public/index.html` if needed.
86
-
87
- ### Key rules while coding
88
-
89
- - **≤150 lines per `.js` / `.css` file.** Add `// SPLIT CANDIDATE:` at 120 lines. When you hit the limit, extract a module.
95
+ - **≤150 lines per `.js` / `.css` file.** Add `// SPLIT CANDIDATE:` at ~120 lines.
90
96
  - **Light DOM by default.** No `shadowRoot`. Shared styles in `src/styles/` apply everywhere.
91
97
  - **JSDoc for types.** `@typedef`, `@param`, `@returns` — validated by `tsc --checkJs`.
92
98
  - **No build step.** Every file runs as-is in the browser via ES modules and import maps.
93
99
 
94
- ### Run checks during development
95
-
96
- ```bash
97
- npm run lint:fix # ESLint auto-fix
98
- npm run format # Prettier auto-format
99
- npm run typecheck # JSDoc type validation
100
- npm test # Node + browser tests
101
- npm run spec # Full interactive spec compliance check
102
- ```
103
-
104
- Or run individual spec checks:
105
-
106
- ```bash
107
- npm run spec:code # Code files ≤150 lines
108
- npm run spec:docs # Doc files ≤500 lines
109
- ```
110
-
111
- ## 4. Project-Specific Specs
100
+ ## 6. Project-Specific Specs
112
101
 
113
- The `docs/app-spec/` directory is yours. Upstream updates never touch it. Use it for:
102
+ `docs/app-spec/` is yours. Upstream updates never touch it. Use it for:
114
103
 
115
104
  - Entity schemas and relationships
116
- - Project-specific patterns or conventions
105
+ - Project-specific component patterns
117
106
  - API documentation beyond the base spec
118
107
  - Architecture decisions (ADRs)
119
- - Deviations from the spec (with rationale)
108
+ - Deviations from the base spec (with rationale)
120
109
 
121
- See [docs/app-spec/README.md](./app-spec/README.md) for the full guide.
110
+ See [docs/app-spec/README.md](./app-spec/README.md) for examples.
122
111
 
123
- ## 5. Update Spec Docs
112
+ ## 7. Updating
124
113
 
125
- When the spec evolves upstream, pull the latest docs into your project:
114
+ When Clearstack releases a new version:
126
115
 
127
116
  ```bash
128
- npx clearstack update
117
+ npm update @techninja/clearstack # bump the package
118
+ npm run spec:update # sync docs + configs
119
+ git diff docs/ .configs/ # review what changed
129
120
  ```
130
121
 
131
- This:
132
- - Copies updated spec docs from the package into your `docs/clearstack/` directory
133
- - Syncs `.configs/` to latest standards
134
- - Skips `docs/app-spec/` entirely — your project-specific specs are safe
135
- - Writes a `.specversion` file so you can track which version you're on
136
- - Prints which files changed so you can review with `git diff docs/ .configs/`
137
-
138
- Review the diff, adjust your code if needed, then commit.
122
+ This updates:
123
+ - `docs/clearstack/*.md` — spec documentation
124
+ - `.configs/*` — linter, formatter, type checker, test runner configs
139
125
 
140
- ## 6. Check Spec Compliance
126
+ This never touches:
127
+ - `docs/app-spec/` — your project specs
128
+ - `src/` — your code
129
+ - `scripts/` — your build scripts
130
+ - `.env` — your thresholds and settings
141
131
 
142
- Run the full compliance suite at any time:
132
+ ## 8. Spec Compliance
143
133
 
144
134
  ```bash
145
- npx clearstack check
135
+ npm run spec # full check via clearstack binary
136
+ npm run spec:code # code files ≤150 lines
137
+ npm run spec:docs # doc files ≤500 lines
138
+ npm run lint:fix # ESLint auto-fix
139
+ npm run format # Prettier auto-format
140
+ npm run typecheck # JSDoc type validation
141
+ npm test # Node + browser tests
146
142
  ```
147
143
 
148
- This runs from the scaffolder package itself (no local scripts needed). It checks:
149
-
150
- 1. **Code line counts** — all `.js` / `.css` files ≤150 lines
151
- 2. **Doc line counts** — all `.md` files ≤500 lines
152
- 3. **ESLint** — linting with the spec's config
153
- 4. **Prettier** — formatting with the spec's config
154
- 5. **JSDoc types** — `tsc --checkJs` against jsconfig
155
-
156
- The same checks run in CI via the GitHub Actions workflow scaffolded into `.github/`.
157
-
158
144
  ### Configuring thresholds
159
145
 
160
146
  Override defaults in `.env`:
@@ -167,24 +153,25 @@ SPEC_DOCS_EXTENSIONS=.md
167
153
  SPEC_IGNORE_DIRS=node_modules,public/vendor,.git,.configs
168
154
  ```
169
155
 
170
- ## 7. CI Pipeline
156
+ ## 9. CI Pipeline
171
157
 
172
- The scaffolded `.github/workflows/` runs all spec checks on every PR. A PR cannot merge unless all checks pass. The workflow runs:
158
+ The scaffolded `.github/workflows/spec.yml` runs all checks on every PR:
173
159
 
174
160
  ```
175
- npm run spec:code → npm run spec:docs → npm run lint → npm run format → npm run typecheck → npm test
161
+ spec:code → spec:docs → lint → format → typecheck → test
176
162
  ```
177
163
 
178
164
  ## Summary
179
165
 
180
166
  | Task | Command |
181
167
  |---|---|
168
+ | Install Clearstack | `npm install -D @techninja/clearstack` |
182
169
  | Scaffold a project | `npx clearstack init` |
183
170
  | Install dependencies | `npm install` |
184
- | Start dev server | `npm run dev` (fullstack) / `npx serve public` (static) |
171
+ | Start dev server | `npm run dev` / `npx serve public` |
185
172
  | Lint + format | `npm run lint:fix && npm run format` |
186
173
  | Type check | `npm run typecheck` |
187
174
  | Run tests | `npm test` |
188
- | Full spec check | `npm run spec` or `npx clearstack check` |
189
- | Update spec docs | `npx clearstack update` |
175
+ | Full spec check | `npm run spec` |
176
+ | Update spec + configs | `npm run spec:update` |
190
177
  | Review spec changes | `git diff docs/ .configs/` |