tenbo-dashboard 0.1.0

package/src/api/plugin.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from 'vite';
+import { findRepoRoot } from './lib/repoRoot';
+import { stateRoute } from './routes/state';
+import { itemsRoute } from './routes/items';
+import { reorderRoute } from './routes/reorder';
+import { relatedRoute } from './routes/related';
+import { openRoute } from './routes/open';
+import { watchRoute } from './routes/watch';
+import { layerDocsRoute } from './routes/layerDocs';
+import { layerContentRoute } from './routes/layerContent';
+
+export function tenboApiPlugin(): Plugin {
+  return {
+    name: 'tenbo-api',
+    configureServer(server) {
+      const repoRoot = findRepoRoot(process.cwd());
+      if (!repoRoot) {
+        console.error('[tenbo-dashboard] no git repo root found from cwd');
+        return;
+      }
+      server.middlewares.use(stateRoute(repoRoot));
+      server.middlewares.use(itemsRoute(repoRoot));
+      server.middlewares.use(reorderRoute(repoRoot));
+      server.middlewares.use(relatedRoute(repoRoot));
+      server.middlewares.use(openRoute(repoRoot));
+      server.middlewares.use(watchRoute(repoRoot));
+      server.middlewares.use(layerDocsRoute(repoRoot));
+      server.middlewares.use(layerContentRoute(repoRoot));
+    },
+  };
+}

package/src/api/routes/items.ts

@@ -0,0 +1,25 @@
+import type { Connect } from 'vite';
+import { patchItem } from '../lib/tenboFs';
+import { readBody, json, error, withErrorHandling } from '../lib/http';
+
+const ALLOWED = new Set(['title', 'description', 'status', 'layer', 'notes', 'links', 'priority', 'done_when', 'files_to_read', 'risks']);
+
+export function itemsRoute(repoRoot: string): Connect.NextHandleFunction {
+  return withErrorHandling(async (req, res, next) => {
+    const m = req.url?.match(/^\/api\/items\/([^/?]+)(\?.*)?$/);
+    if (!m || req.method !== 'PATCH') return next();
+    const itemId = m[1];
+    const body = await readBody<{ scope?: string; patch?: Record<string, unknown> }>(req);
+    const scopeId = body.scope;
+    const patch = body.patch;
+    if (!scopeId || !patch) {
+      return error(res, 400, 'scope and patch required');
+    }
+    const filtered: Record<string, unknown> = {};
+    for (const k of Object.keys(patch)) {
+      if (ALLOWED.has(k)) filtered[k] = patch[k];
+    }
+    patchItem(repoRoot, scopeId, itemId, filtered);
+    json(res, { ok: true });
+  });
+}

package/src/api/routes/layerContent.ts

@@ -0,0 +1,22 @@
+import type { Connect } from 'vite';
+import { readLayerContent } from '../lib/tenboFs';
+import { json, error } from '../lib/http';
+
+export function layerContentRoute(repoRoot: string): Connect.NextHandleFunction {
+  return (req, res, next) => {
+    if (req.method !== 'GET' || !req.url?.startsWith('/api/layer-content')) return next();
+    const url = new URL(req.url, 'http://localhost');
+    const scope = url.searchParams.get('scope');
+    const layer = url.searchParams.get('layer');
+    if (!scope || !layer) {
+      error(res, 400, 'scope and layer query parameters are required');
+      return;
+    }
+    try {
+      const content = readLayerContent(repoRoot, scope, layer);
+      json(res, content);
+    } catch (err) {
+      error(res, 500, String(err));
+    }
+  };
+}

package/src/api/routes/layerDocs.ts

@@ -0,0 +1,22 @@
+import type { Connect } from 'vite';
+import { listLayerDocs } from '../lib/tenboFs';
+import { json, error } from '../lib/http';
+
+export function layerDocsRoute(repoRoot: string): Connect.NextHandleFunction {
+  return (req, res, next) => {
+    if (req.method !== 'GET' || !req.url?.startsWith('/api/layer-docs')) return next();
+    const url = new URL(req.url, 'http://localhost');
+    const scopeId = url.searchParams.get('scope');
+    const layerId = url.searchParams.get('layer');
+    if (!scopeId || !layerId) {
+      error(res, 400, 'scope and layer query params required');
+      return;
+    }
+    try {
+      const docs = listLayerDocs(repoRoot, scopeId, layerId);
+      json(res, docs);
+    } catch (err) {
+      error(res, 500, String(err));
+    }
+  };
+}

package/src/api/routes/open.ts

