@techninja/clearstack 0.3.11 → 0.3.13

package/README.md

@@ -29,17 +29,17 @@ A project/task tracker that exercises every pattern in the spec: API-backed enti
 
 ## Specification
 
-| Document | What It Covers |
-|---|---|
+| Document                                                                    | What It Covers                                                 |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | [FRONTEND_IMPLEMENTATION_RULES.md](./docs/FRONTEND_IMPLEMENTATION_RULES.md) | Philosophy, framework choice, project structure, atomic design |
-| [COMPONENT_PATTERNS.md](./docs/COMPONENT_PATTERNS.md) | Authoring, light DOM, styling, layout engine, JSDoc typing |
-| [STATE_AND_ROUTING.md](./docs/STATE_AND_ROUTING.md) | Store, routing, unified app state, realtime SSE sync |
-| [CONVENTIONS.md](./docs/CONVENTIONS.md) | Naming rules, anti-patterns |
-| [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md) | Express server, import maps, vendor dependency loading |
-| [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md) | REST CRUD, JSON Schema via HEAD, entity management |
-| [TESTING.md](./docs/TESTING.md) | Testing philosophy, tools, patterns, phase checkpoints |
-| [BUILD_LOG.md](./docs/BUILD_LOG.md) | How this project was built — LLM-human collaboration proof |
-| [QUICKSTART.md](./docs/QUICKSTART.md) | Scaffolder setup, development workflow, updating, compliance |
+| [COMPONENT_PATTERNS.md](./docs/COMPONENT_PATTERNS.md)                       | Authoring, light DOM, styling, layout engine, JSDoc typing     |
+| [STATE_AND_ROUTING.md](./docs/STATE_AND_ROUTING.md)                         | Store, routing, unified app state, realtime SSE sync           |
+| [CONVENTIONS.md](./docs/CONVENTIONS.md)                                     | Naming rules, anti-patterns                                    |
+| [SERVER_AND_DEPS.md](./docs/SERVER_AND_DEPS.md)                             | Express server, import maps, vendor dependency loading         |
+| [BACKEND_API_SPEC.md](./docs/BACKEND_API_SPEC.md)                           | REST CRUD, JSON Schema via HEAD, entity management             |
+| [TESTING.md](./docs/TESTING.md)                                             | Testing philosophy, tools, patterns, phase checkpoints         |
+| [BUILD_LOG.md](./docs/BUILD_LOG.md)                                         | How this project was built — LLM-human collaboration proof     |
+| [QUICKSTART.md](./docs/QUICKSTART.md)                                       | Scaffolder setup, development workflow, updating, compliance   |
 
 ## Using Clearstack
 
@@ -48,7 +48,8 @@ Install as a dev dependency, scaffold, and keep in sync:
 ```bash
 npm install -D @techninja/clearstack    # add to your project
 npx clearstack init                     # scaffold (interactive)
-npx clearstack init -y                  # scaffold (defaults)
+npx clearstack init -y                  # scaffold (fullstack defaults)
+npx clearstack init --static            # scaffold (static, no server)
 npm run spec                            # check compliance
 npm run spec:update                     # sync docs + configs on upgrade
 ```

package/bin/cli.js

