@techninja/clearstack 0.2.0

package/lib/check.js

@@ -0,0 +1,115 @@
+/**
+ * Spec compliance checker — validates line counts, lint, format, types, tests.
+ * Reads thresholds from the project's .env file.
+ * @module lib/check
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve, extname, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+
+/**
+ * Load spec config from project .env.
+ * @param {string} projectDir
+ */
+function loadConfig(projectDir) {
+  const envPath = resolve(projectDir, '.env');
+  const env = existsSync(envPath) ? parseEnv(readFileSync(envPath, 'utf-8')) : {};
+  return {
+    codeMax: parseInt(env.SPEC_CODE_MAX_LINES) || 150,
+    docsMax: parseInt(env.SPEC_DOCS_MAX_LINES) || 500,
+    codeExt: (env.SPEC_CODE_EXTENSIONS || '.js,.css').split(','),
+    docsExt: (env.SPEC_DOCS_EXTENSIONS || '.md').split(','),
+    ignore: (env.SPEC_IGNORE_DIRS || 'node_modules,public/vendor,.git,.configs').split(','),
+  };
+}
+
+/**
+ * Run spec compliance checks on a project directory.
+ * @param {string} projectDir
+ * @param {string} [scope] - 'code', 'docs', or undefined for full check
+ */
+export async function check(projectDir, scope) {
+  const cfg = loadConfig(projectDir);
+
+  if (scope === 'code') {
+    if (!checkFiles(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`))
+      process.exit(1);
+    return;
+  }
+  if (scope === 'docs') {
+    if (!checkFiles(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`))
+      process.exit(1);
+    return;
+  }
+
+  console.log('Running spec compliance check...\n');
+  const results = [
+    checkFiles(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`),
+    checkFiles(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`),
+    runCmd('ESLint', 'npx eslint --config .configs/eslint.config.js .', projectDir),
+    runCmd('Prettier', 'npx prettier --config .configs/.prettierrc --check src', projectDir),
+    runCmd('JSDoc types', 'npx tsc --project .configs/jsconfig.json', projectDir),
+  ];
+
+  const passed = results.filter(Boolean).length;
+  console.log(`\n${'='.repeat(40)}`);
+  console.log(`${passed}/${results.length} checks passed.`);
+  if (passed < results.length) process.exit(1);
+}
+
+/** @param {string} src */
+function parseEnv(src) {
+  const env = {};
+  for (const line of src.split('\n')) {
+    const m = line.match(/^([^#=]+)=(.*)$/);
+    if (m) env[m[1].trim()] = m[2].trim();
+  }
+  return env;
+}
+
+/** Check file line counts. */
+function checkFiles(root, extensions, max, ignoreDirs, label) {
+  const violations = [];
+  findFiles(root, extensions, ignoreDirs, root).forEach((file) => {
+    const lines = readFileSync(resolve(root, file), 'utf-8').trimEnd().split('\n').length;
+    if (lines > max) violations.push({ file, lines, max });
+  });
+  if (violations.length === 0) {
+    console.log(`  ✅ ${label}`);
+    return true;
+  }
+  console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
+  violations.forEach((v) => console.log(`     ${v.file}: ${v.lines} lines (max ${v.max})`));
+  return false;
+}
+
+/** Recursively find files. */
+function findFiles(dir, extensions, ignoreDirs, root) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    const rel = relative(root, full);
+    if (entry.isDirectory()) {
+      if (ignoreDirs.some((ig) => entry.name === ig || rel === ig || rel.startsWith(ig + '/'))) continue;
+      results.push(...findFiles(full, extensions, ignoreDirs, root));
+    } else if (extensions.includes(extname(entry.name))) {
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+/** Run a shell command, report pass/fail. */
+function runCmd(label, cmd, cwd) {
+  try {
+    execSync(cmd, { cwd, stdio: 'pipe' });
+    console.log(`  ✅ ${label}`);
+    return true;
+  } catch (err) {
+    console.log(`  ❌ ${label}`);
+    const out = (err.stdout || '') + (err.stderr || '');
+    if (out.trim()) out.trim().split('\n').forEach((l) => console.log(`     ${l}`));
+    return false;
+  }
+}

package/lib/copy.js

@@ -0,0 +1,43 @@
+/**
+ * Template file copier — copies files with {{variable}} replacement.
+ * @module lib/copy
+ */
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const TEMPLATE_RE = /\{\{(\w+)\}\}/g;
+
+/**
+ * Recursively copy a template directory, replacing {{vars}} in file contents.
+ * @param {string} templateRoot - Root templates/ directory
+ * @param {string} templateName - 'shared', 'fullstack', or 'static'
+ * @param {string} dest - Destination project directory
+ * @param {Record<string, string|number>} vars - Template variables
+ */
+export async function copyTemplates(templateRoot, templateName, dest, vars) {
+  const src = resolve(templateRoot, templateName);
+  await copyDir(src, dest, vars);
+}
+
+/**
+ * @param {string} src
+ * @param {string} dest
+ * @param {Record<string, string|number>} vars
+ */
+async function copyDir(src, dest, vars) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, vars);
+    } else {
+      const content = readFileSync(srcPath, 'utf-8');
+      const replaced = content.replace(TEMPLATE_RE, (_, key) =>
+        vars[key] !== undefined ? String(vars[key]) : `{{${key}}}`,
+      );
+      writeFileSync(destPath, replaced);
+    }
+  }
+}

