@techninja/clearstack 0.2.0

package/templates/fullstack/src/api/schemas.js

@@ -0,0 +1,104 @@
+/**
+ * JSON Schema + form layout registry for all entities.
+ * Each entry has { schema, layout } where layout defines form structure.
+ * @module api/schemas
+ */
+
+/** @type {Map<string, { schema: object, layout: object }>} */
+export const schemas = new Map();
+
+schemas.set('projects', {
+  schema: {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'Project',
+    type: 'object',
+    required: ['name'],
+    properties: {
+      id: { type: 'string', format: 'uuid', readOnly: true },
+      name: {
+        type: 'string',
+        minLength: 1,
+        maxLength: 200,
+        title: 'Name',
+        description: 'Project name',
+        placeholder: 'My Project',
+      },
+      description: {
+        type: 'string',
+        maxLength: 1000,
+        default: '',
+        title: 'Description',
+        description: 'Brief summary of the project',
+      },
+      status: {
+        type: 'string',
+        enum: ['active', 'archived'],
+        enumTitles: ['Active', 'Archived'],
+        default: 'active',
+        title: 'Status',
+        description: 'Current project status',
+      },
+      createdAt: { type: 'string', format: 'date-time', readOnly: true },
+    },
+  },
+  layout: {
+    groups: [
+      { fields: ['name'], columns: 1 },
+      { fields: ['description'], columns: 1 },
+      { fields: ['status'], columns: 1 },
+    ],
+    actions: { align: 'right' },
+  },
+});
+
+schemas.set('tasks', {
+  schema: {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'Task',
+    type: 'object',
+    required: ['title', 'projectId'],
+    properties: {
+      id: { type: 'string', format: 'uuid', readOnly: true },
+      projectId: {
+        type: 'string',
+        format: 'uuid',
+        title: 'Project',
+        description: 'Parent project ID',
+        writeOnly: true,
+      },
+      title: {
+        type: 'string',
+        minLength: 1,
+        maxLength: 200,
+        title: 'Title',
+        description: 'Task title',
+        placeholder: 'What needs to be done?',
+      },
+      status: {
+        type: 'string',
+        enum: ['todo', 'doing', 'done'],
+        enumTitles: ['To Do', 'In Progress', 'Done'],
+        default: 'todo',
+        title: 'Status',
+        description: 'Current progress',
+      },
+      priority: {
+        type: 'string',
+        enum: ['low', 'med', 'high'],
+        enumTitles: ['Low', 'Medium', 'High'],
+        default: 'med',
+        title: 'Priority',
+        description: 'Urgency level',
+      },
+      sortOrder: { type: 'number', default: 0, writeOnly: true },
+      createdAt: { type: 'string', format: 'date-time', readOnly: true },
+    },
+  },
+  layout: {
+    groups: [
+      { fields: ['title'], columns: 1 },
+      { fields: ['status', 'priority'], columns: 2 },
+    ],
+    actions: { align: 'right' },
+  },
+});

package/templates/fullstack/src/api/validate.js

@@ -0,0 +1,52 @@
+/**
+ * Server-side validation against JSON Schema.
+ * Returns field-level errors for 422 responses.
+ * @module api/validate
+ */
+
+import { schemas } from './db.js';
+
+/**
+ * Validate a request body against the entity's JSON Schema.
+ * @param {string} entity - Entity name, e.g. 'projects'
+ * @param {object} body - Request body to validate
+ * @param {boolean} [partial=false] - If true, skip required checks for missing keys
+ * @returns {{ valid: boolean, fields: Record<string, string> }}
+ */
+export function validate(entity, body, partial = false) {
+  const entry = schemas.get(entity);
+  if (!entry) return { valid: true, fields: /** @type {Record<string, string>} */ ({}) };
+
+  /** @type {Record<string, string>} */
+  const fields = {};
+  const props = entry.schema.properties || {};
+  const required = entry.schema.required || [];
+
+  if (!partial) {
+    for (const name of required) {
+      const val = body[name];
+      if (val === undefined || val === null || val === '') {
+        fields[name] = `${name} is required`;
+      }
+    }
+  }
+
+  for (const [name, val] of Object.entries(body)) {
+    const prop = props[name];
+    if (!prop || prop.readOnly) continue;
+
+    if (typeof val === 'string') {
+      if (prop.minLength && val.length < prop.minLength) {
+        fields[name] = `Minimum ${prop.minLength} characters`;
+      }
+      if (prop.maxLength && val.length > prop.maxLength) {
+        fields[name] = `Maximum ${prop.maxLength} characters`;
+      }
+      if (prop.enum && !prop.enum.includes(val)) {
+        fields[name] = `Must be one of: ${prop.enum.join(', ')}`;
+      }
+    }
+  }
+
+  return { valid: Object.keys(fields).length === 0, fields };
+}