@@ -3,7 +3,7 @@
 /**
  * clearstack CLI — scaffold, update, and check spec-compliant projects.
  * Usage:
- *   clearstack init [-y] [--mode fullstack|static] [--port 3000]
+ *   clearstack init [-y] [--static|--fullstack] [--port 3000]
  *   clearstack update
  *   clearstack check [code|docs|imports|lint|lint es|format|types|audit|all]
  *   clearstack                   → interactive menu
@@ -22,6 +22,8 @@ const flags = Object.fromEntries(
   }),
 );
 const yes = args.includes('-y') || args.includes('--yes');
+if (flags.static) flags.mode = 'static';
+if (flags.fullstack) flags.mode = 'fullstack';
 
 /** Show interactive menu. */
 async function interactive() {

package/docs/CONVENTIONS.md

@@ -267,6 +267,25 @@ This prevents premature extraction while keeping the eventual split obvious.
 function moveObj(o, dx, dy) { ... }
 ```
 
+### When a File Exceeds 150 Lines
+
+The **only correct response** is to split the file into two or more files.
+Never do any of the following to reduce line count:
+
+- Remove or shorten JSDoc comments
+- Collapse multi-line expressions onto one line
+- Remove blank lines between logical sections
+- Combine unrelated functions into one
+- Delete code that is still needed
+
+These make the code harder to read, which defeats the purpose of the limit.
+The limit exists to force decomposition, not compression.
+
+The spec checker runs formatters (Prettier, ESLint `--fix`) **before**
+counting lines, so the line count always reflects the formatted result.
+Write code in its natural readable form, run `npm run spec all`, and if
+a file is over the limit, split it.
+
 ---
 
 ## npm Scripts: One Entry Point Per Domain
@@ -328,6 +347,53 @@ multiple keys.
 Spec is the inner dev loop — run it constantly. Tests are the commit gate —
 run them before pushing. CI runs both, in parallel.
 
+### Spec Output Contract
+
+The spec checker is designed for **minimal, complete output**. Every check
+prints exactly one line: ✅ on pass, ❌ on fail with the violating file and
+reason. The final summary is 2 lines (`N/N checks passed`).
+
+Total output for a passing run is ~12 lines. A failing run adds one line
+per violation with the exact file path and what to fix.
+
+**Do not pipe, grep, tail, or filter spec output.** It is already the
+minimal actionable result. Filtering it discards the violation details
+that tell you which file to fix, forcing redundant re-runs.
+
+To narrow scope, run a targeted check instead of filtering `all`:
+
+```bash
+# Run everything
+npm run spec all
+
+# Run one check by key
+npm run spec code          # line counts (code files ≤150)
+npm run spec docs          # line counts (doc files ≤500)
+npm run spec imports       # import map aliases (no ../)
+npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec audit         # security audit
+
+# Parent keys run all children
+npm run spec lint           # ESLint + Stylelint + Markdown lint
+npm run spec format         # Prettier (all formatters)
+
+# Child keys run one
+npm run spec lint es        # ESLint only
+npm run spec lint css       # Stylelint only
+npm run spec lint md        # Markdown lint only
+npm run spec format prettier
+```
+
+```bash
+# ❌ Wrong — discards violation file paths
+npm run spec all 2>&1 | tail -3
+npm run spec all 2>&1 | grep -E "pass|fail"
+```
+
+This matters especially for LLM-assisted development: the spec output is
+structured so an LLM can read it in one pass, identify the failing file,
+and fix it without re-running the check. Filtering breaks that loop.
+
 ---
 
 ## Session Retrospective

package/docs/QUICKSTART.md

@@ -22,8 +22,10 @@ pnpm add -D @techninja/clearstack
 From your project root:
 
 ```bash
-npx clearstack init        # interactive
-npx clearstack init -y     # non-interactive (defaults)
+npx clearstack init            # interactive
+npx clearstack init -y         # non-interactive (fullstack defaults)
+npx clearstack init --static   # non-interactive, static mode
+npx clearstack init -y --static # same as above
 ```
 
 The interactive prompt asks for:
@@ -159,7 +161,8 @@ spec:code → spec:docs → lint → format → typecheck → test
 | Task                  | Command                                |
 | --------------------- | -------------------------------------- |
 | Install Clearstack    | `npm install -D @techninja/clearstack` |
-| Scaffold a project    | `npx clearstack init`                  |
+| Scaffold (fullstack)  | `npx clearstack init`                  |
+| Scaffold (static)     | `npx clearstack init --static`         |
 | Install dependencies  | `npm install`                          |
 | Start dev server      | `npm run dev`                          |
 | Lint + format         | `npm run lint:fix && npm run format`   |

package/lib/check.js

@@ -69,12 +69,6 @@ export function buildChecks(dir, cfg, cmds) {
   const css = () => countFiles(dir, ['.css'], cfg.ignore);
   const md = () => countFiles(dir, ['.md'], cfg.ignore);
   return [
-    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`) },
-    { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
-      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`) },
-    { key: 'imports', name: 'Import map aliases (no ../ imports)',
-      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)') },
     { key: 'es', name: 'ESLint', parent: 'lint',
       run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`) },
     { key: 'css', name: 'Stylelint', parent: 'lint',
@@ -83,6 +77,12 @@ export function buildChecks(dir, cfg, cmds) {
       run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`) },
     { key: 'prettier', name: 'Prettier', parent: 'format',
       run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`) },
