@techninja/clearstack 0.2.6 → 0.2.8

package/docs/CONVENTIONS.md

@@ -213,6 +213,50 @@ function moveObj(o, dx, dy) { ... }
 
 ---
 
+## npm Scripts: One Entry Point Per Domain
+
+Every `package.json` script should be a single, discoverable entry point.
+Avoid the `name:variant` colon pattern that fragments a domain across
+multiple keys.
+
+### Rules
+
+- **One script per domain.** `test`, `spec`, `lint` — not `test:node`,
+  `test:browser`, `lint:fix`, `spec:code`, `spec:docs`.
+- **Arguments over aliases.** `pnpm spec check code` instead of
+  `pnpm spec:code`. The CLI handles routing.
+- **Interactive by default.** Running `pnpm spec` with no arguments shows
+  a menu of available actions. Users discover commands by using the tool.
+- **Direct invocation for power users.** Once you know the subcommand,
+  skip the menu: `pnpm spec check`, `pnpm spec update`.
+- **Self-documenting.** Each script's CLI should print usage when given
+  `help` or an unknown argument.
+
+### Why
+
+- Fewer script entries = less package.json bloat
+- Discoverability through interactive menus beats memorizing key names
+- Scripts grow via subcommands, not new `package.json` entries
+- Consistent with how real CLIs work (`git`, `docker`, `npm` itself)
+
+### Example
+
+```json
+{
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch --env-file=.env src/server.js",
+    "test": "node --test tests/*.test.js",
+    "spec": "clearstack"
+  }
+}
+```
+
+`pnpm spec` → interactive menu. `pnpm spec check` → run checks.
+`pnpm spec update` → sync docs. One entry, full access.
+
+---
+
 ## Session Retrospective
 
 At the end of each implementation session, ask:

package/lib/check.js

@@ -20,7 +20,7 @@ function loadConfig(projectDir) {
     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(','),
+    ignore: (env.SPEC_IGNORE_DIRS || 'node_modules,src/public/vendor,.git,.configs').split(','),
   };
 }
 
@@ -100,16 +100,22 @@ function findFiles(dir, extensions, ignoreDirs, root) {
   return results;
 }
 