@@ -0,0 +1,18 @@
+import type { Connect } from 'vite';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { readBody, json, error, withErrorHandling } from '../lib/http';
+
+export function openRoute(repoRoot: string): Connect.NextHandleFunction {
+  return withErrorHandling(async (req, res, next) => {
+    if (req.method !== 'POST' || req.url !== '/api/open') return next();
+    const { path: rel } = await readBody<{ path?: unknown }>(req);
+    if (typeof rel !== 'string') {
+      return error(res, 400, 'path required');
+    }
+    const abs = path.resolve(repoRoot, rel);
+    // VS Code / Cursor; if `code` not on PATH, this just fails silently in spawn
+    spawn('code', ['-g', abs], { detached: true, stdio: 'ignore' }).unref();
+    json(res, { ok: true });
+  });
+}

package/src/api/routes/related.ts

@@ -0,0 +1,11 @@
+import type { Connect } from 'vite';
+import { scanForRelated } from '../lib/frontmatterScan';
+import { json, withErrorHandling } from '../lib/http';
+
+export function relatedRoute(repoRoot: string): Connect.NextHandleFunction {
+  return withErrorHandling((req, res, next) => {
+    if (req.method !== 'GET' || req.url !== '/api/related') return next();
+    const docs = scanForRelated(repoRoot);
+    json(res, docs);
+  });
+}

package/src/api/routes/reorder.ts

@@ -0,0 +1,15 @@
+import type { Connect } from 'vite';
+import { reorderItems } from '../lib/tenboFs';
+import { readBody, json, error, withErrorHandling } from '../lib/http';
+
+export function reorderRoute(repoRoot: string): Connect.NextHandleFunction {
+  return withErrorHandling(async (req, res, next) => {
+    if (req.method !== 'POST' || req.url !== '/api/items/reorder') return next();
+    const { scope, ids } = await readBody<{ scope?: string; ids?: unknown }>(req);
+    if (!scope || !Array.isArray(ids)) {
+      return error(res, 400, 'scope and ids required');
+    }
+    reorderItems(repoRoot, scope, ids as string[]);
+    json(res, { ok: true });
+  });
+}

package/src/api/routes/state.ts

@@ -0,0 +1,23 @@
+import type { Connect } from 'vite';
+import { readState, readWorkspace, tenboExists } from '../lib/tenboFs';
+import { ensureFresh } from '../lib/metricsRefresh';
+import { json, error, withErrorHandling } from '../lib/http';
+
+export function stateRoute(repoRoot: string): Connect.NextHandleFunction {
+  return withErrorHandling(async (req, res, next) => {
+    if (req.method !== 'GET' || req.url !== '/api/state') return next();
+    if (!tenboExists(repoRoot)) {
+      return error(res, 404, 'no .tenbo/ found at repo root');
+    }
+    const { scopeRefs } = readWorkspace(repoRoot);
+    for (const ref of scopeRefs) {
+      try {
+        await ensureFresh(repoRoot, ref.id);
+      } catch (e) {
+        console.warn(`tenbo: metric refresh failed for scope ${ref.id}:`, e);
+      }
+    }
+    const state = readState(repoRoot);
+    json(res, state);
+  });
+}

package/src/api/routes/watch.ts

@@ -0,0 +1,31 @@
+import type { Connect } from 'vite';
+import chokidar from 'chokidar';
+import path from 'node:path';
+
+export function watchRoute(repoRoot: string): Connect.NextHandleFunction {
+  // One watcher per process; multiple SSE clients share it.
+  const watchPath = path.join(repoRoot, '.tenbo');
+  const docsPath = path.join(repoRoot, 'docs/superpowers');
+  const watcher = chokidar.watch([watchPath, docsPath], {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+  });
+
+  type Client = { write: (data: string) => void; end: () => void };
+  const clients = new Set<Client>();
+  watcher.on('all', (event, file) => {
+    const payload = `data: ${JSON.stringify({ event, path: path.relative(repoRoot, file) })}\n\n`;
+    for (const c of clients) c.write(payload);
+  });
+
+  return (req, res, next) => {
+    if (req.method !== 'GET' || req.url !== '/api/watch') return next();
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.write(': connected\n\n');
+    const client: Client = { write: (d) => res.write(d), end: () => res.end() };
+    clients.add(client);
+    req.on('close', () => clients.delete(client));
+  };
+}

package/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}

package/src/hooks/useApiPatch.ts