+    { key: 'code', name: `Code (max ${cfg.codeMax} lines)`,
+      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`) },
+    { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
+      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`) },
+    { key: 'imports', name: 'Import map aliases (no ../ imports)',
+      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)') },
     { key: 'types', name: 'JSDoc types (tsc --checkJs)',
       run: () => runCmd('JSDoc types', cmds.types, dir, `${js()} files`) },
     { key: 'audit', name: 'Security audit',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/docs/clearstack/CONVENTIONS.md

@@ -267,6 +267,25 @@ This prevents premature extraction while keeping the eventual split obvious.
 function moveObj(o, dx, dy) { ... }
 ```
 
+### When a File Exceeds 150 Lines
+
+The **only correct response** is to split the file into two or more files.
+Never do any of the following to reduce line count:
+
+- Remove or shorten JSDoc comments
+- Collapse multi-line expressions onto one line
+- Remove blank lines between logical sections
+- Combine unrelated functions into one
+- Delete code that is still needed
+
+These make the code harder to read, which defeats the purpose of the limit.
+The limit exists to force decomposition, not compression.
+
+The spec checker runs formatters (Prettier, ESLint `--fix`) **before**
+counting lines, so the line count always reflects the formatted result.
+Write code in its natural readable form, run `npm run spec all`, and if
+a file is over the limit, split it.
+
 ---
 
 ## npm Scripts: One Entry Point Per Domain
@@ -328,6 +347,53 @@ multiple keys.
 Spec is the inner dev loop — run it constantly. Tests are the commit gate —
 run them before pushing. CI runs both, in parallel.
 
+### Spec Output Contract
+
+The spec checker is designed for **minimal, complete output**. Every check
+prints exactly one line: ✅ on pass, ❌ on fail with the violating file and
+reason. The final summary is 2 lines (`N/N checks passed`).
+
+Total output for a passing run is ~12 lines. A failing run adds one line
+per violation with the exact file path and what to fix.
+
+**Do not pipe, grep, tail, or filter spec output.** It is already the
+minimal actionable result. Filtering it discards the violation details
+that tell you which file to fix, forcing redundant re-runs.
+
+To narrow scope, run a targeted check instead of filtering `all`:
+
+```bash
+# Run everything
+npm run spec all
+
+# Run one check by key
+npm run spec code          # line counts (code files ≤150)
+npm run spec docs          # line counts (doc files ≤500)
+npm run spec imports       # import map aliases (no ../)
+npm run spec types         # JSDoc types (tsc --checkJs)
+npm run spec audit         # security audit
+
+# Parent keys run all children
+npm run spec lint           # ESLint + Stylelint + Markdown lint
+npm run spec format         # Prettier (all formatters)
+
+# Child keys run one
+npm run spec lint es        # ESLint only
+npm run spec lint css       # Stylelint only
+npm run spec lint md        # Markdown lint only
+npm run spec format prettier
+```
+
+```bash
+# ❌ Wrong — discards violation file paths
+npm run spec all 2>&1 | tail -3
+npm run spec all 2>&1 | grep -E "pass|fail"
+```
+
+This matters especially for LLM-assisted development: the spec output is
+structured so an LLM can read it in one pass, identify the failing file,
+and fix it without re-running the check. Filtering breaks that loop.
+
 ---
 
 ## Session Retrospective

package/templates/shared/docs/clearstack/QUICKSTART.md

@@ -22,8 +22,10 @@ pnpm add -D @techninja/clearstack
 From your project root:
 
 ```bash
-npx clearstack init        # interactive
-npx clearstack init -y     # non-interactive (defaults)
+npx clearstack init            # interactive
+npx clearstack init -y         # non-interactive (fullstack defaults)
+npx clearstack init --static   # non-interactive, static mode
+npx clearstack init -y --static # same as above
 ```
 
 The interactive prompt asks for:
@@ -159,7 +161,8 @@ spec:code → spec:docs → lint → format → typecheck → test
 | Task                  | Command                                |
 | --------------------- | -------------------------------------- |
 | Install Clearstack    | `npm install -D @techninja/clearstack` |
-| Scaffold a project    | `npx clearstack init`                  |
+| Scaffold (fullstack)  | `npx clearstack init`                  |
+| Scaffold (static)     | `npx clearstack init --static`         |
 | Install dependencies  | `npm install`                          |
 | Start dev server      | `npm run dev`                          |
 | Lint + format         | `npm run lint:fix && npm run format`   |