@techninja/clearstack 0.2.18 → 0.2.20

package/lib/check.js

@@ -1,18 +1,30 @@
 /**
- * Spec compliance checker — validates line counts, lint, format, types, tests.
- * Reads thresholds from the project's .env file.
+ * Spec compliance checker — config, commands, and orchestration.
+ * Core utilities live in spec-utils.js.
  * @module lib/check
  */
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { resolve, extname, relative } from 'node:path';
-import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { checkFileLines, runCmd, countFiles } from './spec-utils.js';
+
+export { checkFileLines, runCmd, countFiles, findFiles, elapsed } from './spec-utils.js';
+
+/** @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;
+}
 
 /**
  * Load spec config from project .env.
  * @param {string} projectDir
  */
-function loadConfig(projectDir) {
+export function loadConfig(projectDir) {
   const envPath = resolve(projectDir, '.env');
   const env = existsSync(envPath) ? parseEnv(readFileSync(envPath, 'utf-8')) : {};
   return {
@@ -24,34 +36,47 @@ function loadConfig(projectDir) {
   };
 }
 
+/** Standard check commands used by both CLI and POC. */
+export const CMDS = {
+  lint: 'npx eslint --config .configs/eslint.config.js . --fix',
+  stylelint: 'npx stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix',
+  prettier: 'npx prettier --config .configs/.prettierrc --write src scripts',
+  mdlint: 'npx markdownlint-cli2 --config .configs/.markdownlint.jsonc --fix "docs/**/*.md" "*.md"',
+  types: 'npx tsc --project .configs/jsconfig.json',
+};
+
 /**
- * Run spec compliance checks on a project directory.
+ * Run the full spec compliance check (used by clearstack CLI).
  * @param {string} projectDir
- * @param {string} [scope] - 'code', 'docs', or undefined for full check
+ * @param {string} [scope]
  */
 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)`))
+    if (!checkFileLines(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)`))
+    if (!checkFileLines(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`))
       process.exit(1);
     return;
   }
 
+  const jsFiles = countFiles(projectDir, ['.js'], cfg.ignore);
+  const cssFiles = countFiles(projectDir, ['.css'], cfg.ignore);
+  const mdFiles = countFiles(projectDir, ['.md'], cfg.ignore);
+
   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 . --fix', projectDir),
-    runCmd('Stylelint', 'npx stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix', projectDir),
-    runCmd('Prettier', 'npx prettier --config .configs/.prettierrc --check src', projectDir),
-    runCmd('Markdown', 'npx markdownlint-cli2 --config .configs/.markdownlint.jsonc --fix "docs/**/*.md" "*.md"', projectDir),
-    runCmd('JSDoc types', 'npx tsc --project .configs/jsconfig.json', projectDir),
+    checkFileLines(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`),
+    checkFileLines(projectDir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`),
+    runCmd('ESLint', CMDS.lint, projectDir, `${jsFiles} files`),
+    runCmd('Stylelint', CMDS.stylelint, projectDir, `${cssFiles} files`),
+    runCmd('Prettier', CMDS.prettier, projectDir, `${jsFiles} files`),
+    runCmd('Markdown', CMDS.mdlint, projectDir, `${mdFiles} files`),
+    runCmd('JSDoc types', CMDS.types, projectDir, `${jsFiles} files`),
   ];
 
   const passed = results.filter(Boolean).length;
@@ -59,65 +84,3 @@ export async function check(projectDir, scope) {
   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. Filters node_modules errors. */
-function runCmd(label, cmd, cwd) {
-  try {
-    execSync(cmd, { cwd, stdio: 'pipe' });
-    console.log(`  ✅ ${label}`);
-    return true;
-  } catch (err) {
-    const out = (err.stdout || '') + (err.stderr || '');
-    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

@@ -17,21 +17,18 @@ 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',
-    } : {
-      dev: 'npx serve src',
-    }),
+    start: 'node src/server.js',
+    dev: 'node --watch --env-file=.env src/server.js',
     postinstall: 'node scripts/setup.js',
     test: 'node scripts/test.js',
     spec: 'clearstack',
   };
 
   const specDeps = {
+    express: '^5.2.1',
     hybrids: '^9.1.22',
     'lucide-static': '^1.7.0',
-    ...(isFullstack ? { express: '^5.2.1', ws: '^8.0.0' } : {}),
+    ...(isFullstack ? { ws: '^8.0.0' } : {}),
   };
 
   const specDevDeps = {
@@ -57,7 +54,7 @@ export async function writePackageJson(dest, vars, existing) {
         name: vars.name,
         description: vars.description,
         type: 'module',
-        ...(isFullstack ? { main: 'src/server.js' } : {}),
+        main: 'src/server.js',
         scripts: { ...existing.scripts, ...specScripts },
         dependencies: { ...existing.dependencies, ...specDeps },
         devDependencies: { ...existing.devDependencies, ...specDevDeps },
@@ -67,7 +64,7 @@ export async function writePackageJson(dest, vars, existing) {
         version: '0.1.0',
         type: 'module',
         description: vars.description,
-        ...(isFullstack ? { main: 'src/server.js' } : {}),
+        main: 'src/server.js',
         scripts: specScripts,
         keywords: ['hybrids', 'web-components', 'no-build'],
         license: 'MIT',

package/lib/spec-utils.js

@@ -0,0 +1,109 @@
+/**
+ * Shared spec utilities — file scanning, command running, timing.
+ * Used by both the clearstack CLI and the POC spec runner.
+ * @module lib/spec-utils
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, extname, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+
+/** @param {number} start */
+export function elapsed(start) {
+  const d = performance.now() - start;
+  return d < 1000 ? `${Math.round(d)}ms` : `${(d / 1000).toFixed(1)}s`;
+}
+
+/** Recursively find files matching extensions, skipping ignored dirs. */
+export function findFiles(dir, extensions, ignoreDirs, root = dir) {
+  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;
+}
+
+/**
+ * Count files matching extensions.
+ * @param {string} root
+ * @param {string[]} extensions
+ * @param {string[]} ignoreDirs
+ * @param {string[]} [dirs] - Subdirectories to scope to
+ * @param {RegExp} [filter] - Optional regex filter on filenames
+ * @returns {number}
+ */
+export function countFiles(root, extensions, ignoreDirs, dirs, filter) {
+  let files;
+  if (dirs) {
+    files = dirs.reduce((acc, d) => {
+      try { return acc.concat(findFiles(resolve(root, d), extensions, ignoreDirs, root)); }
+      catch { return acc; }
+    }, []);
+  } else {
+    files = findFiles(root, extensions, ignoreDirs, root);
+  }
+  return filter ? files.filter((f) => filter.test(f)).length : files.length;
+}
+
+/**
+ * Check file line counts with timing.
+ * @param {string} root
+ * @param {string[]} extensions
+ * @param {number} max
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @returns {boolean}
+ */
+export function checkFileLines(root, extensions, max, ignoreDirs, label) {
+  const start = performance.now();
+  const files = findFiles(root, extensions, ignoreDirs, root);
+  const violations = [];
+  for (const file of files) {
+    const lines = readFileSync(resolve(root, file), 'utf-8').trimEnd().split('\n').length;
+    if (lines > max) violations.push({ file, lines, max });
+  }
+  const time = elapsed(start);
+  if (violations.length === 0) {
+    console.log(`  ✅ ${label} (${files.length} files, ${time})`);
+    return true;
+  }
+  console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
+  for (const v of violations) console.log(`     ${v.file}: ${v.lines} lines (max ${v.max})`);
+  return false;
+}
+
+/**
+ * Run a shell command, report pass/fail with timing.
+ * @param {string} label
+ * @param {string} cmd
+ * @param {string} cwd
+ * @param {string} [stats]
+ * @returns {boolean}
+ */
+export function runCmd(label, cmd, cwd, stats) {
+  const start = performance.now();
+  const suffix = (s) => s ? ` (${s}, ${elapsed(start)})` : ` (${elapsed(start)})`;
+  try {
+    execSync(cmd, { cwd, stdio: 'pipe', encoding: 'utf-8' });
+    console.log(`  ✅ ${label}${suffix(stats)}`);
+    return true;
+  } catch (err) {
+    const out = (err.stdout || '') + (err.stderr || '');
+    const ownErrors = out.trim().split('\n')
+      .filter((l) => l.trim() && !l.includes('node_modules'));
+    if (ownErrors.length === 0) {
+      console.log(`  ✅ ${label}${suffix(stats)}`);
+      return true;
+    }
+    console.log(`  ❌ ${label}${suffix(stats)}`);
+    for (const line of ownErrors) console.log(`     ${line}`);
+    return false;
+  }
+}

package/package.json

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

package/templates/shared/src/styles/shared.css

@@ -84,7 +84,7 @@
   padding: 0;
   margin: -1px;
   overflow: hidden;
-  clip: rect(0, 0, 0, 0);
+  clip-path: inset(50%);
   white-space: nowrap;
   border: 0;
 }
@@ -92,10 +92,10 @@
 /* --- Common Transitions --- */
 
 .fade-in {
-  animation: fadeIn 0.2s ease-in;
+  animation: fade-in 0.2s ease-in;
 }
 
-@keyframes fadeIn {
+@keyframes fade-in {
   from {
     opacity: 0;
   }

package/templates/static/src/server.js

@@ -0,0 +1,30 @@
+/**
+ * Static dev server — serves src/ for the browser with SPA fallback.
+ * @module server
+ */
+
+import express from 'express';
+
+/** @type {any} */
+const app = express();
+
+app.use(express.static('src'));
+
+app.use((req, res, next) => {
+  if (req.method === 'GET' && !req.path.includes('.')) {
+    return res.sendFile('index.html', { root: 'src/public' });
+  }
+  next();
+});
+
+/** @param {number} [port] */
+export function start(port = {{port}}) {
+  const server = app.listen(port, () => console.log(`http://localhost:${port}`));
+  return server;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  start(parseInt(process.env.PORT) || {{port}});
+}
+
+export default app;