@techninja/clearstack 0.2.0

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

@@ -0,0 +1,239 @@
+# Frontend Implementation Rules
+## Hybrids.js "No-Build" Web Component Specification
+
+> A concise, LLM-and-human-friendly specification for building web applications
+> with Hybrids v9 using ES modules, no bundler, and atomic design principles.
+
+---
+
+## Table of Contents
+
+**This file:** Foundation — philosophy, framework, structure, atomic design.
+
+1. [Philosophy & Constraints](#1-philosophy--constraints)
+2. [Framework Choice: Hybrids.js](#2-framework-choice-hybridsjs)
+3. [Project Structure](#3-project-structure)
+4. [Atomic Design Hierarchy](#4-atomic-design-hierarchy)
+
+**Sub-specifications:**
+
+| Document | Covers |
+|---|---|
+| [COMPONENT_PATTERNS.md](./COMPONENT_PATTERNS.md) | Authoring, light DOM, styling, layout engine, file size rules |
+| [JSDOC_TYPING.md](./JSDOC_TYPING.md) | JSDoc typing strategy, tsc validation, component/model/handler patterns |
+| [STATE_AND_ROUTING.md](./STATE_AND_ROUTING.md) | Store, routing, unified app state, realtime sync |
+| [CONVENTIONS.md](./CONVENTIONS.md) | Naming conventions, anti-patterns |
+| [SERVER_AND_DEPS.md](./SERVER_AND_DEPS.md) | Express server, import maps, vendor dependency loading |
+| [BACKEND_API_SPEC.md](./BACKEND_API_SPEC.md) | REST endpoints, JSON Schema via HEAD, entity CRUD, realtime sync |
+| [TESTING.md](./TESTING.md) | Testing philosophy, tools, patterns, build-phase checkpoints |
+
+---
+
+## 1. Philosophy & Constraints
+
+This specification defines a **zero-build** frontend architecture. No bundler,
+no transpiler, no compile step. Code runs exactly as written.
+
+### Core Principles
+
+| Principle | Rule |
+|---|---|
+| No build tools | No Webpack, Vite, Rollup, esbuild, or Babel |
+| ES modules only | All `.js` files are native ES modules served to the browser |
+| Import maps | Bare specifiers (e.g. `"hybrids"`) resolved via `<script type="importmap">` |
+| Small files | Every file ≤ **150 lines** before extracting shared logic |
+| Explicit over implicit | Name things clearly; avoid magic strings and hidden conventions |
+| Readable over clever | Optimize for comprehension by humans and LLMs alike |
+| Declarative over imperative | Use framework patterns, not raw DOM manipulation |
+| Composition over inheritance | Build complex UIs by composing small components |
+
+### What This Means in Practice
+
+- You can open any `.js` file in the browser devtools and see the source as-is.
+- Adding a new component means creating files and importing them — no config.
+- Third-party dependencies are vendored as ES modules at install time.
+- The server is a thin static file host with no middleware transforms.
+
+### Constraints
+
+- **No TypeScript** — plain JavaScript with JSDoc comments where types help.
+- **No CSS preprocessors** — plain CSS with custom properties for tokens.
+- **No framework CLI** — manual file creation following this spec's conventions.
+- **No dynamic `import()` for core components** — static imports for the
+  dependency graph to remain visible and traceable.
+- **Node.js ≥ 18** — required for the Express server and `--watch` flag.
+
+---
+
+## 2. Framework Choice: Hybrids.js
+
+We use **[Hybrids v9](https://hybrids.js.org)** — a functional, declarative
+web component framework built on plain objects and pure functions.
+
+### Why Hybrids
+
+| Need | Hybrids Provides |
+|---|---|
+| Components | `define()` — plain object definitions, no classes |
+| Templating | `html``` — tagged template literals with reactive bindings |
+| State | `store()` — global state with async storage, caching, relations |
+| Routing | `router()` — view-graph-based routing with guards and dialogs |
+| Layout | `layout=""` attribute — CSS layout engine in templates |
+| Localization | `localize()` — automatic template translation |
+| ES modules | Ships as raw ES modules in `src/` — no build needed |
+
+### API Surface (v9.1)
+
+These are the only imports you need:
+
+```javascript
+import {
+  define,       // Register a component
+  html,         // Template tagged literal
+  store,        // State management
+  router,       // Routing
+  mount,        // Mount component on existing element
+  parent,       // Access parent component
+  children,     // Access child components
+  dispatch,     // Dispatch custom events
+  msg,          // Localization messages
+  localize,     // Register translations
+} from 'hybrids';
+```
+
+### Why Not Alternatives
+
+| Alternative | Reason to pass |
+|---|---|
+| **Lit** | Class-based, heavier API surface, decorators encourage build tools |
+| **Stencil** | Requires a compiler — violates no-build constraint |
+| **Vanilla** | No state management, no templating — too much boilerplate |
+| **React/Vue/Svelte** | Require build steps, not native web components |
+
+---
+
+## 3. Project Structure
+
+```
+project-root/
+├── public/                          # Static assets served at /
+│   ├── index.html                   # App shell with import map
+│   └── vendor/                      # Vendored ES module deps (generated)
+│       └── hybrids/                 # Copied from node_modules at install
+│
+├── src/                             # Application source (served at /src/)
+│   ├── components/                  # UI components (atomic design)
+│   │   ├── atoms/                   # Smallest UI primitives
+│   │   │   └── app-button/
+│   │   │       ├── app-button.js    # Component definition
+│   │   │       ├── app-button.css   # Scoped styles
+│   │   │       └── index.js         # Re-export
+│   │   ├── molecules/               # Compositions of atoms
+│   │   │   └── search-bar/
+│   │   ├── organisms/               # Complex UI sections
+│   │   │   └── app-header/
+│   │   └── templates/               # Page-level layout shells
+│   │       └── page-layout/
+│   │
+│   ├── pages/                       # Route-bound view components
+│   │   ├── home/
+│   │   │   ├── home-view.js
+│   │   │   └── index.js
+│   │   └── about/
+│   │
+│   ├── store/                       # Hybrids store model definitions
+│   │   ├── AppState.js              # Singleton: global app state
+│   │   └── UserModel.js             # Enumerable: user records
+│   │
+│   ├── router/                      # Router shell component
+│   │   └── index.js
+│   │
+│   ├── styles/                      # Shared CSS
+│   │   ├── tokens.css               # Design tokens (colors, spacing)
+│   │   └── reset.css                # Minimal CSS reset
+│   │
+│   └── utils/                       # Pure helper functions
+│       └── formatDate.js
+│
+├── scripts/                         # Build/install scripts
+│   └── vendor-deps.js               # Copies deps to public/vendor/
+│
+├── src/server.js                    # Express entry point
+├── package.json                     # type: "module", postinstall hook
+├── README.md                        # Project overview
+└── FRONTEND_IMPLEMENTATION_RULES.md # This file
+```
+
+### Key Conventions
+
+- **One component per directory.** Each gets its own folder with `.js`, `.css`,
+  and `index.js` (re-export).
+- **`src/` is served as-is** — the browser loads these files directly.
+- **`public/vendor/`** is gitignored and regenerated on `npm install` via the
+  `postinstall` script.
+- **No barrel files** beyond the per-component `index.js`. Import from the
+  component directory, not from a giant `components/index.js`.
+- **Pages are not components.** They live in `src/pages/`, not in
+  `src/components/`. They compose components but are themselves route targets.
+
+---
+
+## 4. Atomic Design Hierarchy
+
+Components are organized into four tiers. Each tier has a clear scope and
+import direction: **higher tiers import from lower tiers, never the reverse.**
+
+### Tiers
+
+| Tier | Location | Scope | Examples |
+|---|---|---|---|
+| **Atom** | `components/atoms/` | Single-purpose UI primitive. One element, one job. | `app-button`, `app-icon`, `app-input` |
+| **Molecule** | `components/molecules/` | Small composition of 2–4 atoms that form a reusable unit. | `nav-link`, `search-bar`, `form-field` |
+| **Organism** | `components/organisms/` | Complex UI section. May contain molecules, atoms, and local state. | `app-header`, `app-footer`, `user-card` |
+| **Template** | `components/templates/` | Page-level layout shell. Defines slot regions, no business logic. | `page-layout`, `dashboard-layout` |
+
+**Pages** (`src/pages/`) sit outside the component hierarchy. They are
+route-bound views that compose templates and organisms.
+
+### Import Direction
+
+```
+Pages → Templates → Organisms → Molecules → Atoms
+                                                ↑
+                                          Store / Utils
+```
+
+- Atoms import **nothing** from other component tiers.
+- Molecules import only from **atoms**.
+- Organisms import from **molecules** and **atoms**.
+- Templates import from **organisms**, **molecules**, and **atoms**.
+- Pages import from **any component tier** and from **store/router**.
+- **Store models and utils** are shared — any tier may import them.
+
+### When to Promote a Component
+
+Use this checklist to decide if a component belongs at a higher tier:
+
+| Signal | Action |
+|---|---|
+| It renders a single HTML element with props | Keep as **atom** |
+| It composes 2–4 atoms into a reusable group | Make it a **molecule** |
+| It has its own local state or fetches data | Promote to **organism** |
+| It defines layout regions via slots, no logic | Make it a **template** |
+| It's bound to a route and composes a full page | Put it in **pages/** |
+
+### File Anatomy (All Tiers)
+
+Every component directory contains exactly three files:
+
+```
+app-button/
+├── app-button.js    # Component definition (define + html + logic)
+├── app-button.css   # Scoped styles for this component
+└── index.js         # export { default } from './app-button.js';
+```
+
+If a component needs helpers that push it past 150 lines, extract them to
+`src/utils/` — not into sibling files within the component directory.
+
+

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

@@ -0,0 +1,86 @@
+# JSDoc Typing Strategy
+## Type Safety Without TypeScript
+
+> JSDoc annotations provide editor intellisense, LLM comprehension, and
+> compile-time type checking — all without a build step.
+> See [COMPONENT_PATTERNS.md](./COMPONENT_PATTERNS.md) for component authoring.
+
+---
+
+## How It Works
+
+TypeScript's `tsc` compiler validates JSDoc annotations via `--checkJs`,
+giving us compile-time type checking without a build step.
+
+A `jsconfig.json` at the project root enables `checkJs: true`. Running
+`npm run typecheck` invokes `tsc --project jsconfig.json` which:
+
+1. Reads all `.js` files in `src/` and `scripts/`
+2. Parses JSDoc annotations as type information
+3. Reports type errors exactly like TypeScript would
+4. Emits nothing — `noEmit: true`
+
+This means `@typedef`, `@type`, `@param`, and `@returns` are not just
+documentation — they are **enforced types**.
+
+---
+
+## Component Properties
+
+```javascript
+/**
+ * @typedef {Object} AppButtonHost
+ * @property {string} label - Button display text
+ * @property {'primary'|'secondary'|'ghost'} variant - Visual style
+ * @property {boolean} disabled - Disabled state
+ */
+
+/** @type {import('hybrids').Component<AppButtonHost>} */
+export default define({
+  tag: 'app-button',
+  label: '',
+  variant: 'primary',
+  disabled: false,
+  render: ({ label, variant, disabled }) => html`
+    <button class="${variant}" disabled="${disabled}">${label}</button>
+  `,
+});
+```
+
+## Store Models
+
+```javascript
+/**
+ * @typedef {Object} User
+ * @property {string} id - Unique identifier
+ * @property {string} firstName
+ * @property {string} lastName
+ * @property {string} email
+ */
+
+/** @type {import('hybrids').Model<User>} */
+const UserModel = { id: true, firstName: '', lastName: '', email: '' };
+```
+
+## Event Handlers
+
+```javascript
+/**
+ * Increment the counter on the host element.
+ * @param {AppCounterHost & HTMLElement} host
+ * @param {MouseEvent} event
+ */
+function handleClick(host, event) {
+  host.count++;
+}
+```
+
+## Rules
+
+- Every exported component gets a `@typedef` for its host interface.
+- Every store model gets a `@typedef` for its shape.
+- Event handlers document `host` and `event` param types.
+- Keep JSDoc blocks to 3–5 lines. No novels.
+- Use `/** @type {any} */ (expr)` for framework type limitations (e.g.
+  `store.pending()` on array results) — document why with a comment.
+- Run `npm run typecheck` before committing. Zero errors required.

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

@@ -0,0 +1,190 @@
+# Quickstart
+
+Get a spec-compliant project running, develop against it, and keep it in sync as the spec evolves.
+
+## Prerequisites
+
+- Node.js ≥ 20
+- npm ≥ 10
+
+## 1. Scaffold a New Project
+
+```bash
+npx clearstack init
+```
+
+The interactive prompt asks for:
+
+| Prompt | Default | Notes |
+|---|---|---|
+| Project name | `my-app` | Creates a directory with this name |
+| Description | `A Clearstack project` | Goes into package.json |
+| Mode | — | **Fullstack**: Express + WebSocket + JSON DB + SSE. **Static**: localStorage only, no server |
+| Port | `3000` | Fullstack only. Set in `.env` |
+| Include examples? | Yes | Starter components demonstrating spec patterns |
+
+This generates a complete project directory:
+
+```
+my-app/
+├── .configs/          # eslint, prettier, jsconfig, web-test-runner
+├── .github/           # CI workflow, PR + issue templates
+├── docs/              # Spec docs (upstream-managed)
+│   ├── clearstack/    # Clearstack spec docs (synced on update)
+│   └── app-spec/      # Your project-specific specs (never overwritten)
+├── public/            # Static assets, index.html, import map
+├── scripts/           # vendor-deps, build-icons, spec checker
+├── src/
+│   ├── components/    # atoms/, molecules/, organisms/, pages/
+│   ├── store/         # Hybrids store models
+│   ├── styles/        # Global CSS with native nesting
+│   ├── router/        # Client-side routing
+│   └── utils/         # Shared helpers
+├── tests/             # Node + browser tests
+├── data/              # JSON DB (fullstack only)
+├── src/server.js       # Express server (fullstack only)
+├── .env               # PORT, spec thresholds
+└── package.json
+```
+
+## 2. Install and Run
+
+```bash
+cd my-app
+npm install
+```
+
+`postinstall` automatically runs `vendor-deps.js` (copies hybrids to `public/vendor/`) and `build-icons.js` (extracts Lucide SVGs to `public/icons.json`).
+
+### Fullstack mode
+
+```bash
+npm run dev            # node --watch src/server.js
+# → http://localhost:3000
+```
+
+### Static mode
+
+```bash
+npx serve public       # or any static file server
+```
+
+## 3. Development Workflow
+
+### Create a component
+
+Every component is a plain ES module that exports a Hybrids descriptor. Place it in the appropriate atomic design tier:
+
+```
+src/components/atoms/       # buttons, icons, badges
+src/components/molecules/   # form fields, cards
+src/components/organisms/   # lists, editors, canvases
+src/components/pages/       # route-level views
+```
+
+Register it in `src/components/index.js` and add a `<script>` or import map entry in `public/index.html` if needed.
+
+### Key rules while coding
+
+- **≤150 lines per `.js` / `.css` file.** Add `// SPLIT CANDIDATE:` at 120 lines. When you hit the limit, extract a module.
+- **Light DOM by default.** No `shadowRoot`. Shared styles in `src/styles/` apply everywhere.
+- **JSDoc for types.** `@typedef`, `@param`, `@returns` — validated by `tsc --checkJs`.
+- **No build step.** Every file runs as-is in the browser via ES modules and import maps.
+
+### Run checks during development
+
+```bash
+npm run lint:fix       # ESLint auto-fix
+npm run format         # Prettier auto-format
+npm run typecheck      # JSDoc type validation
+npm test               # Node + browser tests
+npm run spec           # Full interactive spec compliance check
+```
+
+Or run individual spec checks:
+
+```bash
+npm run spec:code      # Code files ≤150 lines
+npm run spec:docs      # Doc files ≤500 lines
+```
+
+## 4. Project-Specific Specs
+
+The `docs/app-spec/` directory is yours. Upstream updates never touch it. Use it for:
+
+- Entity schemas and relationships
+- Project-specific patterns or conventions
+- API documentation beyond the base spec
+- Architecture decisions (ADRs)
+- Deviations from the spec (with rationale)
+
+See [docs/app-spec/README.md](./app-spec/README.md) for the full guide.
+
+## 5. Update Spec Docs
+
+When the spec evolves upstream, pull the latest docs into your project:
+
+```bash
+npx clearstack update
+```
+
+This:
+- Copies updated spec docs from the package into your `docs/clearstack/` directory
+- Syncs `.configs/` to latest standards
+- Skips `docs/app-spec/` entirely — your project-specific specs are safe
+- Writes a `.specversion` file so you can track which version you're on
+- Prints which files changed so you can review with `git diff docs/ .configs/`
+
+Review the diff, adjust your code if needed, then commit.
+
+## 6. Check Spec Compliance
+
+Run the full compliance suite at any time:
+
+```bash
+npx clearstack check
+```
+
+This runs from the scaffolder package itself (no local scripts needed). It checks:
+
+1. **Code line counts** — all `.js` / `.css` files ≤150 lines
+2. **Doc line counts** — all `.md` files ≤500 lines
+3. **ESLint** — linting with the spec's config
+4. **Prettier** — formatting with the spec's config
+5. **JSDoc types** — `tsc --checkJs` against jsconfig
+
+The same checks run in CI via the GitHub Actions workflow scaffolded into `.github/`.
+
+### Configuring thresholds
+
+Override defaults in `.env`:
+
+```bash
+SPEC_CODE_MAX_LINES=150
+SPEC_DOCS_MAX_LINES=500
+SPEC_CODE_EXTENSIONS=.js,.css
+SPEC_DOCS_EXTENSIONS=.md
+SPEC_IGNORE_DIRS=node_modules,public/vendor,.git,.configs
+```
+
+## 7. CI Pipeline
+
+The scaffolded `.github/workflows/` runs all spec checks on every PR. A PR cannot merge unless all checks pass. The workflow runs:
+
+```
+npm run spec:code → npm run spec:docs → npm run lint → npm run format → npm run typecheck → npm test
+```
+
+## Summary
+
+| Task | Command |
+|---|---|
+| Scaffold a project | `npx clearstack init` |
+| Install dependencies | `npm install` |
+| Start dev server | `npm run dev` (fullstack) / `npx serve public` (static) |
+| Lint + format | `npm run lint:fix && npm run format` |
+| Type check | `npm run typecheck` |
+| Run tests | `npm test` |
+| Full spec check | `npm run spec` or `npx clearstack check` |
+| Update spec docs | `npx clearstack update` |
+| Review spec changes | `git diff docs/ .configs/` |

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

@@ -0,0 +1,163 @@
+# Server & Dependencies
+## Express Server, Import Maps & Vendor Loading
+
+> How the backend serves the frontend and how dependencies are resolved
+> without a build step.
+> See [BACKEND_API_SPEC.md](./BACKEND_API_SPEC.md) for the REST API contract.
+
+---
+
+## Express Server
+
+`src/server.js` is a minimal Express app that serves static files and the API.
+
+### Responsibilities
+
+| Route | Serves |
+|---|---|
+| `/` | `public/index.html` (app shell) |
+| `/vendor/*` | `public/vendor/` (vendored ES modules) |
+| `/src/*` | `src/` (application source, as-is) |
+| `/api/*` | REST endpoints (see BACKEND_API_SPEC) |
+| `/api/events` | SSE stream for realtime sync |
+
+### Key Rules
+
+- **No middleware transforms.** Files are served byte-for-byte.
+- **Correct MIME types.** `.js` files must be served as `application/javascript`.
+- **No templating engine.** The HTML shell is a static file.
+- **CORS not needed** — frontend and API share the same origin.
+
+### src/server.js Structure
+
+```javascript
+import express from 'express';
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// Static: vendored deps and app shell
+app.use(express.static('public'));
+
+// Static: application source (ES modules served directly)
+app.use('/src', express.static('src'));
+
+// API routes
+// (see BACKEND_API_SPEC.md for full contract)
+app.use(express.json());
+
+// ... mount API routes here ...
+
+app.listen(PORT, () => console.log(`http://localhost:${PORT}`));
+```
+
+---
+
+## Vendor Dependency Loading
+
+Third-party ES module packages are copied from `node_modules/` into
+`public/vendor/` at install time. This makes them servable as static files.
+
+### scripts/vendor-deps.js
+
+```javascript
+import { cpSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const VENDOR_DIR = resolve('public/vendor');
+const DEPS = [
+  { name: 'hybrids', src: 'node_modules/hybrids/src' },
+];
+
+mkdirSync(VENDOR_DIR, { recursive: true });
+
+for (const dep of DEPS) {
+  const dest = resolve(VENDOR_DIR, dep.name);
+  cpSync(dep.src, dest, { recursive: true });
+  console.log(`Vendored: ${dep.name} → ${dest}`);
+}
+```
+
+### Wiring
+
+In `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "node scripts/vendor-deps.js"
+  }
+}
+```
+
+Running `npm install` automatically vendors dependencies. The `public/vendor/`
+directory should be in `.gitignore`.
+
+### Adding a New Dependency
+
+1. `npm install <package>`
+2. Add an entry to the `DEPS` array in `scripts/vendor-deps.js`
+3. Add a mapping in the import map (see below)
+4. Run `npm run postinstall` (or re-run `npm install`)
+
+---
+
+## Import Map
+
+The browser resolves bare specifiers like `'hybrids'` via an import map
+declared in `public/index.html`.
+
+### public/index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>App</title>
+  <link rel="stylesheet" href="/src/styles/reset.css">
+  <link rel="stylesheet" href="/src/styles/tokens.css">
+
+  <script type="importmap">
+  {
+    "imports": {
+      "hybrids": "/vendor/hybrids/index.js"
+    }
+  }
+  </script>
+</head>
+<body>
+  <app-router></app-router>
+  <script type="module" src="/src/router/index.js"></script>
+</body>
+</html>
+```
+
+### How It Works
+
+1. Browser encounters `import { html } from 'hybrids'` in any ES module.
+2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
+3. Server serves the file from `public/vendor/hybrids/index.js`.
+4. Hybrids' internal imports use relative paths — they resolve naturally.
+
+### Rules
+
+- **One import map per page.** It must be declared before any `<script type="module">`.
+- **No dynamic import map generation.** The map is static HTML.
+- **Version pinning** is handled by `package-lock.json` + the vendor copy.
+  The vendored files always match the installed version.
+
+### Cache Busting
+
+For production, append a version query param to the import map entries:
+
+```json
+{
+  "imports": {
+    "hybrids": "/vendor/hybrids/index.js?v=9.1.22"
+  }
+}
+```
+
+Or use versioned directory names: `/vendor/hybrids@9.1.22/index.js`.