@techninja/clearstack 0.3.6 → 0.3.8

package/docs/CONVENTIONS.md

@@ -109,6 +109,50 @@ render: ({ items }) => html`
 
 ---
 
+## Import Map Aliases
+
+All cross-directory imports in browser-facing code use `#prefix/` aliases
+defined in the import map (`src/index.html`). This eliminates fragile
+relative paths like `../../../utils/foo.js`.
+
+### Available Prefixes
+
+| Prefix          | Resolves to                    |
+| --------------- | ------------------------------ |
+| `#store/`       | `/store/`                      |
+| `#utils/`       | `/utils/`                      |
+| `#atoms/`       | `/components/atoms/`           |
+| `#molecules/`   | `/components/molecules/`       |
+| `#organisms/`   | `/components/organisms/`       |
+| `#templates/`   | `/components/templates/`       |
+| `#pages/`       | `/pages/`                      |
+
+### Rules
+
+- **No `../` imports.** The spec check (`npm run spec`) flags any `../`
+  in browser-facing JS. Use a `#prefix/` alias instead.
+- **Same-directory `./` is fine.** `index.js` re-exports and co-located
+  files use `./` naturally.
+- **Server/API files are exempt.** `src/api/` and `src/server.js` run in
+  Node, not the browser — they use `./` relative imports.
+- **Test files are exempt.** `*.test.js` files may use relative paths.
+- **jsconfig.json mirrors the import map.** The `paths` entries in
+  `.configs/jsconfig.json` let `tsc --checkJs` resolve `#prefix/` imports.
+
+### Examples
+
+```javascript
+// ✅ Good — clear, refactor-safe
+import AppState from '#store/AppState.js';
+import { formatDate } from '#utils/formatDate.js';
+import '#atoms/app-badge/app-badge.js';
+
+// ❌ Bad — fragile, hard to read
+import AppState from '../../../store/AppState.js';
+```
+
+---
+
 ## Error Handling
 
 Errors are handled **at the boundary where they are actionable.** Each layer
@@ -193,8 +237,8 @@ state: store(AppState),
 // In src/utils/filterActive.js
 export const filterActive = (items) => items.filter(i => i.active);
 
-// In component
-import { filterActive } from '../../utils/filterActive.js';
+// In component — use import map alias, never ../
+import { filterActive } from '#utils/filterActive.js';
 render: ({ items }) => html`<ul>${filterActive(items).map(...)}</ul>`,
 ```
 

package/docs/SERVER_AND_DEPS.md

@@ -121,7 +121,14 @@ declared in `src/index.html`.
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js",
+          "#store/": "/store/",
+          "#utils/": "/utils/",
+          "#atoms/": "/components/atoms/",
+          "#molecules/": "/components/molecules/",
+          "#organisms/": "/components/organisms/",
+          "#templates/": "/components/templates/",
+          "#pages/": "/pages/"
         }
       }
     </script>
@@ -139,6 +146,8 @@ declared in `src/index.html`.
 2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
 3. Server serves the file from `src/vendor/hybrids/index.js`.
 4. Hybrids' internal imports use relative paths — they resolve naturally.
+5. `#prefix/` entries resolve cross-directory app imports without `../`.
+   For example, `import '#utils/formatDate.js'` resolves to `/utils/formatDate.js`.
 
 ### Rules
 

package/lib/check.js

@@ -6,9 +6,16 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { checkFileLines, runCmd, countFiles } from './spec-utils.js';
+import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
 
