tenbo-dashboard 0.1.0 → 0.3.0

package/README.md

@@ -2,8 +2,6 @@
 
 Local architecture dashboard and CLI tools for [tenbo](https://github.com/poyi/tenbo) — an agentic project manager for AI-assisted coding.
 
-![tenbo dashboard — kanban board view](https://raw.githubusercontent.com/poyi/tenbo/main/docs/images/dashboard-kanban.png)
-
 ## Quick start
 
 ```bash
@@ -11,21 +9,47 @@ Local architecture dashboard and CLI tools for [tenbo](https://github.com/poyi/t
 npx tenbo-dashboard
 ```
 
-Opens a local dashboard for browsing roadmaps, triaging items, and drag-reorder.
+Opens a local dashboard at http://localhost:5174.
+
+## What it gives you
+
+Three views over the same `.tenbo/` files Claude maintains. Edits in either surface show up in the other on next refresh.
+
+### Roadmap — what to work on next
+
+![tenbo dashboard — kanban view](https://raw.githubusercontent.com/poyi/tenbo/main/docs/images/dashboard-kanban.png)
+
+Kanban across `now` / `next` / `later` / `done`, grouped by scope and layer. Drag to reprioritize, click to edit. The same roadmap Claude reads when you ask "what should I build next?".
+
+### Docs — what the project actually does
+
+![tenbo dashboard — docs view](https://raw.githubusercontent.com/poyi/tenbo/main/docs/images/dashboard-docs.png)
+
+Project overview, principles, and glossary alongside per-layer narratives, intents (responsibilities + boundaries + invariants), and code maps (entry points + key files + extension recipes). Onboard new contributors — human or AI — in minutes instead of an hour of grep.
+
+### Health — where the codebase is quietly rotting
+
+![tenbo dashboard — health view](https://raw.githubusercontent.com/poyi/tenbo/main/docs/images/dashboard-health.png)
+
+Surfaces the things that would otherwise become tech debt nobody mentions: oversized layers (hotspots), code-map references that no longer match real files (doc drift), unreferenced files, coupling violations, dead code. Each finding carries a severity, the file it points at, and a suggested fix.
 
 ## CLI tools
 
+The same package ships commands the skill uses behind the scenes — also runnable directly:
+
 ```bash
-npx tenbo-dashboard validate          # Run validation rules
+npx tenbo-dashboard validate          # Schema + consistency checks
+npx tenbo-dashboard init-check        # Strict completeness check after fresh init
+npx tenbo-dashboard metrics --all     # Recompute scope metrics + health findings
 npx tenbo-dashboard next-id <prefix>  # Allocate next roadmap item ID
-npx tenbo-dashboard metrics --all     # Compute scope metrics
+npx tenbo-dashboard --version         # Print the installed version
 ```
 
 ## What is tenbo?
 
-tenbo is a Claude Code skill that gives your AI coding assistant persistent project memory — architecture docs, roadmaps, and health signals that survive across sessions. The dashboard is an optional visual companion.
+An AI cofounder that gives your coding assistant persistent project memory — architecture docs, roadmaps, and health signals that survive across sessions. Available as a Claude Code skill and as a Cursor rule package; both editors share the same `.tenbo/` data and the same companion dashboard. The dashboard is the optional visual companion; the skill / rule is the always-on conversational brain.
 
-Install the skill: [github.com/poyi/tenbo](https://github.com/poyi/tenbo)
+Install: [github.com/poyi/tenbo](https://github.com/poyi/tenbo) (instructions for both Claude Code and Cursor)
 
 ## License
 

package/bin/launch-dashboard.mjs

@@ -0,0 +1,8 @@
+import { createServer } from 'vite';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const server = await createServer({ root, configFile: path.join(root, 'vite.config.ts') });
+await server.listen();
+server.printUrls();

package/bin/tenbo-dashboard.mjs

@@ -1,22 +1,48 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
+/**
+ * Find the tsx binary by walking up node_modules from this file's directory.
+ * Required because npm hoists shared dependencies to a parent node_modules,
+ * so `<package>/node_modules/.bin/tsx` may not exist for consumers.
+ */
+function findTsx() {
+  let dir = __dirname;
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, 'node_modules', '.bin', 'tsx');
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return 'tsx'; // last-resort fallback to PATH
+}
+
 const [command, ...args] = process.argv.slice(2);
 
+if (command === '--version' || command === '-v' || command === 'version') {
+  const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
 const commands = {
   validate: 'scripts/validate-cli.ts',
   'next-id': 'scripts/next-id.ts',
   metrics: 'scripts/compute-metrics.ts',
+  'init-check': 'scripts/init-check.ts',
+  sync: 'scripts/sync.ts',
 };
 
 function run(script, scriptArgs) {
-  const tsx = path.join(root, 'node_modules', '.bin', 'tsx');
+  const tsx = findTsx();
   const child = spawn(tsx, [path.join(root, script), ...scriptArgs], {
     stdio: 'inherit',
     cwd: process.cwd(),
@@ -25,18 +51,8 @@ function run(script, scriptArgs) {
 }
 
 function startDashboard() {
-  // Use Vite's JS API to start the dev server
-  const viteScript = `
-    import { createServer } from 'vite';
-    import { fileURLToPath } from 'node:url';
-    import path from 'node:path';
-    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-    const server = await createServer({ root, configFile: path.join(root, 'vite.config.ts') });
-    await server.listen();
-    server.printUrls();
-  `;
-  const tsx = path.join(root, 'node_modules', '.bin', 'tsx');
-  const child = spawn(tsx, ['--eval', viteScript], {
+  const launcher = path.join(__dirname, 'launch-dashboard.mjs');
+  const child = spawn(process.execPath, [launcher], {
     stdio: 'inherit',
     cwd: process.cwd(),
     env: { ...process.env, TENBO_CWD: process.cwd() },
@@ -44,15 +60,18 @@ function startDashboard() {
   child.on('close', (code) => process.exit(code ?? 0));
 }
 
-if (!command || command === 'help' || command === '--help') {
+if (command === 'help' || command === '--help') {
   console.log(`
 tenbo-dashboard — local architecture dashboard for .tenbo/ repos
 
 Usage:
   tenbo-dashboard                  Launch the dashboard (http://localhost:5174)
+  tenbo-dashboard sync             Refresh tenbo state after a change (metrics + init-check + validate, surfaces new findings)
   tenbo-dashboard validate         Run validation rules
+  tenbo-dashboard init-check       Strict completeness check for fresh init (errors on missing skeletons, file_count:0, etc)
   tenbo-dashboard next-id <prefix> Allocate next roadmap item ID
   tenbo-dashboard metrics --all    Compute scope metrics
+  tenbo-dashboard --version        Print package version
   tenbo-dashboard help             Show this help
 `);
   process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",
@@ -45,20 +45,22 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^8.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@vitejs/plugin-react": "^4.3.1",
     "@xyflow/react": "^12.10.2",
     "chokidar": "^3.6.0",
     "dagre": "^0.8.5",
     "gray-matter": "^4.0.3",
+    "jscpd": "^4",
     "lucide-react": "^0.545.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-markdown": "^9.0.1",
     "remark-gfm": "^4.0.0",
-    "yaml": "^2.5.1",
-    "@vitejs/plugin-react": "^4.3.1",
+    "ts-morph": "^25",
     "tsx": "^4.19.0",
     "typescript": "^5.5.4",
-    "vite": "^5.4.3"
+    "vite": "^5.4.3",
+    "yaml": "^2.5.1"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -67,9 +69,7 @@
     "@types/node": "^22.5.4",
     "@types/react": "^18.3.5",
     "@types/react-dom": "^18.3.0",
-    "jscpd": "^4",
     "jsdom": "^25.0.0",
-    "ts-morph": "^25",
     "vitest": "^2.0.5"
   }
 }

package/scripts/init-check.ts

@@ -0,0 +1,133 @@
+/**
+ * init-check.ts — strict variant of validate, used by the skill at the end of
+ * the Initialize Project Memory flow.
+ *
+ * Reuses the standard validator, then upgrades or adds checks that catch
+ * silent init failures (missing skeleton docs, glob mistakes producing
+ * `file_count: 0`, missing principles.md/glossary.md, missing metrics.json).
+ *
+ * Exit codes:
+ *   0 — every init artifact is present and structurally sound
+ *   1 — at least one init defect found
+ *   2 — could not locate repo root
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+import { readState } from '../src/api/lib/tenboFs';
+import { validate } from '../src/api/lib/validator';
+
+interface InitDefect {
+  message: string;
+  scope?: string;
+  layerId?: string;
+}
+
+export function runInitCheck(repoRoot: string): { defects: InitDefect[]; preExistingErrors: number } {
+  const defects: InitDefect[] = [];
+  const tenbo = path.join(repoRoot, '.tenbo');
+
+  // Repo-level files
+  if (!fs.existsSync(path.join(tenbo, 'workspace.yaml'))) {
+    defects.push({ message: 'missing .tenbo/workspace.yaml' });
+  }
+  if (!fs.existsSync(path.join(tenbo, 'principles.md'))) {
+    defects.push({ message: 'missing .tenbo/principles.md (init step 8 — write from template)' });
+  }
+  if (!fs.existsSync(path.join(tenbo, 'glossary.md'))) {
+    defects.push({ message: 'missing .tenbo/glossary.md (init step 8 — write from template)' });
+  }
+
+  const state = readState(repoRoot);
+
+  // Per-scope and per-layer
+  for (const scope of state.scopes) {
+    const scopeDir = path.join(tenbo, 'scopes', scope.id);
+    const metricsPath = path.join(scopeDir, 'metrics.json');
+
+    if (!fs.existsSync(metricsPath)) {
+      defects.push({
+        message: `scope "${scope.id}" missing metrics.json — run "npx tenbo-dashboard metrics --all"`,
+        scope: scope.id,
+      });
+    } else {
+      // Check for the silent glob bug: file_count: 0 in a scope that obviously has files.
+      try {
+        const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+        const layers = metrics?.layers ?? {};
+        // Quick file existence check on the scope path
+        const scopeRoot = path.resolve(repoRoot, scope.path ?? '.');
+        const scopeHasFiles = fs.existsSync(scopeRoot) && fs.readdirSync(scopeRoot).length > 0;
+        for (const [layerId, m] of Object.entries(layers) as [string, { file_count?: number }][]) {
+          if (scopeHasFiles && (m.file_count ?? 0) === 0) {
+            defects.push({
+              message: `layer "${layerId}" has file_count: 0 despite scope "${scope.id}" containing files — likely a glob path mistake. Globs in architecture.yaml are RELATIVE to scope.path (not the repo root). See architecture.yaml.tmpl header comment.`,
+              scope: scope.id,
+              layerId,
+            });
+          }
+        }
+      } catch (e) {
+        defects.push({
+          message: `scope "${scope.id}" metrics.json is unreadable: ${(e as Error).message}`,
+          scope: scope.id,
+        });
+      }
+    }
+
+    for (const layer of scope.layers) {
+      const docs = state.layerDocs?.[`${scope.id}/${layer.id}`];
+      if (!docs?.hasIntent) {
+        defects.push({
+          message: `layer "${layer.id}" missing intent.md (init step 8 — write skeleton from template)`,
+          scope: scope.id,
+          layerId: layer.id,
+        });
+      }
+      if (!docs?.hasCodeMap) {
+        defects.push({
+          message: `layer "${layer.id}" missing code-map.md (init step 8 — write skeleton from template)`,
+          scope: scope.id,
+          layerId: layer.id,
+        });
+      }
+    }
+  }
+
+  // Reuse standard validator for everything else; treat its errors as defects.
+  const result = validate(state);
+  for (const e of result.errors) {
+    defects.push({ message: e.message, scope: e.scope, layerId: e.layerId });
+  }
+
+  return { defects, preExistingErrors: result.errors.length };
+}
+
+function isMain(): boolean {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const here = path.resolve(new URL(import.meta.url).pathname);
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const repoRoot = findRepoRoot(process.cwd());
+  if (!repoRoot) {
+    process.stderr.write('init-check: unable to find repo root (no .tenbo/ in any parent directory)\n');
+    process.exit(2);
+  }
+  const { defects } = runInitCheck(repoRoot);
+  if (defects.length === 0) {
+    process.stdout.write('init-check: all init artifacts present.\n');
+    process.exit(0);
+  }
+  process.stderr.write(`init-check FAILED — ${defects.length} init defect(s):\n`);
+  for (const d of defects) {
+    const loc = d.scope ? ` [${d.scope}${d.layerId ? `/${d.layerId}` : ''}]` : '';
+    process.stderr.write(`  ❌${loc} ${d.message}\n`);
+  }
+  process.exit(1);
+}

package/scripts/sync.ts

@@ -0,0 +1,144 @@
+/**
+ * sync.ts — single command for "make tenbo state fresh after a change".
+ *
+ * Runs metrics --all (or --scope <id>) + init-check + validate, then prints
+ * a unified summary of NEW findings (severity >= warning) introduced since
+ * the prior metrics.json snapshot. Replaces three separate commands the
+ * skill used to invoke at init and completion time, eliminating the
+ * silent-staleness failure mode where an agent forgot one of the three.
+ *
+ * Exit codes:
+ *   0 — everything refreshed cleanly, no new errors
+ *   1 — an error in any step (validation failure, init defect, metrics throw)
+ *   2 — could not locate repo root
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+import { runComputeMetrics } from './compute-metrics';
+import { runInitCheck } from './init-check';
+import { readState } from '../src/api/lib/tenboFs';
+import { validate } from '../src/api/lib/validator';
+import type { ScopeMetrics } from '../src/types';
+
+interface NewFinding {
+  scope: string;
+  layer: string;
+  severity: string;
+  signal: string;
+  headline: string;
+}
+
+function readMetrics(metricsPath: string): ScopeMetrics | null {
+  try {
+    if (!fs.existsSync(metricsPath)) return null;
+    return JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function findingKey(scope: string, f: { signal: string; layer: string; headline: string }): string {
+  return `${scope}::${f.signal}::${f.layer}::${f.headline}`;
+}
+
+interface SyncArgs {
+  repoRoot: string;
+  scope?: string; // single-scope refresh; omit to refresh all
+}
+
+export async function runSync(args: SyncArgs): Promise<number> {
+  const { repoRoot, scope } = args;
+
+  // Snapshot prior findings so we can diff after the refresh.
+  const state = readState(repoRoot);
+  const targetScopes = scope ? [scope] : state.scopes.map((s) => s.id);
+  const priorFindingKeys = new Set<string>();
+  for (const id of targetScopes) {
+    const m = readMetrics(path.join(repoRoot, '.tenbo', 'scopes', id, 'metrics.json'));
+    for (const f of m?.findings ?? []) priorFindingKeys.add(findingKey(id, f));
+  }
+
+  // 1. metrics
+  const metricsCode = await runComputeMetrics({
+    repoRoot,
+    all: !scope,
+    scope,
+  });
+  if (metricsCode !== 0) {
+    process.stderr.write('sync: metrics step failed\n');
+    return 1;
+  }
+
+  // 2. init-check
+  const { defects } = runInitCheck(repoRoot);
+  if (defects.length > 0) {
+    process.stderr.write(`sync: init-check FAILED — ${defects.length} init defect(s):\n`);
+    for (const d of defects) {
+      const loc = d.scope ? ` [${d.scope}${d.layerId ? `/${d.layerId}` : ''}]` : '';
+      process.stderr.write(`  ❌${loc} ${d.message}\n`);
+    }
+    return 1;
+  }
+
+  // 3. validate (re-read state after metrics may have changed scope dirs)
+  const stateAfter = readState(repoRoot);
+  const result = validate(stateAfter);
+  if (result.errors.length > 0) {
+    process.stderr.write(`sync: validate FAILED — ${result.errors.length} error(s):\n`);
+    for (const e of result.errors) process.stderr.write(`  ❌ ${e.message}\n`);
+    return 1;
+  }
+
+  // 4. Diff findings: surface NEW critical/warning findings introduced this run.
+  const newFindings: NewFinding[] = [];
+  for (const id of targetScopes) {
+    const m = readMetrics(path.join(repoRoot, '.tenbo', 'scopes', id, 'metrics.json'));
+    for (const f of m?.findings ?? []) {
+      if (f.severity === 'info') continue;
+      if (priorFindingKeys.has(findingKey(id, f))) continue;
+      newFindings.push({
+        scope: id,
+        layer: f.layer,
+        severity: f.severity,
+        signal: f.signal,
+        headline: f.headline,
+      });
+    }
+  }
+
+  // 5. Summary line + (optional) new-finding lines.
+  const scopeLabel = scope ? `scope "${scope}"` : `${targetScopes.length} scope(s)`;
+  if (newFindings.length === 0) {
+    process.stdout.write(`sync: ${scopeLabel} fresh. No new errors, no new warning/critical findings.\n`);
+    return 0;
+  }
+  process.stdout.write(`sync: ${scopeLabel} fresh. ${newFindings.length} new finding(s) since last refresh:\n`);
+  for (const f of newFindings) {
+    const icon = f.severity === 'critical' ? '🔴' : '⚠️';
+    process.stdout.write(`  ${icon} [${f.scope}/${f.layer}] ${f.signal}: ${f.headline}\n`);
+  }
+  return 0;
+}
+
+function isMain(): boolean {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const here = path.resolve(new URL(import.meta.url).pathname);
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) {
+  const args = process.argv.slice(2);
+  const scopeIdx = args.indexOf('--scope');
+  const scope = scopeIdx >= 0 ? args[scopeIdx + 1] : undefined;
+  const repoRoot = findRepoRoot(process.cwd());
+  if (!repoRoot) {
+    process.stderr.write('sync: unable to find repo root (no .git in any parent directory)\n');
+    process.exit(2);
+  }
+  runSync({ repoRoot, scope }).then((code) => process.exit(code));
+}

package/vite.config.ts

@@ -5,5 +5,26 @@ import { tenboApiPlugin } from './src/api/plugin';
 export default defineConfig({
   plugins: [react(), tenboApiPlugin()],
   server: { port: 5174 },
+  // Force pre-bundling of the markdown chain. When the dashboard is installed as a
+  // consumer dependency, Vite's optimizer fails to walk into transitive CJS deps
+  // like `style-to-js`, and serving them raw via `/@fs/` produces a silent
+  // "module does not provide an export named 'default'" SyntaxError that aborts
+  // React mounting. Listing them here makes Vite pre-bundle them with proper
+  // ESM interop.
+  optimizeDeps: {
+    include: [
+      // React subpath — the optimizer auto-handles `react-dom` root but NOT
+      // `react-dom/client`, so the subpath gets served raw via `/@fs/` and
+      // breaks default-import interop in consumer installs.
+      'react-dom/client',
+      // Markdown chain — transitive CJS deps (style-to-js, hast-util-to-jsx-runtime)
+      // also need explicit pre-bundling for consumer installs. Without this,
+      // they're served raw and produce silent SyntaxError aborting React mount.
+      'react-markdown',
+      'remark-gfm',
+      'style-to-js',
+      'hast-util-to-jsx-runtime',
+    ],
+  },
   test: { environment: 'jsdom', globals: true, setupFiles: ['./src/test-setup.ts'] },
 });