@@ -0,0 +1,9 @@
+import { useCallback } from 'react';
+import type { Item } from '../types';
+import { tenboApi } from '../api/client';
+
+export function useApiPatch() {
+  return useCallback((scopeId: string, itemId: string, patch: Partial<Item>) => {
+    return tenboApi.patchItem(scopeId, itemId, patch);
+  }, []);
+}

package/src/hooks/useLayerContent.ts

@@ -0,0 +1,25 @@
+import { useEffect, useState } from 'react';
+import type { LayerContent } from '../types';
+
+export function useLayerContent(
+  scopeId: string,
+  layerId: string,
+  generation: number,
+): { content: LayerContent | null; error: string | null } {
+  const [content, setContent] = useState<LayerContent | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    setContent(null);
+    setError(null);
+    fetch(`/api/layer-content?scope=${encodeURIComponent(scopeId)}&layer=${encodeURIComponent(layerId)}`)
+      .then(async (r) => {
+        if (!r.ok) throw new Error(`GET /api/layer-content -> ${r.status}`);
+        return r.json();
+      })
+      .then((c) => { if (!cancelled) setContent(c); })
+      .catch((e) => { if (!cancelled) setError(String(e)); });
+    return () => { cancelled = true; };
+  }, [scopeId, layerId, generation]);
+  return { content, error };
+}

package/src/hooks/usePrompt.ts

@@ -0,0 +1,23 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+
+export function usePrompt() {
+  const [toast, setToast] = useState<string | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  const copy = useCallback(async (text: string, label: string) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    try {
+      await navigator.clipboard.writeText(text);
+      setToast(`${label} copied. Paste into Claude Code in the repo root.`);
+    } catch {
+      setToast('Copy failed. Select and copy manually.');
+    }
+    timerRef.current = setTimeout(() => setToast(null), 3000);
+  }, []);
+
+  return { copy, toast };
+}

package/src/hooks/useTenboState.ts

@@ -0,0 +1,35 @@
+import { useEffect, useState, useCallback, useRef } from 'react';
+import type { TenboState } from '../types';
+import { tenboApi } from '../api/client';
+
+export function useTenboState() {
+  const [state, setState] = useState<TenboState | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [generation, setGeneration] = useState<number>(0);
+  const reloadDebounce = useRef<number | null>(null);
+
+  const reload = useCallback(async () => {
+    try {
+      setState(await tenboApi.getState());
+      setGeneration(n => n + 1);
+      setLoadError(null);
+    } catch (e) {
+      setLoadError(String(e));
+    }
+  }, []);
+
+  useEffect(() => { reload(); }, [reload]);
+
+  // SSE: debounced reload on any file change
+  useEffect(() => {
+    const es = new EventSource('/api/watch');
+    es.onmessage = () => {
+      if (reloadDebounce.current) window.clearTimeout(reloadDebounce.current);
+      reloadDebounce.current = window.setTimeout(() => { reload(); }, 250);
+    };
+    es.onerror = () => { /* browser auto-reconnects */ };
+    return () => es.close();
+  }, [reload]);
+
+  return { state, loadError, reload, generation };
+}

package/src/main.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import { ErrorBoundary } from './ErrorBoundary';
+import './styles.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ErrorBoundary>
+      <App />
+    </ErrorBoundary>
+  </React.StrictMode>
+);

package/src/prompts/populateLayer.ts

@@ -0,0 +1,12 @@
+export function populateLayerPrompt(
+  target: 'intent' | 'codeMap' | 'readme',
+  scopeId: string,
+  layerId: string,
+): string {
+  const file = target === 'intent' ? 'intent.md' : target === 'codeMap' ? 'code-map.md' : 'README.md';
+  return [
+    `Run the tenbo populate-architecture behavior for scope \`${scopeId}\`, layer \`${layerId}\`.`,
+    `Focus on \`${file}\`.`,
+    `Use the universal prompting rule: ask, don't guess.`,
+  ].join('\n');
+}

package/src/router/routes.ts

