@techninja/clearstack 0.3.9 → 0.3.11

package/bin/cli.js

@@ -5,7 +5,7 @@
  * Usage:
  *   clearstack init [-y] [--mode fullstack|static] [--port 3000]
  *   clearstack update
- *   clearstack check [code|docs]
+ *   clearstack check [code|docs|imports|lint|lint es|format|types|audit|all]
  *   clearstack                   → interactive menu
  */
 
@@ -25,16 +25,21 @@ const yes = args.includes('-y') || args.includes('--yes');
 
 /** Show interactive menu. */
 async function interactive() {
-  const { select } = await import('@inquirer/prompts');
-  const action = await select({
-    message: 'clearstack — what do you want to do?',
-    choices: [
-      { name: 'Initialize a new project', value: 'init' },
-      { name: 'Update spec docs + configs', value: 'update' },
-      { name: 'Run spec compliance check', value: 'check' },
-    ],
-  });
-  await run(action);
+  try {
+    const { select } = await import('@inquirer/prompts');
+    const action = await select({
+      message: 'clearstack — what do you want to do?',
+      choices: [
+        { name: 'Initialize a new project', value: 'init' },
+        { name: 'Update spec docs + configs', value: 'update' },
+        { name: 'Run spec compliance check', value: 'check' },
+      ],
+    });
+    await run(action);
+  } catch (e) {
+    if (e?.name === 'ExitPromptError') process.exit(0);
+    throw e;
+  }
 }
 
 /**
@@ -49,9 +54,9 @@ async function run(action) {
     const { update } = await import('../lib/update.js');
     await update(PKG_ROOT);
   } else if (action === 'check') {
-    const sub = args.find((a) => a !== cmd && !a.startsWith('-'));
+    const subs = args.filter((a) => a !== cmd && !a.startsWith('-'));
     const { check } = await import('../lib/check.js');
-    await check(process.cwd(), sub);
+    await check(process.cwd(), subs.join(' ') || undefined);
   } else {
     console.log('Usage: clearstack [init|update|check] [-y]');
   }

package/docs/CONVENTIONS.md

@@ -117,15 +117,15 @@ 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/`                      |
+| Prefix        | Resolves to              |
+| ------------- | ------------------------ |
+| `#store/`     | `/store/`                |
+| `#utils/`     | `/utils/`                |
+| `#atoms/`     | `/components/atoms/`     |
+| `#molecules/` | `/components/molecules/` |
+| `#organisms/` | `/components/organisms/` |
+| `#templates/` | `/components/templates/` |
+| `#pages/`     | `/pages/`                |
 
 ### Rules
 

package/docs/STATE_AND_ROUTING.md

@@ -43,12 +43,12 @@ If a property is defined as `undefined` or later set to `null`, this crashes:
 // ❌ BAD — undefined has no type info, null crashes .toString()
 export default define({
   tag: 'my-view',
-  _data: undefined,  // no type info for hybrids to work with
+  _data: undefined, // no type info for hybrids to work with
   // ...
 });
 
 // Later in a handler:
-host._data = null;  // TypeError: Cannot read properties of null (reading 'toString')
+host._data = null; // TypeError: Cannot read properties of null (reading 'toString')
 ```
 
 Always provide a typed default value, and reset to the same type:
@@ -62,7 +62,7 @@ export default define({
 });
 
 // Later in a handler:
-host._data = [];  // safe — same type as default
+host._data = []; // safe — same type as default
 ```
 
 The `connect: () => {}` no-op prevents hybrids from doing anything special
@@ -232,14 +232,16 @@ export default define({
   items: {
     value: [],
     connect: (host, _key, invalidate) => {
-      fetchItems().then((list) => { host.items = list; invalidate(); });
+      fetchItems().then((list) => {
+        host.items = list;
+        invalidate();
+      });
     },
   },
   render: ({ items }) => html`
     // ❌ BAD — items may not be an array yet when render fires
-    ${items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)}
-
-    // ✅ GOOD — guard before calling array methods
+    ${items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)} // ✅ GOOD — guard
+    before calling array methods
     ${Array.isArray(items) && items.length > 0
       ? items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)
       : html``}
@@ -350,7 +352,7 @@ properties holding complex objects (arrays of records, parsed data, etc.),
 the URL becomes enormous — potentially megabytes — and the browser locks
 up just rendering the `<a>` element.
 
-The `connect: () => {}` no-op prevents hybrids from *observing* a property,
+The `connect: () => {}` no-op prevents hybrids from _observing_ a property,
 but the router still serializes it. The only way to fully exclude a
 property from URL serialization is to not define it on the routed view at
 all (use a module-level variable or a separate store).
@@ -361,10 +363,10 @@ direct href instead of `router.backUrl()`:
 ```javascript
 // ❌ BAD — serializes ALL parent properties into the href
 // If parent has a 700K-item array, the URL is megabytes
-html`<a href="${router.backUrl()}">← Back</a>`
+html`<a href="${router.backUrl()}">← Back</a>`;
 
 // ✅ GOOD — direct link, no serialization
-html`<a href="/dashboard">← Back</a>`
+html`<a href="/dashboard">← Back</a>`;
 ```
 
 Use `router.backUrl()` only when the parent view has simple scalar
@@ -476,25 +478,11 @@ re-fetches automatically.
 ### Debouncing Batch Operations
 
 Operations like drag-to-reorder send multiple PUTs, each triggering an SSE
-event. Without debouncing, each event clears the store and triggers a
-re-render while the previous render is still pending — causing cascading
-errors.
+event. Without debouncing, each event clears the store mid-render.
 
 The `connectRealtime()` utility debounces by entity type: multiple SSE
-events within 300ms trigger only one `store.clear()`. This means a reorder
-of 5 tasks sends 5 PUTs → 5 SSE events → 1 store clear after 300ms.
-
-```javascript
-// Inside connectRealtime — debounce per entity type
-const timers = {};
-source.addEventListener('update', (event) => {
-  const { type } = JSON.parse(event.data);
-  clearTimeout(timers[type]);
-  timers[type] = setTimeout(() => {
-    store.clear([Model]); // one clear after the batch settles
-  }, 300);
-});
-```
+events within 300ms trigger only one `store.clear()`. A reorder of 5 tasks
+sends 5 PUTs → 5 SSE events → 1 store clear after the batch settles.
 
-For the local user, the UI should not call `store.clear()` explicitly
-after batch operations — let the debounced SSE handler do it once.
+For the local user, don't call `store.clear()` explicitly after batch
+operations — let the debounced SSE handler do it once.

package/lib/check.js

@@ -114,7 +114,7 @@ export async function check(projectDir, scope) {
   const cmds = buildCmds(detectRunner(projectDir));
   const checks = buildChecks(projectDir, cfg, cmds);
 
-  if (scope) {
+  if (scope && scope !== 'all') {
     const matched = resolveChecks(checks, scope);
     if (!matched) {
       console.log(`Unknown check: ${scope}`);

package/package.json

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

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

@@ -117,15 +117,15 @@ 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/`                      |
+| Prefix        | Resolves to              |
+| ------------- | ------------------------ |
+| `#store/`     | `/store/`                |
+| `#utils/`     | `/utils/`                |
+| `#atoms/`     | `/components/atoms/`     |
+| `#molecules/` | `/components/molecules/` |
+| `#organisms/` | `/components/organisms/` |
+| `#templates/` | `/components/templates/` |
+| `#pages/`     | `/pages/`                |
 
 ### Rules
 

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

@@ -43,12 +43,12 @@ If a property is defined as `undefined` or later set to `null`, this crashes:
 // ❌ BAD — undefined has no type info, null crashes .toString()
 export default define({
   tag: 'my-view',
-  _data: undefined,  // no type info for hybrids to work with
+  _data: undefined, // no type info for hybrids to work with
   // ...
 });
 
 // Later in a handler:
-host._data = null;  // TypeError: Cannot read properties of null (reading 'toString')
+host._data = null; // TypeError: Cannot read properties of null (reading 'toString')
 ```
 
 Always provide a typed default value, and reset to the same type:
@@ -62,7 +62,7 @@ export default define({
 });
 
 // Later in a handler:
-host._data = [];  // safe — same type as default
+host._data = []; // safe — same type as default
 ```
 
 The `connect: () => {}` no-op prevents hybrids from doing anything special
@@ -232,14 +232,16 @@ export default define({
   items: {
     value: [],
     connect: (host, _key, invalidate) => {
-      fetchItems().then((list) => { host.items = list; invalidate(); });
+      fetchItems().then((list) => {
+        host.items = list;
+        invalidate();
+      });
     },
   },
   render: ({ items }) => html`
     // ❌ BAD — items may not be an array yet when render fires
-    ${items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)}
-
-    // ✅ GOOD — guard before calling array methods
+    ${items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)} // ✅ GOOD — guard
+    before calling array methods
     ${Array.isArray(items) && items.length > 0
       ? items.filter((i) => i.active).map((i) => html`<span>${i.name}</span>`)
       : html``}
@@ -350,7 +352,7 @@ properties holding complex objects (arrays of records, parsed data, etc.),
 the URL becomes enormous — potentially megabytes — and the browser locks
 up just rendering the `<a>` element.
 
-The `connect: () => {}` no-op prevents hybrids from *observing* a property,
+The `connect: () => {}` no-op prevents hybrids from _observing_ a property,
 but the router still serializes it. The only way to fully exclude a
 property from URL serialization is to not define it on the routed view at
 all (use a module-level variable or a separate store).
@@ -361,10 +363,10 @@ direct href instead of `router.backUrl()`:
 ```javascript
 // ❌ BAD — serializes ALL parent properties into the href
 // If parent has a 700K-item array, the URL is megabytes
-html`<a href="${router.backUrl()}">← Back</a>`
+html`<a href="${router.backUrl()}">← Back</a>`;
 
 // ✅ GOOD — direct link, no serialization
-html`<a href="/dashboard">← Back</a>`
+html`<a href="/dashboard">← Back</a>`;
 ```
 
 Use `router.backUrl()` only when the parent view has simple scalar
@@ -476,25 +478,11 @@ re-fetches automatically.
 ### Debouncing Batch Operations
 
 Operations like drag-to-reorder send multiple PUTs, each triggering an SSE
-event. Without debouncing, each event clears the store and triggers a
-re-render while the previous render is still pending — causing cascading
-errors.
+event. Without debouncing, each event clears the store mid-render.
 
 The `connectRealtime()` utility debounces by entity type: multiple SSE
-events within 300ms trigger only one `store.clear()`. This means a reorder
-of 5 tasks sends 5 PUTs → 5 SSE events → 1 store clear after 300ms.
-
-```javascript
-// Inside connectRealtime — debounce per entity type
-const timers = {};
-source.addEventListener('update', (event) => {
-  const { type } = JSON.parse(event.data);
-  clearTimeout(timers[type]);
-  timers[type] = setTimeout(() => {
-    store.clear([Model]); // one clear after the batch settles
-  }, 300);
-});
-```
+events within 300ms trigger only one `store.clear()`. A reorder of 5 tasks
+sends 5 PUTs → 5 SSE events → 1 store clear after the batch settles.
 
-For the local user, the UI should not call `store.clear()` explicitly
-after batch operations — let the debounced SSE handler do it once.
+For the local user, don't call `store.clear()` explicitly after batch
+operations — let the debounced SSE handler do it once.