@techninja/clearstack 0.3.14 → 0.3.16

package/README.md

@@ -50,8 +50,9 @@ npm install -D @techninja/clearstack    # add to your project
 npx clearstack init                     # scaffold (interactive)
 npx clearstack init -y                  # scaffold (fullstack defaults)
 npx clearstack init --static            # scaffold (static, no server)
+npx clearstack update                   # sync docs (skip existing configs)
+npx clearstack update --force           # sync docs + overwrite configs
 npm run spec                            # check compliance
-npm run spec:update                     # sync docs + configs on upgrade
 ```
 
 Two modes: **fullstack** (Express + WebSocket + JSON DB + SSE) or **static** (localStorage, no server).
@@ -65,7 +66,7 @@ See [QUICKSTART.md](./docs/QUICKSTART.md) for the full walkthrough.
 - **Light DOM by default.** Shared styles just work.
 - **JSDoc over TypeScript.** Types without a compile step — validated by `tsc --checkJs`.
 - **Test at the boundary.** Each phase passes before the next begins.
-- **The spec checks itself.** `npm run spec:code` and `npm run spec:docs`.
+- **The spec checks itself.** `npm run spec code` and `npm run spec docs`.
 - **Lint and format.** ESLint + Prettier, semicolons, 2-space indent.
 
 ## Scripts
@@ -78,10 +79,11 @@ npm run lint        # ESLint check
 npm run lint:fix    # ESLint auto-fix
 npm run format      # Prettier auto-format
 npm run typecheck   # JSDoc type validation via tsc
-npm run spec        # Spec compliance check
-npm run spec:code   # Check code files ≤150 lines
-npm run spec:docs   # Check doc files ≤500 lines
-npm run spec:update # Sync docs + configs from upstream
+npm run spec        # Spec compliance (interactive)
+npm run spec all    # Full spec check
+npm run spec code   # Check code files ≤150 lines
+npm run spec docs   # Check doc files ≤500 lines
+npm run spec update # Sync docs from upstream
 ```
 
 ## License

package/bin/cli.js

@@ -4,7 +4,7 @@
  * clearstack CLI — scaffold, update, and check spec-compliant projects.
  * Usage:
  *   clearstack init [-y] [--static|--fullstack] [--port 3000]
- *   clearstack update
+ *   clearstack update [--force]
  *   clearstack check [code|docs|imports|lint|lint es|format|types|audit|all]
  *   clearstack                   → interactive menu
  */