@@ -0,0 +1,98 @@
+export type WorkspaceTab = typeof WORKSPACE_TABS[number];
+export type LayerTab = typeof LAYER_TABS[number];
+export type Mode = 'docs' | 'roadmap' | 'health';
+
+const WORKSPACE_TABS = ['overview', 'principles', 'glossary'] as const;
+const LAYER_TABS = ['overview', 'purpose', 'files', 'docs'] as const;
+
+export type Route =
+  | { kind: 'docs-project'; tab: WorkspaceTab }
+  | { kind: 'docs-scope'; scopeId: string }
+  | { kind: 'docs-layer'; scopeId: string; layerId: string; tab: LayerTab }
+  | { kind: 'roadmap'; scope?: string; layer?: string }
+  | { kind: 'health' }
+  | { kind: 'health-layer'; scopeId: string; layerId: string }
+  | { kind: 'item'; itemId: string }
+  | { kind: 'unknown' };
+
+function isWorkspaceTab(s: string | undefined): s is WorkspaceTab {
+  return WORKSPACE_TABS.includes(s as WorkspaceTab);
+}
+
+function isLayerTab(s: string | undefined): s is LayerTab {
+  return LAYER_TABS.includes(s as LayerTab);
+}
+
+function splitPathAndQuery(raw: string): { parts: string[]; query: URLSearchParams } {
+  const stripped = raw.replace(/^#\/?/, '');
+  const [pathPart, queryPart = ''] = stripped.split('?');
+  const parts = pathPart.split('/').filter(Boolean);
+  const query = new URLSearchParams(queryPart);
+  return { parts, query };
+}
+
+export function parseHash(hash: string): Route {
+  const { parts, query } = splitPathAndQuery(hash);
+  if (parts.length === 0) return { kind: 'roadmap' };
+
+  // Backward-compat redirects from the pre-Phase-1 route shapes.
+  if (parts[0] === 'workspace') {
+    if (parts[1] === 'cross-cutting') return { kind: 'roadmap' };
+    const tab: WorkspaceTab = isWorkspaceTab(parts[1]) ? parts[1] : 'overview';
+    return { kind: 'docs-project', tab };
+  }
+  if (parts[0] === 'scope' && parts[1]) {
+    if (parts[2] === 'layer' && parts[3]) {
+      const tab: LayerTab = isLayerTab(parts[4]) ? parts[4] : 'overview';
+      return { kind: 'docs-layer', scopeId: parts[1], layerId: parts[3], tab };
+    }
+    return { kind: 'roadmap', scope: parts[1] };
+  }
+
+  if (parts[0] === 'docs') {
+    if (parts.length === 1) return { kind: 'docs-project', tab: 'overview' };
+    if (parts[1] === 'scope' && parts[2]) {
+      if (parts[3] === 'layer' && parts[4]) {
+        const tab: LayerTab = isLayerTab(parts[5]) ? parts[5] : 'overview';
+        return { kind: 'docs-layer', scopeId: parts[2], layerId: parts[4], tab };
+      }
+      return { kind: 'docs-scope', scopeId: parts[2] };
+    }
+    const tab: WorkspaceTab = isWorkspaceTab(parts[1]) ? parts[1] : 'overview';
+    return { kind: 'docs-project', tab };
+  }
+  if (parts[0] === 'roadmap') {
+    const scope = query.get('scope') ?? undefined;
+    const layer = query.get('layer') ?? undefined;
+    return { kind: 'roadmap', scope, layer };
+  }
+  if (parts[0] === 'item' && parts[1]) return { kind: 'item', itemId: parts[1] };
+  if (parts[0] === 'health' && parts[1] && parts[2]) return { kind: 'health-layer', scopeId: parts[1], layerId: parts[2] };
+  if (parts[0] === 'health') return { kind: 'health' };
+  return { kind: 'unknown' };
+}
+
+export function formatRoute(r: Route): string {
+  switch (r.kind) {
+    case 'docs-project': return r.tab === 'overview' ? '#/docs' : `#/docs/${r.tab}`;
+    case 'docs-scope': return `#/docs/scope/${r.scopeId}`;
+    case 'docs-layer': return `#/docs/scope/${r.scopeId}/layer/${r.layerId}/${r.tab}`;
+    case 'roadmap': {
+      const params = new URLSearchParams();
+      if (r.scope) params.set('scope', r.scope);
+      if (r.layer) params.set('layer', r.layer);
+      const q = params.toString();
+      return q ? `#/roadmap?${q}` : '#/roadmap';
+    }
+    case 'item': return `#/item/${r.itemId}`;
+    case 'health': return '#/health';
+    case 'health-layer': return `#/health/${r.scopeId}/${r.layerId}`;
+    default: return '#/';
+  }
+}
+
+export function modeFromRoute(r: Route): Mode {
+  if (r.kind === 'roadmap') return 'roadmap';
+  if (r.kind === 'health' || r.kind === 'health-layer') return 'health';
+  return 'docs';
+}

package/src/router/useHashRoute.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { parseHash, formatRoute } from './routes.js';
+
+describe('parseHash', () => {
+  it('defaults to docs project overview on empty hash', () => {
+    expect(parseHash('')).toEqual({ kind: 'docs-project', tab: 'overview' });
+    expect(parseHash('#/')).toEqual({ kind: 'docs-project', tab: 'overview' });
+    expect(parseHash('#/docs')).toEqual({ kind: 'docs-project', tab: 'overview' });
+  });
+  it('parses docs project tab', () => {
+    expect(parseHash('#/docs/glossary')).toEqual({ kind: 'docs-project', tab: 'glossary' });
+  });
+  it('parses docs scope', () => {
+    expect(parseHash('#/docs/scope/editor')).toEqual({ kind: 'docs-scope', scopeId: 'editor' });
+  });
+  it('parses docs layer with default tab', () => {
+    expect(parseHash('#/docs/scope/editor/layer/foo')).toEqual({ kind: 'docs-layer', scopeId: 'editor', layerId: 'foo', tab: 'overview' });
+  });
+  it('parses docs layer with explicit tab', () => {
+    expect(parseHash('#/docs/scope/editor/layer/foo/purpose')).toEqual({ kind: 'docs-layer', scopeId: 'editor', layerId: 'foo', tab: 'purpose' });
+  });
+  it('parses roadmap with no filter', () => {
+    expect(parseHash('#/roadmap')).toEqual({ kind: 'roadmap', scope: undefined, layer: undefined });
+  });
+  it('parses roadmap with scope and layer filters', () => {
+    expect(parseHash('#/roadmap?scope=editor&layer=ai')).toEqual({ kind: 'roadmap', scope: 'editor', layer: 'ai' });
+  });
+  it('parses item', () => {
+    expect(parseHash('#/item/cmp-001')).toEqual({ kind: 'item', itemId: 'cmp-001' });
+  });
+  it('redirects legacy workspace tab to docs', () => {
+    expect(parseHash('#/workspace/principles')).toEqual({ kind: 'docs-project', tab: 'principles' });
+  });
+  it('redirects legacy workspace cross-cutting to roadmap', () => {
+    expect(parseHash('#/workspace/cross-cutting')).toEqual({ kind: 'roadmap' });
+  });
+  it('redirects legacy scope to roadmap with filter', () => {
+    expect(parseHash('#/scope/editor')).toEqual({ kind: 'roadmap', scope: 'editor' });
+  });
+  it('redirects legacy layer to docs-layer', () => {
+    expect(parseHash('#/scope/editor/layer/foo/purpose')).toEqual({ kind: 'docs-layer', scopeId: 'editor', layerId: 'foo', tab: 'purpose' });
+  });
+  it('parses /health/<scope>/<layer>', () => {
+    expect(parseHash('#/health/editor/visual-canvas')).toEqual({
+      kind: 'health-layer', scopeId: 'editor', layerId: 'visual-canvas',
+    });
+  });
+});
+
+describe('formatRoute', () => {
+  it('round-trips docs-layer', () => {
+    expect(formatRoute({ kind: 'docs-layer', scopeId: 'editor', layerId: 'foo', tab: 'purpose' })).toBe('#/docs/scope/editor/layer/foo/purpose');
+  });
+  it('formats roadmap with filters', () => {
+    expect(formatRoute({ kind: 'roadmap', scope: 'editor', layer: 'ai' })).toBe('#/roadmap?scope=editor&layer=ai');
+  });
+  it('formats roadmap without filters', () => {
+    expect(formatRoute({ kind: 'roadmap' })).toBe('#/roadmap');
+  });
+  it('formats docs-project default tab compactly', () => {
+    expect(formatRoute({ kind: 'docs-project', tab: 'overview' })).toBe('#/docs');
+    expect(formatRoute({ kind: 'docs-project', tab: 'glossary' })).toBe('#/docs/glossary');
+  });
+  it('formats health-layer', () => {
+    expect(formatRoute({ kind: 'health-layer', scopeId: 'editor', layerId: 'visual-canvas' })).toBe('#/health/editor/visual-canvas');
+  });
+});

package/src/router/useHashRoute.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState, useCallback } from 'react';
+import { parseHash, formatRoute, type Route } from './routes.js';
+
+export function useHashRoute(): { route: Route; navigate: (r: Route) => void } {
+  const [route, setRoute] = useState<Route>(() => parseHash(window.location.hash));
+  useEffect(() => {
+    const onHash = () => setRoute(parseHash(window.location.hash));
+    window.addEventListener('hashchange', onHash);
+    return () => window.removeEventListener('hashchange', onHash);
+  }, []);
+  const navigate = useCallback((r: Route) => {
+    window.location.hash = formatRoute(r);
+  }, []);
+  return { route, navigate };
+}