-/** Run a shell command, report pass/fail. */
+/** Run a shell command, report pass/fail. Filters node_modules errors. */
 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}`));
+    const ownErrors = out.trim().split('\n')
+      .filter((l) => l.trim() && !l.includes('node_modules'));
+    if (ownErrors.length === 0) {
+      console.log(`  ✅ ${label}`);
+      return true;
+    }
+    console.log(`  ❌ ${label}`);
+    ownErrors.forEach((l) => console.log(`     ${l}`));
     return false;
   }
 }

package/lib/package-gen.js

@@ -20,19 +20,12 @@ export async function writePackageJson(dest, vars, existing) {
     ...(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',
+    } : {
+      dev: 'npx serve src',
+    }),
+    postinstall: 'node scripts/setup.js',
+    test: 'node scripts/test.js',
+    spec: 'clearstack',
   };
 
   const specDeps = {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
-    "clearstack": "./bin/cli.js"
+    "clearstack": "bin/cli.js"
   },
   "files": [
     "bin/",
@@ -20,24 +20,17 @@
     "start": "node src/server.js",
     "dev": "node --watch --env-file=.env src/server.js",
     "setup": "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",
+    "test": "node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js",
     "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",
+    "lint": "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"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "web-components",
     "no-build",

package/templates/fullstack/src/server.js

@@ -10,16 +10,16 @@ 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);
 
+app.use(express.static('src'));
+
 // SPA fallback
 app.use((req, res, next) => {
-  if (req.method === 'GET' && !req.path.includes('.')) {
-    return res.sendFile('index.html', { root: 'public' });
+  if (req.method === 'GET' && !req.path.includes('.') && !req.path.startsWith('/api')) {
+    return res.sendFile('index.html', { root: 'src/public' });
   }
   next();
 });

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

@@ -58,7 +58,7 @@ export default [
     },
   },
   {
-    ignores: ['node_modules/', 'public/vendor/'],
+    ignores: ['node_modules/', 'src/public/vendor/'],
   },
   prettier,
 ];

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

@@ -19,7 +19,7 @@
   ],
   "exclude": [
     "../node_modules",
-    "../public/vendor",
+    "../src/public/vendor",
     "../**/*.test.js"
   ]
 }

package/templates/shared/.env

@@ -3,7 +3,7 @@ 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
+SPEC_IGNORE_DIRS=node_modules,src/public/vendor,.git,.configs
 
 # Server
 PORT={{port}}

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

@@ -213,6 +213,50 @@ function moveObj(o, dx, dy) { ... }
 
 ---
 
+## npm Scripts: One Entry Point Per Domain
+
+Every `package.json` script should be a single, discoverable entry point.
+Avoid the `name:variant` colon pattern that fragments a domain across
+multiple keys.
+
+### Rules
+
+- **One script per domain.** `test`, `spec`, `lint` — not `test:node`,
+  `test:browser`, `lint:fix`, `spec:code`, `spec:docs`.
+- **Arguments over aliases.** `pnpm spec check code` instead of
+  `pnpm spec:code`. The CLI handles routing.
+- **Interactive by default.** Running `pnpm spec` with no arguments shows
+  a menu of available actions. Users discover commands by using the tool.
+- **Direct invocation for power users.** Once you know the subcommand,
+  skip the menu: `pnpm spec check`, `pnpm spec update`.
+- **Self-documenting.** Each script's CLI should print usage when given
+  `help` or an unknown argument.
+
+### Why
+
+- Fewer script entries = less package.json bloat
+- Discoverability through interactive menus beats memorizing key names
+- Scripts grow via subcommands, not new `package.json` entries
+- Consistent with how real CLIs work (`git`, `docker`, `npm` itself)
+
+### Example
+
+```json
+{
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch --env-file=.env src/server.js",
+    "test": "node --test tests/*.test.js",
+    "spec": "clearstack"
+  }
+}
+```
+
+`pnpm spec` → interactive menu. `pnpm spec check` → run checks.
+`pnpm spec update` → sync docs. One entry, full access.
+
+---
+
 ## Session Retrospective
 
 At the end of each implementation session, ask:

package/templates/shared/gitignore

@@ -1,5 +1,5 @@
 node_modules/
-public/vendor/
-public/icons.json
+src/public/vendor/
+src/public/icons.json
 data/db.json
 .env.local

package/templates/shared/scripts/build-icons.js

@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const ICONS_DIR = resolve(ROOT, 'node_modules/lucide-static/icons');
-const OUT = resolve(ROOT, 'public/icons.json');
+const OUT = resolve(ROOT, 'src/public/icons.json');
 
 /** Icons used in the app — lucide name → app name */
 const ICON_MAP = {
@@ -83,4 +83,4 @@ for (const [lucideName, appName] of Object.entries(ICON_MAP)) {
 }
 
 writeFileSync(OUT, JSON.stringify(icons, null, 2));
-console.log(`✓ Built ${count} icons → public/icons.json`);
+console.log(`✓ Built ${count} icons → src/public/icons.json`);

package/templates/shared/scripts/setup.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install setup — vendors dependencies and builds icon sprite.
+ * @module scripts/setup
+ */
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+await import(resolve(ROOT, 'scripts/vendor-deps.js'));
+await import(resolve(ROOT, 'scripts/build-icons.js'));

package/templates/shared/scripts/test.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * Test runner — finds and executes all .test.js files.
+ * @module scripts/test
+ */
+
+import { execSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync, statSync } from 'node:fs';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** @param {string} dir @returns {string[]} */
+function findTests(dir) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    if (entry.name === 'node_modules' || entry.name === 'public') continue;
+    if (entry.isDirectory()) results.push(...findTests(full));
+    else if (entry.name.endsWith('.test.js')) results.push(full);
+  }
+  return results;
+}
+
+const files = findTests(ROOT);
+if (files.length === 0) {
+  console.log('No test files found.');
+  process.exit(0);
+}
+
+try {
+  execSync(`node --test ${files.join(' ')}`, { cwd: ROOT, stdio: 'inherit' });
+} catch {
+  process.exit(1);
+}

package/templates/shared/scripts/vendor-deps.js

@@ -10,7 +10,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
-const VENDOR_DIR = resolve(ROOT, 'public/vendor');
+const VENDOR_DIR = resolve(ROOT, 'src/public/vendor');
 
 /** @type {{ name: string, src: string }[]} */
 const DEPS = [{ name: 'hybrids', src: 'node_modules/hybrids/src' }];
@@ -21,5 +21,5 @@ for (const dep of DEPS) {
   const src = resolve(ROOT, dep.src);
   const dest = resolve(VENDOR_DIR, dep.name);
   cpSync(src, dest, { recursive: true });
-  console.log(`✓ Vendored: ${dep.name} → public/vendor/${dep.name}/`);
+  console.log(`✓ Vendored: ${dep.name} → src/public/vendor/${dep.name}/`);
 }

package/templates/shared/src/public/index.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{name}}</title>
+  <link rel="stylesheet" href="/styles/reset.css">
+  <link rel="stylesheet" href="/styles/tokens.css">
+  <link rel="stylesheet" href="/styles/shared.css">
+  <link rel="stylesheet" href="/styles/buttons.css">
+  <link rel="stylesheet" href="/styles/forms.css">
+  <link rel="stylesheet" href="/styles/components.css">
+
+  <script type="importmap">
+  {
+    "imports": {
+      "hybrids": "/public/vendor/hybrids/index.js"
+    }
+  }
+  </script>
+</head>
+<body>
+  <app-router></app-router>
+  <script type="module" src="/router/index.js"></script>
+</body>
+</html>

package/templates/shared/public/index.html

@@ -1,26 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{{name}}</title>
-  <link rel="stylesheet" href="/src/styles/reset.css">
-  <link rel="stylesheet" href="/src/styles/tokens.css">
-  <link rel="stylesheet" href="/src/styles/shared.css">
-  <link rel="stylesheet" href="/src/styles/buttons.css">
-  <link rel="stylesheet" href="/src/styles/forms.css">
-  <link rel="stylesheet" href="/src/styles/components.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>