package/templates/fullstack/src/pages/home/home-view.js

@@ -0,0 +1,19 @@
+/**
+ * Home page — starting point for your app.
+ * @module pages/home
+ */
+
+import { html, define } from 'hybrids';
+
+export default define({
+  tag: 'home-view',
+  render: {
+    value: () => html`
+      <div class="home-view">
+        <h1>{{name}}</h1>
+        <p>Your Clearstack project is ready. Start building!</p>
+      </div>
+    `,
+    shadow: false,
+  },
+});

package/templates/fullstack/src/router/index.js

@@ -0,0 +1,16 @@
+/**
+ * App router shell — manages view stack and realtime sync.
+ * @module router
+ */
+
+import { html, define, router } from 'hybrids';
+import HomeView from '../pages/home/home-view.js';
+
+export default define({
+  tag: 'app-router',
+  stack: router(HomeView, { url: '/' }),
+  render: {
+    value: ({ stack }) => html`<div class="app-router">${stack}</div>`,
+    shadow: false,
+  },
+});

package/templates/fullstack/src/server.js

@@ -0,0 +1,46 @@
+/**
+ * Express server entry point.
+ * @module server
+ */
+
+import express from 'express';
+import { entityRouter } from './api/entities.js';
+import { eventsRouter } from './api/events.js';
+
+const app = express();
+
+app.use(express.json());
+app.use(express.static('public'));
+app.use('/src', express.static('src'));
+
+app.use('/api', eventsRouter);
+app.use('/api', entityRouter);
+
+// SPA fallback
+app.use((req, res, next) => {
+  if (req.method === 'GET' && !req.path.includes('.')) {
+    return res.sendFile('index.html', { root: 'public' });
+  }
+  next();
+});
+
+/**
+ * Start the server.
+ * @param {number} [port=3000]
+ * @returns {import('node:http').Server}
+ */
+export function start(port = {{port}}) {
+  const server = app.listen(port, () => console.log(`http://localhost:${port}`));
+  server.on('error', (/** @type {NodeJS.ErrnoException} */ err) => {
+    if (err.code === 'EADDRINUSE') console.error(`Port ${port} in use. Try: PORT=4354 npm start`);
+    else console.error(err);
+    process.exit(1);
+  });
+  return server;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  start(parseInt(process.env.PORT) || {{port}});
+}
+
+export default app;

package/templates/fullstack/src/store/AppState.js

@@ -0,0 +1,33 @@
+/**
+ * Global UI state — singleton, persisted to localStorage.
+ * Theme, sidebar, active filters. No API calls.
+ * @module store/AppState
+ */
+
+import { store } from 'hybrids';
+
+/**
+ * @typedef {Object} AppState
+ * @property {string} theme - 'light' or 'dark'
+ * @property {boolean} sidebarOpen - Sidebar visibility
+ * @property {string} activeFilter - Current task filter value
+ */
+
+/** @type {import('hybrids').Model<AppState>} */
+const AppState = {
+  theme: 'light',
+  sidebarOpen: true,
+  activeFilter: 'all',
+  [store.connect]: {
+    get: () => {
+      const raw = localStorage.getItem('appState');
+      return raw ? JSON.parse(raw) : {};
+    },
+    set: (id, values) => {
+      localStorage.setItem('appState', JSON.stringify(values));
+      return values;
+    },
+  },
+};
+
+export default AppState;

package/templates/fullstack/src/store/UserPrefs.js

@@ -0,0 +1,31 @@
+/**
+ * User preferences — singleton, persisted to localStorage.
+ * Display preferences that don't need an API.
+ * @module store/UserPrefs
+ */
+
+import { store } from 'hybrids';
+
+/**
+ * @typedef {Object} UserPrefs
+ * @property {'board'|'list'} defaultView - Preferred task view mode
+ * @property {boolean} compactMode - Dense UI toggle
+ */
+
+/** @type {import('hybrids').Model<UserPrefs>} */
+const UserPrefs = {
+  defaultView: 'list',
+  compactMode: false,
+  [store.connect]: {
+    get: () => {
+      const raw = localStorage.getItem('userPrefs');
+      return raw ? JSON.parse(raw) : {};
+    },
+    set: (id, values) => {
+      localStorage.setItem('userPrefs', JSON.stringify(values));
+      return values;
+    },
+  },
+};
+
+export default UserPrefs;