-export { checkFileLines, runCmd, countFiles, findFiles, elapsed } from './spec-utils.js';
+export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
+
+/** Detect the project's package manager runner (npx, pnpm exec, yarn). */
+function detectRunner(projectDir) {
+  if (existsSync(resolve(projectDir, 'pnpm-lock.yaml'))) return 'pnpm exec';
+  if (existsSync(resolve(projectDir, 'yarn.lock'))) return 'yarn';
+  return 'npx';
+}
 
 /** @param {string} src */
 function parseEnv(src) {
@@ -36,15 +43,24 @@ export 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',
-  audit: 'npm audit --omit=dev',
-};
+/**
+ * Build check commands for the detected package manager.
+ * @param {string} runner
+ */
+function buildCmds(runner) {
+  const audit = runner === 'pnpm exec' ? 'pnpm audit --prod' : 'npm audit --omit=dev';
+  return {
+    lint: `${runner} eslint --config .configs/eslint.config.js . --fix`,
+    stylelint: `${runner} stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix`,
+    prettier: `${runner} prettier --config .configs/.prettierrc --write src scripts`,
+    mdlint: `${runner} markdownlint-cli2 --config .configs/.markdownlint.jsonc --fix "docs/**/*.md" "*.md"`,
+    types: `${runner} tsc --project .configs/jsconfig.json`,
+    audit,
+  };
+}
+
+/** @deprecated Use buildCmds() instead — kept for backward compat. */
+export const CMDS = buildCmds('npx');
 
 /**
  * Run the full spec compliance check (used by clearstack CLI).
@@ -53,6 +69,7 @@ export const CMDS = {
  */
 export async function check(projectDir, scope) {
   const cfg = loadConfig(projectDir);
+  const cmds = buildCmds(detectRunner(projectDir));
 
   if (scope === 'code') {
     if (!checkFileLines(projectDir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`))
@@ -73,12 +90,13 @@ export async function check(projectDir, scope) {
   const results = [
     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`),
-    runCmd('Security audit', CMDS.audit, projectDir),
+    checkImports(projectDir, cfg.ignore, 'Import map aliases (no ../ imports)'),
+    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`),
+    runCmd('Security audit', cmds.audit, projectDir),
   ];
 
   const passed = results.filter(Boolean).length;

package/lib/package-gen.js

@@ -49,6 +49,16 @@ export async function writePackageJson(dest, vars, existing) {
     typescript: '^6.0.2',
   };
 
+  const subpathImports = {
+    '#store/*': './src/store/*',
+    '#utils/*': './src/utils/*',
+    '#atoms/*': './src/components/atoms/*',
+    '#molecules/*': './src/components/molecules/*',
+    '#organisms/*': './src/components/organisms/*',
+    '#templates/*': './src/components/templates/*',
+    '#pages/*': './src/pages/*',
+  };
+
   const pkg = existing
     ? {
         ...existing,
@@ -56,6 +66,7 @@ export async function writePackageJson(dest, vars, existing) {
         description: vars.description,
         type: 'module',
         main: 'src/server.js',
+        imports: { ...existing.imports, ...subpathImports },
         scripts: { ...existing.scripts, ...specScripts },
         dependencies: { ...existing.dependencies, ...specDeps },
         devDependencies: { ...existing.devDependencies, ...specDevDeps },
@@ -66,6 +77,7 @@ export async function writePackageJson(dest, vars, existing) {
         type: 'module',
         description: vars.description,
         main: 'src/server.js',
+        imports: subpathImports,
         scripts: specScripts,
         keywords: ['hybrids', 'web-components', 'no-build'],
         license: 'MIT',

package/lib/spec-utils.js

@@ -79,6 +79,38 @@ export function checkFileLines(root, extensions, max, ignoreDirs, label) {
   return false;
 }
 
+/**
+ * Check for relative parent imports (`../`) in browser-facing JS files.
+ * Same-directory (`./`) and server/test files are allowed.
+ * @param {string} root
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @returns {boolean}
+ */
+export function checkImports(root, ignoreDirs, label) {
+  const start = performance.now();
+  const files = findFiles(root, ['.js'], ignoreDirs, root)
+    .filter((f) => f.startsWith('src/') && !f.includes('vendor/') && !f.includes('api/') && !f.endsWith('.test.js') && !f.endsWith('server.js'));
+  const violations = [];
+  const importRe = /(?:^|\n)\s*import\s.*?from\s+['"](\.\.[^'"]*)['"]|(?:^|\n)\s*import\s+['"](\.\.[^'"]*)['"]|(?:^|\n)\s*export\s.*?from\s+['"](\.\.[^'"]*)['"/]/g;
+  for (const file of files) {
+    const src = readFileSync(resolve(root, file), 'utf-8');
+    let m;
+    while ((m = importRe.exec(src)) !== null) {
+      const spec = m[1] || m[2] || m[3];
+      violations.push({ file, spec });
+    }
+  }
+  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}: import '${v.spec}' → use #prefix/ alias`);
+  return false;
+}
+
 /**
  * Run a shell command, report pass/fail with timing.
  * @param {string} label

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -31,6 +31,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "imports": {
+    "#store/*": "./src/store/*",
+    "#utils/*": "./src/utils/*",
+    "#atoms/*": "./src/components/atoms/*",
+    "#molecules/*": "./src/components/molecules/*",
+    "#organisms/*": "./src/components/organisms/*",
+    "#templates/*": "./src/components/templates/*",
+    "#pages/*": "./src/pages/*"
+  },
   "keywords": [
     "web-components",
     "no-build",

package/templates/fullstack/src/router/index.js

@@ -4,7 +4,7 @@
  */
 
 import { html, define, router } from 'hybrids';
-import HomeView from '../pages/home/home-view.js';
+import HomeView from '#pages/home/home-view.js';
 
 export default define({
   tag: 'app-router',

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

@@ -10,7 +10,14 @@
     "skipLibCheck": true,
     "types": ["node"],
     "paths": {
-      "hybrids": ["../node_modules/hybrids/types/index.d.ts"]
+      "hybrids": ["../node_modules/hybrids/types/index.d.ts"],
+      "#store/*": ["../src/store/*"],
+      "#utils/*": ["../src/utils/*"],
+      "#atoms/*": ["../src/components/atoms/*"],
+      "#molecules/*": ["../src/components/molecules/*"],
+      "#organisms/*": ["../src/components/organisms/*"],
+      "#templates/*": ["../src/components/templates/*"],
+      "#pages/*": ["../src/pages/*"]
     }
   },
   "include": ["../src/**/*.js", "../scripts/**/*.js"],

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

@@ -109,6 +109,50 @@ render: ({ items }) => html`
 
 ---
 
+## Import Map Aliases
+
+All cross-directory imports in browser-facing code use `#prefix/` aliases
+defined in the import map (`src/index.html`). This eliminates fragile
+relative paths like `../../../utils/foo.js`.
+
+### Available Prefixes
+
+| Prefix          | Resolves to                    |
+| --------------- | ------------------------------ |
+| `#store/`       | `/store/`                      |
+| `#utils/`       | `/utils/`                      |
+| `#atoms/`       | `/components/atoms/`           |
+| `#molecules/`   | `/components/molecules/`       |
+| `#organisms/`   | `/components/organisms/`       |
+| `#templates/`   | `/components/templates/`       |
+| `#pages/`       | `/pages/`                      |
+
+### Rules
+
+- **No `../` imports.** The spec check (`npm run spec`) flags any `../`
+  in browser-facing JS. Use a `#prefix/` alias instead.
+- **Same-directory `./` is fine.** `index.js` re-exports and co-located
+  files use `./` naturally.
+- **Server/API files are exempt.** `src/api/` and `src/server.js` run in
+  Node, not the browser — they use `./` relative imports.
+- **Test files are exempt.** `*.test.js` files may use relative paths.
+- **jsconfig.json mirrors the import map.** The `paths` entries in
+  `.configs/jsconfig.json` let `tsc --checkJs` resolve `#prefix/` imports.
+
+### Examples
+
+```javascript
+// ✅ Good — clear, refactor-safe
+import AppState from '#store/AppState.js';
+import { formatDate } from '#utils/formatDate.js';
+import '#atoms/app-badge/app-badge.js';
+
+// ❌ Bad — fragile, hard to read
+import AppState from '../../../store/AppState.js';
+```
+
+---
+
 ## Error Handling
 
 Errors are handled **at the boundary where they are actionable.** Each layer
@@ -193,8 +237,8 @@ state: store(AppState),
 // In src/utils/filterActive.js
 export const filterActive = (items) => items.filter(i => i.active);
 
-// In component
-import { filterActive } from '../../utils/filterActive.js';
+// In component — use import map alias, never ../
+import { filterActive } from '#utils/filterActive.js';
 render: ({ items }) => html`<ul>${filterActive(items).map(...)}</ul>`,
 ```
 

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

@@ -121,7 +121,14 @@ declared in `src/index.html`.
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js",
+          "#store/": "/store/",
+          "#utils/": "/utils/",
+          "#atoms/": "/components/atoms/",
+          "#molecules/": "/components/molecules/",
+          "#organisms/": "/components/organisms/",
+          "#templates/": "/components/templates/",
+          "#pages/": "/pages/"
         }
       }
     </script>
@@ -139,6 +146,8 @@ declared in `src/index.html`.
 2. Import map resolves `'hybrids'` → `/vendor/hybrids/index.js`.
 3. Server serves the file from `src/vendor/hybrids/index.js`.
 4. Hybrids' internal imports use relative paths — they resolve naturally.
+5. `#prefix/` entries resolve cross-directory app imports without `../`.
+   For example, `import '#utils/formatDate.js'` resolves to `/utils/formatDate.js`.
 
 ### Rules
 

package/templates/shared/src/components/atoms/theme-toggle/theme-toggle.js

@@ -5,11 +5,11 @@
  */
 
 import { html, define, store } from 'hybrids';
-import AppState from '../../../store/AppState.js';
+import AppState from '#store/AppState.js';
 
 /**
  * @typedef {Object} ThemeToggleHost
- * @property {import('../../../store/AppState.js').AppState} state
+ * @property {import('#store/AppState.js').AppState} state
  */
 
 /**

package/templates/shared/src/index.html

@@ -14,7 +14,14 @@
     <script type="importmap">
       {
         "imports": {
-          "hybrids": "/vendor/hybrids/index.js"
+          "hybrids": "/vendor/hybrids/index.js",
+          "#store/": "/store/",
+          "#utils/": "/utils/",
+          "#atoms/": "/components/atoms/",
+          "#molecules/": "/components/molecules/",
+          "#organisms/": "/components/organisms/",
+          "#templates/": "/components/templates/",
+          "#pages/": "/pages/"
         }
       }
     </script>

package/templates/static/src/pages/home/home-view.js

@@ -4,12 +4,12 @@
  */
 
 import { html, define, store } from 'hybrids';
-import AppState from '../../store/AppState.js';
-import '../../components/atoms/app-button/app-button.js';
+import AppState from '#store/AppState.js';
+import '#atoms/app-button/app-button.js';
 
 /**
  * @typedef {Object} HomeViewHost
- * @property {import('../../store/AppState.js').AppState} state
+ * @property {import('#store/AppState.js').AppState} state
  */
 
 /** @param {HomeViewHost & HTMLElement} host */

package/templates/static/src/router/index.js

@@ -4,7 +4,7 @@
  */
 
 import { html, define, router } from 'hybrids';
-import HomeView from '../pages/home/home-view.js';
+import HomeView from '#pages/home/home-view.js';
 
 export default define({
   tag: 'app-router',