@techninja/clearstack 0.2.5 → 0.2.7

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

@@ -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

@@ -22,17 +22,8 @@ export async function writePackageJson(dest, vars, existing) {
       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',
+    test: 'node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js',
+    spec: 'clearstack',
   };
 
   const specDeps = {
@@ -43,6 +34,7 @@ export async function writePackageJson(dest, vars, existing) {
 
   const specDevDeps = {
     '@techninja/clearstack': '^0.2.0',
+    '@types/node': '^22.0.0',
     '@open-wc/testing': '^4.0.0',
     '@web/test-runner': '^0.20.0',
     '@web/test-runner-playwright': '^0.11.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -20,22 +20,12 @@
     "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"
   },
   "keywords": [

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

@@ -8,6 +8,7 @@
     "noEmit": true,
     "strict": false,
     "skipLibCheck": true,
+    "types": ["node"],
     "paths": {
       "hybrids": ["../node_modules/hybrids/types/index.d.ts"]
     }

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/static/src/pages/home/home-view.js

@@ -26,7 +26,8 @@ export default define({
       <div class="home-view">
         <h1>{{name}}</h1>
         <p>Your Clearstack project is ready. Start building!</p>
-        ${store.ready(state) && html`
+        ${store.ready(state) &&
+        html`
           <p>Count: ${state.count}</p>
           <button class="btn btn-primary" onclick="${increment}">Increment</button>
           <p class="hint">State persists in localStorage — refresh to verify.</p>