package/templates/fullstack/src/store/realtimeSync.js

@@ -0,0 +1,54 @@
+/**
+ * Realtime sync via Server-Sent Events.
+ * Debounces rapid updates to avoid clearing stores mid-render.
+ * @module utils/realtimeSync
+ */
+
+import { store } from 'hybrids';
+
+/**
+ * Connect to the SSE endpoint and clear store caches on entity updates.
+ * Debounces clears — multiple events within 300ms trigger one clear.
+ * @param {string} url - SSE endpoint, e.g. '/api/events'
+ * @param {Record<string, import('hybrids').Model<any>>} modelMap
+ * @returns {() => void} Disconnect function
+ */
+export function connectRealtime(url, modelMap) {
+  const source = new EventSource(url);
+  /** @type {Record<string, ReturnType<typeof setTimeout>>} */
+  const timers = {};
+
+  source.addEventListener('open', () => {
+    console.log('[SSE] Connected to', url);
+  });
+
+  source.addEventListener('update', (event) => {
+    const { type, action } = JSON.parse(event.data);
+    const Model = modelMap[type];
+    if (!Model) return;
+
+    // Debounce: batch rapid events (e.g. reorder sends N PUTs)
+    clearTimeout(timers[type]);
+    timers[type] = setTimeout(() => {
+      console.log(`[SSE] ${type} ${action} — clearing store cache`);
+      try {
+        store.clear([Model]);
+      } catch {
+        /* list may not exist */
+      }
+      try {
+        store.clear(Model);
+      } catch {
+        /* singular may not exist */
+      }
+    }, 300);
+  });
+
+  source.addEventListener('error', () => {
+    console.log('[SSE] Connection lost, reconnecting in 5s...');
+    source.close();
+    setTimeout(() => connectRealtime(url, modelMap), 5000);
+  });
+
+  return () => source.close();
+}

package/templates/shared/.configs/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "printWidth": 100,
+  "arrowParens": "always"
+}

package/templates/shared/.configs/eslint.config.js

@@ -0,0 +1,64 @@
+import prettier from 'eslint-config-prettier';
+import jsdoc from 'eslint-plugin-jsdoc';
+
+export default [
+  {
+    files: ['**/*.js'],
+    plugins: { jsdoc },
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: 'module',
+      globals: {
+        console: 'readonly',
+        document: 'readonly',
+        window: 'readonly',
+        HTMLElement: 'readonly',
+        CustomEvent: 'readonly',
+        EventSource: 'readonly',
+        localStorage: 'readonly',
+        fetch: 'readonly',
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        requestAnimationFrame: 'readonly',
+        process: 'readonly',
+        URL: 'readonly',
+        URLSearchParams: 'readonly',
+        Event: 'readonly',
+        globalThis: 'readonly',
+      },
+    },
+    rules: {
+      semi: ['error', 'always'],
+      indent: ['error', 2, { SwitchCase: 1 }],
+      'no-var': 'error',
+      'prefer-const': 'error',
+      eqeqeq: ['error', 'always'],
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      'no-console': 'off',
+
+      // JSDoc enforcement
+      'jsdoc/require-jsdoc': [
+        'warn',
+        {
+          require: { FunctionDeclaration: true },
+          checkConstructors: false,
+        },
+      ],
+      'jsdoc/require-param-type': 'warn',
+      'jsdoc/require-returns-type': 'warn',
+      'jsdoc/valid-types': 'warn',
+    },
+  },
+  {
+    files: ['**/*.test.js'],
+    rules: {
+      'jsdoc/require-jsdoc': 'off',
+      'no-unused-vars': 'off',
+    },
+  },
+  {
+    ignores: ['node_modules/', 'public/vendor/'],
+  },
+  prettier,
+];

package/templates/shared/.configs/jsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "checkJs": true,
+    "allowJs": true,
+    "noEmit": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "paths": {
+      "hybrids": ["../node_modules/hybrids/types/index.d.ts"]
+    }
+  },
+  "include": [
+    "../src/**/*.js",
+    "../scripts/**/*.js"
+  ],
+  "exclude": [
+    "../node_modules",
+    "../public/vendor",
+    "../**/*.test.js"
+  ]
+}