@@ -54,7 +54,7 @@ async function run(action) {
     await init(PKG_ROOT, { yes, ...flags });
   } else if (action === 'update') {
     const { update } = await import('../lib/update.js');
-    await update(PKG_ROOT);
+    await update(PKG_ROOT, { force: !!flags.force });
   } else if (action === 'check') {
     const subs = args.filter((a) => a !== cmd && !a.startsWith('-'));
     const { check } = await import('../lib/check.js');

package/docs/CONVENTIONS.md

@@ -298,7 +298,7 @@ multiple keys.
 
 - **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
+- **Arguments over aliases.** `pnpm spec 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.

package/docs/QUICKSTART.md

@@ -43,7 +43,7 @@ If a `package.json` already exists, Clearstack merges into it — your existing
 
 ```
 your-project/
-├── .configs/              # ⟳ Managed — synced on update
+├── .configs/              # ✏️ Scaffolded once — yours to customize
 ├── .github/               # CI workflow, PR + issue templates
 ├── docs/
 │   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
@@ -108,14 +108,16 @@ When Clearstack releases a new version:
 
 ```bash
 npm update @techninja/clearstack    # bump the package
-npm run spec:update                 # sync docs + configs
+npm run spec update                 # sync docs, skip existing configs
+npm run spec update --force         # sync docs + overwrite configs
 git diff docs/ .configs/            # review what changed
 ```
 
 This updates:
 
-- `docs/clearstack/*.md` — spec documentation
-- `.configs/*` — linter, formatter, type checker, test runner configs
+- `docs/clearstack/*.md` — spec documentation (always overwritten)
+- `.configs/*` — skipped if already exists (your customizations are safe)
+- `.configs/*` with `--force` — overwritten with latest defaults
 
 This never touches:
 
@@ -127,12 +129,16 @@ This never touches:
 ## 8. Spec Compliance
 
 ```bash
-npm run spec           # full check via clearstack binary
-npm run spec:code      # code files ≤150 lines
-npm run spec:docs      # doc files ≤500 lines
-npm run lint:fix       # ESLint auto-fix
-npm run format         # Prettier auto-format
-npm run typecheck      # JSDoc type validation
+npm run spec           # interactive menu
+npm run spec all       # full check
+npm run spec code      # code files ≤150 lines
+npm run spec docs      # doc files ≤500 lines
+npm run spec lint      # ESLint + Stylelint + Markdown
+npm run spec lint es   # ESLint only
+npm run spec format    # Prettier
+npm run spec imports   # import map aliases
+npm run spec types     # JSDoc type validation
+npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
 
@@ -153,21 +159,21 @@ SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 The scaffolded `.github/workflows/spec.yml` runs all checks on every PR:
 
 ```
-spec:code → spec:docs → lint → format → typecheck → test
+spec all → lint + format + code + docs + imports + types + audit
 ```
 
 ## Summary
 
-| Task                  | Command                                |
-| --------------------- | -------------------------------------- |
-| Install Clearstack    | `npm install -D @techninja/clearstack` |
-| Scaffold (fullstack)  | `npx clearstack init`                  |
-| Scaffold (static)     | `npx clearstack init --static`         |
-| Install dependencies  | `npm install`                          |
-| Start dev server      | `npm run dev`                          |
-| Lint + format         | `npm run lint:fix && npm run format`   |
-| Type check            | `npm run typecheck`                    |
-| Run tests             | `npm test`                             |
-| Full spec check       | `npm run spec`                         |
-| Update spec + configs | `npm run spec:update`                  |
-| Review spec changes   | `git diff docs/ .configs/`             |
+| Task                  | Command                                    |
+| --------------------- | ------------------------------------------ |
+| Install Clearstack    | `npm install -D @techninja/clearstack`     |
+| Scaffold (fullstack)  | `npx clearstack init`                      |
+| Scaffold (static)     | `npx clearstack init --static`             |
+| Install dependencies  | `npm install`                              |
+| Start dev server      | `npm run dev`                              |
+| Lint + format         | `npm run spec lint && npm run spec format` |
+| Type check            | `npm run typecheck`                        |
+| Run tests             | `npm test`                                 |
+| Full spec check       | `npm run spec`                             |
+| Update spec + configs | `npm run spec update`                      |
+| Review spec changes   | `git diff docs/ .configs/`                 |

package/lib/check.js

@@ -42,11 +42,9 @@ export function loadConfig(projectDir) {
   };
 }
 
-/**
- * Build check commands for the detected package manager.
- * @param {string} runner
- */
-function buildCmds(runner) {
+/** Build check commands for the detected package manager. */
+export function buildCmds(projectDir) {
+  const runner = detectRunner(projectDir);
   const audit = runner === 'pnpm exec' ? 'pnpm audit --prod' : 'npm audit --omit=dev';
   return {
     lint: `${runner} eslint --config .configs/eslint.config.js . --fix`,
@@ -58,8 +56,6 @@ function buildCmds(runner) {
   };
 }
 
-/** @deprecated Use buildCmds() instead — kept for backward compat. */
-export const CMDS = buildCmds('npx');
 
 /** @typedef {{ key: string, name: string, parent?: string, run: () => boolean }} Check */
 
@@ -108,10 +104,10 @@ export function parentKeys(checks) {
   return [...new Set(checks.filter((c) => c.parent).map((c) => c.parent))];
 }
 
-/** Run the full spec compliance check (used by clearstack CLI). */
+/** Run the full spec compliance check (used by clearstack CLI and scripts/spec.js). */
 export async function check(projectDir, scope) {
   const cfg = loadConfig(projectDir);
-  const cmds = buildCmds(detectRunner(projectDir));
+  const cmds = buildCmds(projectDir);
   const checks = buildChecks(projectDir, cfg, cmds);
 
   if (scope && scope !== 'all') {
@@ -127,7 +123,7 @@ export async function check(projectDir, scope) {
     return;
   }
 
-  console.log('Running spec compliance check...\n');
+  console.log('🔍 Clearstack compliance checking now... 💙\n');
   const results = checks.map((c) => c.run());
   const passed = results.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);

package/lib/package-gen.js

@@ -21,7 +21,7 @@ export async function writePackageJson(dest, vars, existing) {
     dev: 'node --watch --env-file=.env --env-file=.env.local src/server.js',
     postinstall: 'node scripts/setup.js',
     test: 'node scripts/test.js',
-    spec: 'clearstack',
+    spec: 'node scripts/spec.js',
   };
 
   const specDeps = {

package/lib/update.js

@@ -1,6 +1,7 @@
 /**
  * Spec updater — syncs docs and configs from the clearstack package.
- * Copies new versions so the user can review the git diff.
+ * Docs are overwritten (clearstack-owned). Configs skip existing files
+ * to preserve project customizations — use --force to overwrite.
  * @module lib/update
  */
 
@@ -8,24 +9,27 @@ import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from
 import { resolve, join } from 'node:path';
 
 /**
- * Sync a source directory to a destination, comparing file contents.
+ * Sync a source directory to a destination.
  * @param {string} src
  * @param {string} dest
  * @param {string} label
+ * @param {{ skipExisting?: boolean }} [opts]
  * @returns {number} count of updated files
  */
-function syncDir(src, dest, label) {
+function syncDir(src, dest, label, opts = {}) {
   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);
+    if (opts.skipExisting && existsSync(destPath)) {
+      console.log(`  ⏭ Skipped: ${label}/${file} (exists, use --force to overwrite)`);
+      continue;
+    }
+    const srcContent = readFileSync(join(src, file), 'utf-8');
     const destContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
-
     if (srcContent !== destContent) {
       writeFileSync(destPath, srcContent);
       console.log(`  ✓ Updated: ${label}/${file}`);
@@ -36,25 +40,29 @@ function syncDir(src, dest, label) {
 }
 
 /**
- * Update spec docs and configs from the clearstack package to the local project.
+ * Update spec docs and configs from the clearstack package.
  * @param {string} pkgRoot - Root of the clearstack package
+ * @param {{ force?: boolean }} [opts]
  */
-export async function update(pkgRoot) {
+export async function update(pkgRoot, opts = {}) {
   const templateShared = resolve(pkgRoot, 'templates/shared');
   let total = 0;
 
   console.log('');
 
+  // Docs: always overwrite (clearstack-owned content)
   total += syncDir(
     resolve(templateShared, 'docs/clearstack'),
     resolve(process.cwd(), 'docs/clearstack'),
     'docs/clearstack',
   );
 
+  // Configs: skip existing unless --force (project may have customized)
   total += syncDir(
     resolve(templateShared, '.configs'),
     resolve(process.cwd(), '.configs'),
     '.configs',
+    { skipExisting: !opts.force },
   );
 
   // Merge .gitignore (append missing lines, never remove user entries)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

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

@@ -24,20 +24,8 @@ jobs:
       - 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: Spec compliance
+        run: node scripts/spec.js all
 
       - name: Node tests
         run: node --test tests/*.test.js src/utils/*.test.js src/store/*.test.js

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

@@ -298,7 +298,7 @@ multiple keys.
 
 - **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
+- **Arguments over aliases.** `pnpm spec 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.

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

@@ -43,7 +43,7 @@ If a `package.json` already exists, Clearstack merges into it — your existing
 
 ```
 your-project/
-├── .configs/              # ⟳ Managed — synced on update
+├── .configs/              # ✏️ Scaffolded once — yours to customize
 ├── .github/               # CI workflow, PR + issue templates
 ├── docs/
 │   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
@@ -108,14 +108,16 @@ When Clearstack releases a new version:
 
 ```bash
 npm update @techninja/clearstack    # bump the package
-npm run spec:update                 # sync docs + configs
+npm run spec update                 # sync docs, skip existing configs
+npm run spec update --force         # sync docs + overwrite configs
 git diff docs/ .configs/            # review what changed
 ```
 
 This updates:
 
-- `docs/clearstack/*.md` — spec documentation
-- `.configs/*` — linter, formatter, type checker, test runner configs
+- `docs/clearstack/*.md` — spec documentation (always overwritten)
+- `.configs/*` — skipped if already exists (your customizations are safe)
+- `.configs/*` with `--force` — overwritten with latest defaults
 
 This never touches:
 
@@ -127,12 +129,16 @@ This never touches:
 ## 8. Spec Compliance
 
 ```bash
-npm run spec           # full check via clearstack binary
-npm run spec:code      # code files ≤150 lines
-npm run spec:docs      # doc files ≤500 lines
-npm run lint:fix       # ESLint auto-fix
-npm run format         # Prettier auto-format
-npm run typecheck      # JSDoc type validation
+npm run spec           # interactive menu
+npm run spec all       # full check
+npm run spec code      # code files ≤150 lines
+npm run spec docs      # doc files ≤500 lines
+npm run spec lint      # ESLint + Stylelint + Markdown
+npm run spec lint es   # ESLint only
+npm run spec format    # Prettier
+npm run spec imports   # import map aliases
+npm run spec types     # JSDoc type validation
+npm run spec audit     # security audit
 npm test               # Node + browser tests
 ```
 
@@ -153,21 +159,21 @@ SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs
 The scaffolded `.github/workflows/spec.yml` runs all checks on every PR:
 
 ```
-spec:code → spec:docs → lint → format → typecheck → test
+spec all → lint + format + code + docs + imports + types + audit
 ```
 
 ## Summary
 
-| Task                  | Command                                |
-| --------------------- | -------------------------------------- |
-| Install Clearstack    | `npm install -D @techninja/clearstack` |
-| Scaffold (fullstack)  | `npx clearstack init`                  |
-| Scaffold (static)     | `npx clearstack init --static`         |
-| Install dependencies  | `npm install`                          |
-| Start dev server      | `npm run dev`                          |
-| Lint + format         | `npm run lint:fix && npm run format`   |
-| Type check            | `npm run typecheck`                    |
-| Run tests             | `npm test`                             |
-| Full spec check       | `npm run spec`                         |
-| Update spec + configs | `npm run spec:update`                  |
-| Review spec changes   | `git diff docs/ .configs/`             |
+| Task                  | Command                                    |
+| --------------------- | ------------------------------------------ |
+| Install Clearstack    | `npm install -D @techninja/clearstack`     |
+| Scaffold (fullstack)  | `npx clearstack init`                      |
+| Scaffold (static)     | `npx clearstack init --static`             |
+| Install dependencies  | `npm install`                              |
+| Start dev server      | `npm run dev`                              |
+| Lint + format         | `npm run spec lint && npm run spec format` |
+| Type check            | `npm run typecheck`                        |
+| Run tests             | `npm test`                                 |
+| Full spec check       | `npm run spec`                             |
+| Update spec + configs | `npm run spec update`                      |
+| Review spec changes   | `git diff docs/ .configs/`                 |

package/templates/shared/scripts/spec.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * Spec enforcement — interactive menu + CLI shortcuts.
+ * Delegates all check logic to @techninja/clearstack.
+ * @module scripts/spec
+ */
+
+import {
+  loadConfig,
+  buildChecks,
+  buildCmds,
+  resolveChecks,
+  parentKeys,
+  check,
+} from '@techninja/clearstack/lib/check.js';
+
+const ROOT = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+const [sub, subsub] = process.argv.slice(2);
+const scope = subsub ? `${sub} ${subsub}` : sub;
+
+if (scope) {
+  await check(ROOT, scope);
+} else {
+  await interactive(ROOT);
+}
+
+/** Show interactive menu, then run the selected check. */
+async function interactive(dir) {
+  const cfg = loadConfig(dir);
+  const checks = buildChecks(dir, cfg, buildCmds(dir));
+  try {
+    const { select } = await import('@inquirer/prompts');
+    const action = await select({
+      message: 'Spec checker — what do you want to validate?',
+      choices: menuChoices(checks),
+    });
+    await check(dir, action);
+  } catch (e) {
+    if (e?.name === 'ExitPromptError') process.exit(0);
+    throw e;
+  }
+}
+
+/** Build interactive menu choices with hierarchy. */
+function menuChoices(checks) {
+  const choices = [];
+  const seen = new Set();
+  for (const c of checks) {
+    if (c.parent && !seen.has(c.parent)) {
+      seen.add(c.parent);
+      const kids = checks.filter((k) => k.parent === c.parent);
+      const label = kids.map((k) => k.name).join(' + ');
+      choices.push({ name: `${label} [${c.parent}]`, value: c.parent });
+      for (const k of kids)
+        choices.push({ name: `  ${k.name} [${c.parent} ${k.key}]`, value: `${c.parent} ${k.key}` });
+    } else if (!c.parent) {
+      choices.push({ name: `${c.name} [${c.key}]`, value: c.key });
+    }
+  }
+  choices.push({ name: 'All (full spec check)', value: 'all' });
+  return choices;
+}