package/lib/init.js

@@ -0,0 +1,73 @@
+/**
+ * Project scaffolder — generates a spec-compliant project from templates.
+ * @module lib/init
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { copyTemplates } from './copy.js';
+import { writePackageJson } from './package-gen.js';
+
+/**
+ * @typedef {Object} InitOptions
+ * @property {boolean} [yes] - Skip prompts, use defaults
+ * @property {string} [mode] - 'fullstack' or 'static'
+ * @property {string} [port] - Server port
+ */
+
+/**
+ * Run the init flow.
+ * @param {string} pkgRoot - Root of the clearstack package
+ * @param {InitOptions} [opts]
+ */
+export async function init(pkgRoot, opts = {}) {
+  console.log('\n🏗️  Clearstack project scaffolder\n');
+
+  const dest = process.cwd();
+  const pkgPath = resolve(dest, 'package.json');
+  const existingPkg = existsSync(pkgPath)
+    ? JSON.parse(readFileSync(pkgPath, 'utf-8'))
+    : null;
+
+  let name, description, mode, port;
+
+  if (opts.yes) {
+    name = existingPkg?.name || basename(dest);
+    description = existingPkg?.description || 'A Clearstack project';
+    mode = opts.mode || 'fullstack';
+    port = opts.port || '3000';
+  } else {
+    const { input, select } = await import('@inquirer/prompts');
+    name = await input({
+      message: 'Project name:',
+      default: existingPkg?.name || basename(dest),
+    });
+    description = await input({
+      message: 'Description:',
+      default: existingPkg?.description || 'A Clearstack project',
+    });
+    mode = await select({
+      message: 'Project mode:',
+      choices: [
+        { name: 'Full stack (Express + WebSocket + JSON DB + SSE)', value: 'fullstack' },
+        { name: 'Static / browser only (localStorage, no server)', value: 'static' },
+      ],
+    });
+    port = mode === 'fullstack'
+      ? await input({ message: 'Server port:', default: '3000' })
+      : '3000';
+  }
+
+  const templateDir = resolve(pkgRoot, 'templates');
+  const vars = { name, description, port, mode, year: new Date().getFullYear() };
+
+  console.log(`Scaffolding ${name} (${mode}) → ${dest}\n`);
+
+  await copyTemplates(templateDir, 'shared', dest, vars);
+  await copyTemplates(templateDir, mode, dest, vars);
+  await writePackageJson(dest, vars, existingPkg);
+
+  console.log(`\n✅ Project scaffolded at ${dest}`);
+  console.log('   npm install');
+  console.log(mode === 'fullstack' ? '   npm run dev\n' : '   npx serve public\n');
+}