package/templates/shared/.configs/web-test-runner.config.js

@@ -0,0 +1,8 @@
+import { playwrightLauncher } from '@web/test-runner-playwright';
+
+export default {
+  files: 'src/components/**/*.test.js',
+  nodeResolve: true,
+  rootDir: '..',
+  browsers: [playwrightLauncher({ product: 'chromium' })],
+};

package/templates/shared/.env

@@ -0,0 +1,9 @@
+# Spec enforcement defaults
+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
+
+# Server
+PORT={{port}}

package/templates/shared/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+title: "[Bug] "
+labels: bug
+---
+
+## Describe the bug
+
+<!-- Clear description of what's wrong -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+<!-- What should happen -->
+
+## Actual behavior
+
+<!-- What actually happens -->
+
+## Environment
+
+- Browser:
+- OS:
+- Node version:
+
+## Console errors
+
+```
+<!-- Paste any console errors here -->
+```
+
+## Spec check output
+
+```
+<!-- Paste output of `npm run spec all` if relevant -->
+```

package/templates/shared/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[Feature] "
+labels: enhancement
+---
+
+## What
+
+<!-- What feature or improvement do you want? -->
+
+## Why
+
+<!-- What problem does it solve? What use case does it enable? -->
+
+## Proposed approach
+
+<!-- How would you implement it? Which files/components would change? -->
+
+## Spec impact
+
+<!-- Would this require changes to any spec docs in docs/? -->
+
+- [ ] No spec changes needed
+- [ ] New patterns to document
+- [ ] Existing spec needs correction
+
+## Alternatives considered
+
+<!-- What other approaches did you think about? -->

package/templates/shared/.github/ISSUE_TEMPLATE/spec_correction.md

@@ -0,0 +1,26 @@
+---
+name: Spec Correction
+about: The spec says one thing but implementation reveals another
+title: "[Spec] "
+labels: spec
+---
+
+## Which spec doc?
+
+<!-- e.g. COMPONENT_PATTERNS.md, STATE_AND_ROUTING.md -->
+
+## What the spec says
+
+<!-- Quote the relevant section -->
+
+## What actually happens
+
+<!-- What did you discover during implementation? -->
+
+## Proposed correction
+
+<!-- How should the spec be updated? -->
+
+## Code evidence
+
+<!-- Link to the file/line that demonstrates the correct behavior -->

package/templates/shared/.github/pull_request_template.md

@@ -0,0 +1,51 @@
+## What
+
+<!-- Brief description of what this PR does -->
+
+## Why
+
+<!-- What problem does it solve or what feature does it add? -->
+
+## Changes
+
+<!-- List the key changes. Group by category if helpful. -->
+
+### Added
+-
+
+### Changed
+-
+
+### Fixed
+-
+
+## Spec Compliance
+
+<!-- Paste the output of `npm run spec all` -->
+
+```
+npm run spec all
+```
+
+## Tests
+
+<!-- What tests were added or updated? -->
+
+- [ ] New tests cover the changes
+- [ ] All existing tests still pass
+- [ ] `npm run spec all` passes (7/7)
+
+## Spec Updates
+
+<!-- Did any spec docs need updating? If so, which ones and why? -->
+
+- [ ] No spec changes needed
+- [ ] Updated: <!-- list docs -->
+
+## Session Retrospective
+
+<!-- Answer briefly — helps future contributors understand the journey -->
+
+1. **Patterns discovered:**
+2. **Unexpected breakage:**
+3. **What would you test differently?**

package/templates/shared/.github/workflows/spec.yml

@@ -0,0 +1,46 @@
+name: Spec Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  spec:
+    name: Full Spec Compliance
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install chromium --with-deps
+
+      - name: Code line counts (≤150)
+        run: node scripts/spec.js code
+
+      - name: Doc line counts (≤500)
+        run: node scripts/spec.js docs
+
+      - name: ESLint
+        run: npx eslint --config .configs/eslint.config.js .
+
+      - name: Prettier
+        run: npx prettier --config .configs/.prettierrc --check src scripts server.js tests
+
+      - name: JSDoc types (tsc --checkJs)
+        run: npx tsc --project .configs/jsconfig.json
+
+      - name: Node tests
+        run: node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js
+
+      - name: Browser tests
+        run: npx web-test-runner --config .configs/web-test-runner.config.js