package/lib/package-gen.js

@@ -0,0 +1,83 @@
+/**
+ * Generates package.json for the scaffolded project.
+ * @module lib/package-gen
+ */
+
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Write a package.json tailored to the project mode.
+ * Merges with existing package.json if provided.
+ * @param {string} dest - Project directory
+ * @param {{ name: string, description: string, port: string, mode: string }} vars
+ * @param {Record<string, unknown>} [existing] - Existing package.json to merge with
+ */
+export async function writePackageJson(dest, vars, existing) {
+  const isFullstack = vars.mode === 'fullstack';
+
+  const specScripts = {
+    ...(isFullstack ? {
+      start: 'node src/server.js',
+      dev: 'node --watch --env-file=.env src/server.js',
+    } : {}),
+    postinstall: 'node scripts/vendor-deps.js && node scripts/build-icons.js',
+    test: 'npm run test:node && npm run test:browser',
+    'test:node': 'node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js',
+    'test:browser': 'web-test-runner --config .configs/web-test-runner.config.js',
+    spec: 'clearstack check',
+    'spec:code': 'clearstack check code',
+    'spec:docs': 'clearstack check docs',
+    'spec:update': 'clearstack update',
+    lint: 'eslint --config .configs/eslint.config.js .',
+    'lint:fix': 'eslint --config .configs/eslint.config.js . --fix',
+    format: 'prettier --config .configs/.prettierrc --write src scripts tests',
+    typecheck: 'tsc --project .configs/jsconfig.json',
+  };
+
+  const specDeps = {
+    hybrids: '^9.1.22',
+    'lucide-static': '^1.7.0',
+    ...(isFullstack ? { express: '^5.2.1', ws: '^8.0.0' } : {}),
+  };
+
+  const specDevDeps = {
+    '@techninja/clearstack': '^0.2.0',
+    '@open-wc/testing': '^4.0.0',
+    '@web/test-runner': '^0.20.0',
+    '@web/test-runner-playwright': '^0.11.0',
+    eslint: '^10.1.0',
+    'eslint-config-prettier': '^10.1.8',
+    'eslint-plugin-jsdoc': '^62.8.1',
+    playwright: '^1.50.0',
+    prettier: '^3.8.1',
+    typescript: '^6.0.2',
+  };
+
+  const pkg = existing
+    ? {
+        ...existing,
+        name: vars.name,
+        description: vars.description,
+        type: 'module',
+        ...(isFullstack ? { main: 'src/server.js' } : {}),
+        scripts: { ...existing.scripts, ...specScripts },
+        dependencies: { ...existing.dependencies, ...specDeps },
+        devDependencies: { ...existing.devDependencies, ...specDevDeps },
+      }
+    : {
+        name: vars.name,
+        version: '0.1.0',
+        type: 'module',
+        description: vars.description,
+        ...(isFullstack ? { main: 'src/server.js' } : {}),
+        scripts: specScripts,
+        keywords: ['hybrids', 'web-components', 'no-build'],
+        license: 'MIT',
+        dependencies: specDeps,
+        devDependencies: specDevDeps,
+      };
+
+  writeFileSync(resolve(dest, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
+  console.log('  ✓ package.json' + (existing ? ' (merged)' : ''));
+}

package/lib/update.js

@@ -0,0 +1,73 @@
+/**
+ * Spec updater — syncs docs and configs from the clearstack package.
+ * Copies new versions so the user can review the git diff.
+ * @module lib/update
+ */
+
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+/**
+ * Sync a source directory to a destination, comparing file contents.
+ * @param {string} src
+ * @param {string} dest
+ * @param {string} label
+ * @returns {number} count of updated files
+ */
+function syncDir(src, dest, label) {
+  if (!existsSync(src)) return 0;
+  mkdirSync(dest, { recursive: true });
+
+  const files = readdirSync(src).filter((f) => !f.startsWith('.spec'));
+  let updated = 0;
+
+  for (const file of files) {
+    const srcContent = readFileSync(join(src, file), 'utf-8');
+    const destPath = join(dest, file);
+    const destContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+
+    if (srcContent !== destContent) {
+      writeFileSync(destPath, srcContent);
+      console.log(`  ✓ Updated: ${label}/${file}`);
+      updated++;
+    }
+  }
+  return updated;
+}
+
+/**
+ * Update spec docs and configs from the clearstack package to the local project.
+ * @param {string} pkgRoot - Root of the clearstack package
+ */
+export async function update(pkgRoot) {
+  const templateShared = resolve(pkgRoot, 'templates/shared');
+  let total = 0;
+
+  console.log('');
+
+  total += syncDir(
+    resolve(templateShared, 'docs/clearstack'),
+    resolve(process.cwd(), 'docs/clearstack'),
+    'docs/clearstack',
+  );
+
+  total += syncDir(
+    resolve(templateShared, '.configs'),
+    resolve(process.cwd(), '.configs'),
+    '.configs',
+  );
+
+  // Write spec version marker
+  const pkg = JSON.parse(readFileSync(resolve(pkgRoot, 'package.json'), 'utf-8'));
+  const versionPath = resolve(process.cwd(), 'docs/clearstack/.specversion');
+  mkdirSync(resolve(process.cwd(), 'docs/clearstack'), { recursive: true });
+  writeFileSync(versionPath, pkg.version + '\n');
+
+  console.log(`\n  docs/app-spec/ — untouched (your project specs are safe)`);
+
+  if (total === 0) {
+    console.log('  ✅ All docs and configs are up to date.\n');
+  } else {
+    console.log(`\n  ${total} file(s) updated. Review with: git diff docs/ .configs/\n`);
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@techninja/clearstack",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
+  "bin": {
+    "clearstack": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "docs/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/techninja/clearstack.git"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch --env-file=.env src/server.js",
+    "postinstall": "node scripts/vendor-deps.js && node scripts/build-icons.js",
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js",
+    "test:browser": "web-test-runner --config .configs/web-test-runner.config.js",
+    "test:watch": "web-test-runner --config .configs/web-test-runner.config.js --watch",
+    "spec": "node --env-file=.env scripts/spec.js",
+    "spec:code": "node --env-file=.env scripts/spec.js code",
+    "spec:docs": "node --env-file=.env scripts/spec.js docs",
+    "lint": "eslint --config .configs/eslint.config.js .",
+    "lint:fix": "eslint --config .configs/eslint.config.js . --fix",
+    "format": "prettier --config .configs/.prettierrc --write src scripts tests",
+    "format:check": "prettier --config .configs/.prettierrc --check src scripts tests",
+    "typecheck": "tsc --project .configs/jsconfig.json",
+    "sync-docs": "node scripts/sync-docs.js",
+    "release": "node scripts/release.js",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major",
+    "prepublishOnly": "node scripts/sync-docs.js"
+  },
+  "keywords": [
+    "web-components",
+    "no-build",
+    "es-modules",
+    "specification",
+    "scaffold",
+    "hybrids"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2"
+  },
+  "devDependencies": {
+    "@open-wc/testing": "^4.0.0",
+    "@types/ws": "^8.18.1",
+    "@web/test-runner": "^0.20.0",
+    "@web/test-runner-playwright": "^0.11.0",
+    "eslint": "^10.1.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^62.8.1",
+    "express": "^5.2.1",
+    "hybrids": "^9.1.22",
+    "lucide-static": "^1.7.0",
+    "playwright": "^1.50.0",
+    "prettier": "^3.8.1",
+    "typescript": "^6.0.2",
+    "ws": "^8.20.0"
+  }
+}

package/templates/fullstack/data/seed.json

@@ -0,0 +1 @@
+{"example": {}}

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

@@ -0,0 +1,75 @@
+/**
+ * JSON file-backed database. In-memory with disk persistence on writes.
+ * Call reload() to refresh from disk after external edits.
+ * @module api/db
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+
+export { schemas } from './schemas.js';
+
+const DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../../data');
+const DB_PATH = resolve(DIR, 'db.json');
+const SEED_PATH = resolve(DIR, 'seed.json');
+
+let data = loadFromDisk();
+
+/** Read the database file from disk. Seeds if missing. */
+function loadFromDisk() {
+  mkdirSync(DIR, { recursive: true });
+  if (!existsSync(DB_PATH)) {
+    const seed = existsSync(SEED_PATH) ? readFileSync(SEED_PATH, 'utf-8') : '{}';
+    writeFileSync(DB_PATH, seed);
+  }
+  return JSON.parse(readFileSync(DB_PATH, 'utf-8'));
+}
+
+/** Persist current state to disk. */
+function save() {
+  writeFileSync(DB_PATH, JSON.stringify(data, null, 2));
+}
+
+/** Reload from disk — call after external edits to db.json. */
+export function reload() {
+  data = loadFromDisk();
+}
+
+/** @type {{ get(entity: string): Record<string, object> | undefined }} */
+export const db = {
+  get(entity) {
+    return data[entity];
+  },
+};
+
+/** @param {string} entity @param {string} id */
+export function getRecord(entity, id) {
+  return data[entity]?.[id];
+}
+
+/** @param {string} entity @param {string} id @param {object} value */
+export function setRecord(entity, id, value) {
+  if (!data[entity]) data[entity] = {};
+  data[entity][id] = value;
+  save();
+}
+
+/** @param {string} entity @param {string} id @returns {boolean} */
+export function deleteRecord(entity, id) {
+  if (!data[entity]?.[id]) return false;
+  delete data[entity][id];
+  save();
+  return true;
+}
+
+/** @param {string} entity @returns {object[]} */
+export function listRecords(entity) {
+  return data[entity] ? Object.values(data[entity]) : [];
+}
+
+/** @param {object} values @returns {object} */
+export function createEntity(values) {
+  return { ...values, id: randomUUID(), createdAt: new Date().toISOString() };
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Generic CRUD router for any entity registered in the schema map.
+ * @module api/entities
+ */
+
+import { Router } from 'express';
+import { schemas, getRecord, setRecord, deleteRecord, listRecords, createEntity } from './db.js';
+import { broadcast } from './events.js';
+import { validate } from './validate.js';
+
+export const entityRouter = Router();
+
+/** @param {string} plural */
+const singular = (plural) => plural.replace(/s$/, '');
+
+// --- OPTIONS: schema + methods ---
+
+entityRouter.options('/:entity', (req, res) => {
+  const entry = schemas.get(req.params.entity);
+  if (!entry) return res.status(404).json({ error: 'Unknown entity' });
+  res.set('Allow', 'OPTIONS, GET, POST');
+  res.json({ schema: entry.schema, layout: entry.layout, methods: ['OPTIONS', 'GET', 'POST'] });
+});
+
+entityRouter.options('/:entity/:id', (req, res) => {
+  const entry = schemas.get(req.params.entity);
+  if (!entry) return res.status(404).json({ error: 'Unknown entity' });
+  res.set('Allow', 'OPTIONS, GET, PUT, DELETE');
+  res.json({
+    schema: entry.schema,
+    layout: entry.layout,
+    methods: ['OPTIONS', 'GET', 'PUT', 'DELETE'],
+  });
+});
+
+// --- List ---
+
+entityRouter.get('/:entity', (req, res) => {
+  const { entity } = req.params;
+
+  if (req.query.schema === 'true') {
+    const entry = schemas.get(entity);
+    return entry ? res.json(entry.schema) : res.status(404).json({ error: 'Unknown entity' });
+  }
+
+  let items = listRecords(entity);
+  if (!items.length && !schemas.has(entity)) {
+    return res.status(404).json({ error: 'Unknown entity' });
+  }
+
+  for (const [key, val] of Object.entries(req.query)) {
+    if (['limit', 'offset', 'sort', 'schema'].includes(key)) continue;
+    items = items.filter((item) => item[key] === val);
+  }
+
+  if (req.query.sort) {
+    const sortVal = /** @type {string} */ (req.query.sort);
+    const desc = sortVal.startsWith('-');
+    const field = desc ? sortVal.slice(1) : sortVal;
+    items.sort((a, b) => {
+      const av = a[field] ?? '';
+      const bv = b[field] ?? '';
+      const cmp = typeof av === 'number' ? av - bv : String(av).localeCompare(String(bv));
+      return desc ? -cmp : cmp;
+    });
+  }
+
+  const total = items.length;
+  const offset = parseInt(/** @type {string} */ (req.query.offset)) || 0;
+  const limit = parseInt(/** @type {string} */ (req.query.limit)) || 20;
+  res.json({ data: items.slice(offset, offset + limit), total, limit, offset });
+});
+
+// --- Read ---
+
+entityRouter.get('/:entity/:id', (req, res) => {
+  const item = getRecord(req.params.entity, req.params.id);
+  return item ? res.json(item) : res.status(404).json({ error: 'Not found' });
+});
+
+// --- Create ---
+
+entityRouter.post('/:entity', (req, res) => {
+  if (!schemas.has(req.params.entity)) return res.status(404).json({ error: 'Unknown entity' });
+  const { valid, fields } = validate(req.params.entity, req.body);
+  if (!valid) return res.status(422).json({ error: 'Validation failed', fields });
+  const entity = createEntity(req.body);
+  setRecord(req.params.entity, entity.id, entity);
+  broadcast(singular(req.params.entity), entity.id, 'created');
+  res.status(201).json(entity);
+});
+
+// --- Update ---
+
+entityRouter.put('/:entity/:id', (req, res) => {
+  const existing = getRecord(req.params.entity, req.params.id);
+  if (!existing) return res.status(404).json({ error: 'Not found' });
+  const { valid, fields } = validate(req.params.entity, req.body, true);
+  if (!valid) return res.status(422).json({ error: 'Validation failed', fields });
+  const updated = { ...existing, ...req.body, id: existing.id, createdAt: existing.createdAt };
+  setRecord(req.params.entity, existing.id, updated);
+  broadcast(singular(req.params.entity), existing.id, 'updated');
+  res.json(updated);
+});
+
+// --- Delete ---
+
+entityRouter.delete('/:entity/:id', (req, res) => {
+  if (!deleteRecord(req.params.entity, req.params.id)) {
+    return res.status(404).json({ error: 'Not found' });
+  }
+  broadcast(singular(req.params.entity), req.params.id, 'deleted');
+  res.status(204).end();
+});

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

@@ -0,0 +1,35 @@
+/**
+ * Server-Sent Events endpoint and broadcast utility.
+ * @module api/events
+ */
+
+import { Router } from 'express';
+
+/** @type {Set<import('node:http').ServerResponse>} */
+const clients = new Set();
+
+export const eventsRouter = Router();
+
+eventsRouter.get('/events', (req, res) => {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  });
+
+  clients.add(res);
+  req.on('close', () => clients.delete(res));
+});
+
+/**
+ * Broadcast an entity change to all connected SSE clients.
+ * @param {string} type - Entity name (singular), e.g. 'project'
+ * @param {string} id - Entity ID
+ * @param {'created'|'updated'|'deleted'} action
+ */
+export function broadcast(type, id, action) {
+  const data = JSON.stringify({ type, id, action });
+  for (const res of clients) {
+    res.write(`event: update\ndata: ${data}\n\n`);
+  }
+}