npm - tenbo-dashboard - Versions diffs - 0.1.0 - Mend

tenbo-dashboard 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (155) hide show

package/README.md +32 -0
package/bin/tenbo-dashboard.mjs +67 -0
package/index.html +12 -0
package/package.json +75 -0
package/scripts/compute-metrics.test.ts +35 -0
package/scripts/compute-metrics.ts +46 -0
package/scripts/next-id.test.ts +128 -0
package/scripts/next-id.ts +183 -0
package/scripts/validate-cli.test.ts +152 -0
package/scripts/validate-cli.ts +181 -0
package/src/App.tsx +152 -0
package/src/ErrorBoundary.tsx +25 -0
package/src/api/client.ts +41 -0
package/src/api/lib/frontmatterScan.ts +37 -0
package/src/api/lib/health/agingTodos.test.ts +32 -0
package/src/api/lib/health/agingTodos.ts +97 -0
package/src/api/lib/health/archCompliance.test.ts +26 -0
package/src/api/lib/health/archCompliance.ts +53 -0
package/src/api/lib/health/collectAll.test.ts +49 -0
package/src/api/lib/health/collectAll.ts +78 -0
package/src/api/lib/health/config.test.ts +45 -0
package/src/api/lib/health/config.ts +54 -0
package/src/api/lib/health/coupling.test.ts +40 -0
package/src/api/lib/health/coupling.ts +66 -0
package/src/api/lib/health/deadCode.test.ts +23 -0
package/src/api/lib/health/deadCode.ts +76 -0
package/src/api/lib/health/docDrift.test.ts +54 -0
package/src/api/lib/health/docDrift.ts +99 -0
package/src/api/lib/health/hotspotFiles.test.ts +49 -0
package/src/api/lib/health/hotspotFiles.ts +70 -0
package/src/api/lib/health/importGraph.test.ts +29 -0
package/src/api/lib/health/importGraph.ts +51 -0
package/src/api/lib/health/layerFiles.test.ts +46 -0
package/src/api/lib/health/layerFiles.ts +40 -0
package/src/api/lib/health/redundancy.test.ts +24 -0
package/src/api/lib/health/redundancy.ts +162 -0
package/src/api/lib/health/testCoverage.test.ts +33 -0
package/src/api/lib/health/testCoverage.ts +55 -0
package/src/api/lib/health/types.test.ts +29 -0
package/src/api/lib/health/types.ts +85 -0
package/src/api/lib/http.ts +34 -0
package/src/api/lib/metrics.test.ts +81 -0
package/src/api/lib/metrics.ts +78 -0
package/src/api/lib/metricsRefresh.test.ts +54 -0
package/src/api/lib/metricsRefresh.ts +147 -0
package/src/api/lib/phases.test.ts +76 -0
package/src/api/lib/phases.ts +48 -0
package/src/api/lib/relationships.ts +65 -0
package/src/api/lib/repoRoot.ts +12 -0
package/src/api/lib/tenboFs.layerContent.test.ts +36 -0
package/src/api/lib/tenboFs.ts +237 -0
package/src/api/lib/tenboFs.v2.test.ts +86 -0
package/src/api/lib/tenboFs.workspaceContent.test.ts +42 -0
package/src/api/lib/validator.docUpdate.test.ts +99 -0
package/src/api/lib/validator.phases.test.ts +98 -0
package/src/api/lib/validator.relationships.test.ts +126 -0
package/src/api/lib/validator.specLinks.test.ts +96 -0
package/src/api/lib/validator.ts +311 -0
package/src/api/lib/validator.v2.test.ts +55 -0
package/src/api/lib/yamlOrdered.ts +60 -0
package/src/api/plugin.ts +31 -0
package/src/api/routes/items.ts +25 -0
package/src/api/routes/layerContent.ts +22 -0
package/src/api/routes/layerDocs.ts +22 -0
package/src/api/routes/open.ts +18 -0
package/src/api/routes/related.ts +11 -0
package/src/api/routes/reorder.ts +15 -0
package/src/api/routes/state.ts +23 -0
package/src/api/routes/watch.ts +31 -0
package/src/css-modules.d.ts +4 -0
package/src/hooks/useApiPatch.ts +9 -0
package/src/hooks/useLayerContent.ts +25 -0
package/src/hooks/usePrompt.ts +23 -0
package/src/hooks/useTenboState.ts +35 -0
package/src/main.tsx +13 -0
package/src/prompts/populateLayer.ts +12 -0
package/src/router/routes.ts +98 -0
package/src/router/useHashRoute.test.ts +67 -0
package/src/router/useHashRoute.ts +15 -0
package/src/styles.css +228 -0
package/src/test-setup.ts +1 -0
package/src/types.ts +202 -0
package/src/ui/DotGrid.module.css +7 -0
package/src/ui/DotGrid.tsx +87 -0
package/src/ui/EmptyState.module.css +11 -0
package/src/ui/EmptyState.tsx +10 -0
package/src/ui/FindingModal/EvidenceSection.tsx +51 -0
package/src/ui/FindingModal/FindingModal.module.css +31 -0
package/src/ui/FindingModal/FindingModal.test.tsx +36 -0
package/src/ui/FindingModal/HeadlineSection.tsx +17 -0
package/src/ui/FindingModal/RelatedFindingsSection.tsx +29 -0
package/src/ui/FindingModal/SuggestionSection.tsx +13 -0
package/src/ui/FindingModal/index.tsx +36 -0
package/src/ui/HealthPage/Digest.tsx +29 -0
package/src/ui/HealthPage/FindingRow.tsx +21 -0
package/src/ui/HealthPage/HealthPage.module.css +45 -0
package/src/ui/HealthPage/HealthPage.test.tsx +49 -0
package/src/ui/HealthPage/HealthPage.tsx +66 -0
package/src/ui/HealthPage/LayerCard.tsx +36 -0
package/src/ui/HealthPage/SeverityIcon.tsx +29 -0
package/src/ui/HealthPage/SeverityLegend.tsx +27 -0
package/src/ui/HealthPage/severity.test.ts +46 -0
package/src/ui/HealthPage/severity.ts +21 -0
package/src/ui/ItemCard.module.css +131 -0
package/src/ui/ItemCard.tsx +117 -0
package/src/ui/ItemModal/DescriptionField.tsx +22 -0
package/src/ui/ItemModal/EnrichmentSections.tsx +49 -0
package/src/ui/ItemModal/ItemModal.module.css +200 -0
package/src/ui/ItemModal/LinksSection.tsx +26 -0
package/src/ui/ItemModal/NotesSection.tsx +18 -0
package/src/ui/ItemModal/PhasesSection.tsx +79 -0
package/src/ui/ItemModal/RelatedSection.tsx +26 -0
package/src/ui/ItemModal/RelationshipsSection.tsx +69 -0
package/src/ui/ItemModal/StatusLayerControls.tsx +43 -0
package/src/ui/ItemModal/TitleField.tsx +21 -0
package/src/ui/ItemModal/index.tsx +117 -0
package/src/ui/KanbanColumn.module.css +20 -0
package/src/ui/KanbanColumn.tsx +36 -0
package/src/ui/LayerDetailPage/LayerDetailPage.module.css +11 -0
package/src/ui/LayerDetailPage/LayerDetailPage.test.tsx +30 -0
package/src/ui/LayerDetailPage/LayerDetailPage.tsx +59 -0
package/src/ui/LayerDetailPage/SignalSection.tsx +33 -0
package/src/ui/LayerDrawer.module.css +60 -0
package/src/ui/LayerDrawer.tsx +69 -0
package/src/ui/LayerKanban.module.css +45 -0
package/src/ui/LayerKanban.tsx +65 -0
package/src/ui/LayerPage/FillThisInButton.tsx +11 -0
package/src/ui/LayerPage/LayerPage.module.css +52 -0
package/src/ui/LayerPage/LayerPage.tsx +76 -0
package/src/ui/LayerPage/MetricsBadges.tsx +18 -0
package/src/ui/LayerPage/isTemplateOnly.test.ts +45 -0
package/src/ui/LayerPage/isTemplateOnly.ts +19 -0
package/src/ui/LayerPage/tabs/CodeMapTab.tsx +19 -0
package/src/ui/LayerPage/tabs/DeepDivesTab.tsx +35 -0
package/src/ui/LayerPage/tabs/IntentTab.tsx +19 -0
package/src/ui/LayerPage/tabs/PlainEnglishTab.tsx +19 -0
package/src/ui/Markdown.module.css +115 -0
package/src/ui/Markdown.tsx +27 -0
package/src/ui/RoadmapPage/RoadmapPage.module.css +93 -0
package/src/ui/RoadmapPage/RoadmapPage.tsx +255 -0
package/src/ui/ScopePage/ScopePage.module.css +72 -0
package/src/ui/ScopePage/ScopePage.tsx +131 -0
package/src/ui/SummaryStrip.module.css +18 -0
package/src/ui/SummaryStrip.tsx +16 -0
package/src/ui/TaskList.module.css +136 -0
package/src/ui/TaskList.tsx +91 -0
package/src/ui/TopBar.module.css +78 -0
package/src/ui/TopBar.tsx +48 -0
package/src/ui/WorkspacePage/WorkspacePage.module.css +24 -0
package/src/ui/WorkspacePage/WorkspacePage.tsx +36 -0
package/src/ui/WorkspacePage/tabs/GlossaryTab.tsx +6 -0
package/src/ui/WorkspacePage/tabs/OverviewTab.tsx +28 -0
package/src/ui/WorkspacePage/tabs/PrinciplesTab.tsx +6 -0
package/tsconfig.json +18 -0
package/vite.config.ts +9 -0

package/README.md ADDED Viewed

@@ -0,0 +1,32 @@
+# tenbo-dashboard
+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
+# Run in any project with a .tenbo/ directory
+npx tenbo-dashboard
+```
+Opens a local dashboard for browsing roadmaps, triaging items, and drag-reorder.
+## CLI tools
+```bash
+npx tenbo-dashboard validate          # Run validation rules
+npx tenbo-dashboard next-id <prefix>  # Allocate next roadmap item ID
+npx tenbo-dashboard metrics --all     # Compute scope metrics
+```
+## 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.
+Install the skill: [github.com/poyi/tenbo](https://github.com/poyi/tenbo)
+## License
+MIT

package/bin/tenbo-dashboard.mjs ADDED Viewed

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const [command, ...args] = process.argv.slice(2);
+const commands = {
+  validate: 'scripts/validate-cli.ts',
+  'next-id': 'scripts/next-id.ts',
+  metrics: 'scripts/compute-metrics.ts',
+};
+function run(script, scriptArgs) {
+  const tsx = path.join(root, 'node_modules', '.bin', 'tsx');
+  const child = spawn(tsx, [path.join(root, script), ...scriptArgs], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+  child.on('close', (code) => process.exit(code ?? 1));
+}
+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], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    env: { ...process.env, TENBO_CWD: process.cwd() },
+  });
+  child.on('close', (code) => process.exit(code ?? 0));
+}
+if (!command || 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 validate         Run validation rules
+  tenbo-dashboard next-id <prefix> Allocate next roadmap item ID
+  tenbo-dashboard metrics --all    Compute scope metrics
+  tenbo-dashboard help             Show this help
+`);
+  process.exit(0);
+}
+if (commands[command]) {
+  run(commands[command], args);
+} else {
+  // No recognized subcommand — default to launching the dashboard
+  // Pass the original command back as an arg in case it was a flag
+  startDashboard();
+}

package/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>tenbo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,75 @@
+{
+  "name": "tenbo-dashboard",
+  "version": "0.1.0",
+  "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
+  "type": "module",
+  "license": "MIT",
+  "author": "Po-Yi Chen",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/poyi/tenbo.git",
+    "directory": "tenbo-dashboard"
+  },
+  "homepage": "https://github.com/poyi/tenbo#readme",
+  "keywords": [
+    "tenbo",
+    "architecture",
+    "roadmap",
+    "developer-tools",
+    "project-management",
+    "ai-skills"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "tenbo-dashboard": "./bin/tenbo-dashboard.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "test": "vitest",
+    "validate": "tsx scripts/validate-cli.ts",
+    "next-id": "tsx scripts/next-id.ts",
+    "compute-metrics": "tsx scripts/compute-metrics.ts"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^8.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@xyflow/react": "^12.10.2",
+    "chokidar": "^3.6.0",
+    "dagre": "^0.8.5",
+    "gray-matter": "^4.0.3",
+    "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",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.3"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.0.1",
+    "@types/dagre": "^0.7.54",
+    "@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/compute-metrics.test.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runComputeMetrics } from './compute-metrics.js';
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-cm-'));
+  const scope = path.join(dir, '.tenbo', 'scopes', 'editor');
+  const layer = path.join(scope, 'layers', 'foo');
+  mkdirSync(layer, { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo', 'workspace.yaml'), 'scopes:\n  - id: editor\n    path: scopes/editor\n');
+  writeFileSync(path.join(scope, 'architecture.yaml'), 'scope: editor\nlayers:\n  - id: foo\n    name: Foo\n    description: A small layer.\n    files: ["src/**"]\n    dependencies: { inbound: [], outbound: [], external: [] }\n');
+  writeFileSync(path.join(scope, 'roadmap.yaml'), 'items: []\n');
+  writeFileSync(path.join(layer, 'intent.md'), '# Foo\n');
+  writeFileSync(path.join(layer, 'code-map.md'), '# Foo\n');
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+describe('compute-metrics CLI', () => {
+  it('writes metrics.json for the requested scope', async () => {
+    const code = await runComputeMetrics({ repoRoot: dir, scope: 'editor' });
+    expect(code).toBe(0);
+    expect(existsSync(path.join(dir, '.tenbo', 'scopes', 'editor', 'metrics.json'))).toBe(true);
+  });
+  it('writes metrics for all scopes with --all', async () => {
+    const code = await runComputeMetrics({ repoRoot: dir, all: true });
+    expect(code).toBe(0);
+    expect(existsSync(path.join(dir, '.tenbo', 'scopes', 'editor', 'metrics.json'))).toBe(true);
+  });
+});

package/scripts/compute-metrics.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import { ensureFresh } from '../src/api/lib/metricsRefresh.js';
+import { readState } from '../src/api/lib/tenboFs.js';
+import { findRepoRoot } from '../src/api/lib/repoRoot.js';
+export interface RunArgs {
+  repoRoot: string;
+  scope?: string;
+  all?: boolean;
+}
+export async function runComputeMetrics(args: RunArgs): Promise<number> {
+  const { repoRoot } = args;
+  const state = readState(repoRoot);
+  const scopes = args.all
+    ? state.scopes.map((s) => s.id)
+    : args.scope
+      ? [args.scope]
+      : [];
+  if (scopes.length === 0) {
+    console.error('compute-metrics: pass --all or --scope <id>');
+    return 2;
+  }
+  for (const id of scopes) {
+    try {
+      await ensureFresh(repoRoot, id, { force: true });
+      console.log(`compute-metrics: wrote metrics for ${id}`);
+    } catch (e) {
+      console.error(`compute-metrics: failed for ${id}:`, e);
+      return 1;
+    }
+  }
+  return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const all = args.includes('--all');
+  const scopeIdx = args.indexOf('--scope');
+  const scope = scopeIdx >= 0 ? args[scopeIdx + 1] : undefined;
+  const repoRoot = findRepoRoot(process.cwd());
+  if (!repoRoot) {
+    console.error('compute-metrics: unable to find repo root');
+    process.exit(1);
+  }
+  runComputeMetrics({ repoRoot, scope, all }).then((code) => process.exit(code));
+}

package/scripts/next-id.test.ts ADDED Viewed

@@ -0,0 +1,128 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readdirSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { allocateNextId, STALE_LOCK_MS } from './next-id';
+// Resolve repo paths from cwd — Vitest's `import.meta.url` is not a `file:` URL
+// under jsdom. Vitest runs from the package root, so cwd === tenbo-dashboard.
+const APP_ROOT = process.cwd();
+const SCRIPT_PATH = path.join(APP_ROOT, 'scripts', 'next-id.ts');
+const TSX_BIN = path.join(APP_ROOT, 'node_modules', '.bin', 'tsx');
+const created: string[] = [];
+afterEach(() => {
+  while (created.length) {
+    const root = created.pop();
+    if (root) rmSync(root, { recursive: true, force: true });
+  }
+});
+function makeRoot(): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'tenbo-nextid-'));
+  created.push(root);
+  // .git marker so findRepoRoot treats this as a repo (not strictly needed since
+  // tests pass repoRoot directly, but harmless).
+  mkdirSync(path.join(root, '.git'), { recursive: true });
+  mkdirSync(path.join(root, '.tenbo', 'scopes', 'editor'), { recursive: true });
+  writeFileSync(
+    path.join(root, '.tenbo', 'workspace.yaml'),
+    'scopes:\n  - id: editor\n    prefix: ed\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n',
+  );
+  return root;
+}
+function writeRoadmap(root: string, scopeRel: string, ids: string[]): void {
+  const items = ids.length ? ids.map((id) => `  - id: ${id}\n    title: t\n`).join('') : '';
+  const body = `items:\n${items}`;
+  writeFileSync(path.join(root, '.tenbo', scopeRel, 'roadmap.yaml'), body);
+}
+describe('next-id allocator', () => {
+  it('returns prefix-001 for an empty roadmap', () => {
+    const root = makeRoot();
+    writeRoadmap(root, 'scopes/editor', []);
+    expect(allocateNextId({ repoRoot: root, prefix: 'ed' })).toBe('ed-001');
+  });
+  it('returns ed-059 when ed-001..ed-058 exist', () => {
+    const root = makeRoot();
+    const ids = Array.from({ length: 58 }, (_, i) => `ed-${String(i + 1).padStart(3, '0')}`);
+    writeRoadmap(root, 'scopes/editor', ids);
+    expect(allocateNextId({ repoRoot: root, prefix: 'ed' })).toBe('ed-059');
+  });
+  it('returns x-002 when only x-001 exists in workspace roadmap', () => {
+    const root = makeRoot();
+    writeFileSync(path.join(root, '.tenbo', 'roadmap.yaml'), 'items:\n  - id: x-001\n    title: t\n');
+    expect(allocateNextId({ repoRoot: root, prefix: 'x' })).toBe('x-002');
+  });
+  it('reclaims stale lock files older than 60s', () => {
+    const root = makeRoot();
+    writeRoadmap(root, 'scopes/editor', []);
+    // Pre-create a stale lock for ed-001.
+    const lockDir = path.join(root, '.tenbo', '.id-locks');
+    mkdirSync(lockDir, { recursive: true });
+    const lockPath = path.join(lockDir, 'ed-001.lock');
+    writeFileSync(lockPath, JSON.stringify({ pid: 99999, ts: '2020-01-01T00:00:00Z' }));
+    const ancient = (Date.now() - STALE_LOCK_MS - 5_000) / 1000;
+    utimesSync(lockPath, ancient, ancient);
+    const id = allocateNextId({ repoRoot: root, prefix: 'ed' });
+    // Stale lock reclaimed → ed-001 returned.
+    expect(id).toBe('ed-001');
+  });
+  it('skips past fresh locks (simulated concurrent allocation)', () => {
+    const root = makeRoot();
+    writeRoadmap(root, 'scopes/editor', []);
+    // Simulate another caller having just claimed ed-001 by creating a fresh lock.
+    const id1 = allocateNextId({ repoRoot: root, prefix: 'ed' });
+    expect(id1).toBe('ed-001');
+    const id2 = allocateNextId({ repoRoot: root, prefix: 'ed' });
+    expect(id2).toBe('ed-002');
+    const id3 = allocateNextId({ repoRoot: root, prefix: 'ed' });
+    expect(id3).toBe('ed-003');
+    // Lock files for each should now exist.
+    const locks = readdirSync(path.join(root, '.tenbo', '.id-locks')).sort();
+    expect(locks).toEqual(['ed-001.lock', 'ed-002.lock', 'ed-003.lock']);
+  });
+  it('concurrent child processes never return the same id', () => {
+    const root = makeRoot();
+    writeRoadmap(root, 'scopes/editor', []);
+    // Fan out N parallel child processes that all try to allocate `ed`.
+    const N = 5;
+    const procs = Array.from({ length: N }, () =>
+      spawnSync(TSX_BIN, [SCRIPT_PATH, 'ed'], {
+        cwd: root,
+        encoding: 'utf8',
+      }),
+    );
+    const ids = procs.map((p) => {
+      expect(p.status, `stderr: ${p.stderr}`).toBe(0);
+      return p.stdout.trim();
+    });
+    const unique = new Set(ids);
+    expect(unique.size).toBe(N);
+    // All should match the ed-NNN pattern.
+    for (const id of ids) expect(id).toMatch(/^ed-\d{3}$/);
+  });
+  it('returns no-op gracefully when prefix has no roadmap', () => {
+    const root = makeRoot();
+    // No roadmap file at all → empty existing → starts at 001.
+    expect(allocateNextId({ repoRoot: root, prefix: 'ed' })).toBe('ed-001');
+  });
+});
+// Sanity: confirm the module exports the constant tests rely on.
+describe('exports', () => {
+  it('exports STALE_LOCK_MS = 60000', () => {
+    expect(STALE_LOCK_MS).toBe(60_000);
+  });
+});

package/scripts/next-id.ts ADDED Viewed

@@ -0,0 +1,183 @@
+/**
+ * next-id.ts — Atomic id allocator for tenbo roadmap items.
+ *
+ * Purpose:
+ *   Read the relevant `roadmap.yaml` files for a given scope prefix, find the
+ *   maximum three-digit suffix already in use, and return the next id, while
+ *   atomically reserving it via a short-lived lock file. Two parallel callers
+ *   must never get the same id.
+ *
+ * Usage:
+ *   npx tenbo-dashboard next-id <prefix>
+ *   # e.g. npx tenbo-dashboard next-id ed   →  ed-059
+ *   # e.g. npx tenbo-dashboard next-id x    →  x-002
+ *
+ * When to use:
+ *   Any tenbo skill behavior that needs to allocate a new roadmap-item id
+ *   (Behaviors B2, B12, B13). Replaces ad-hoc grep+sort logic and removes the
+ *   id-collision class of error.
+ *
+ * Lock-file convention:
+ *   Locks live at `.tenbo/.id-locks/<prefix>-<NNN>.lock`. Each lock contains
+ *   the allocating process's PID and a UTC timestamp. Locks older than 60s
+ *   are considered stale and reclaimable. The directory is git-ignored.
+ *
+ * Output:
+ *   On success, prints the allocated id (e.g. `ed-059`) to stdout with no
+ *   decoration so callers can capture it via `$(...)`. Errors go to stderr
+ *   and the process exits non-zero.
+ */
+import { readFileSync, existsSync, mkdirSync, readdirSync, writeFileSync, statSync, unlinkSync, openSync, closeSync, writeSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+export const STALE_LOCK_MS = 60_000;
+const MAX_ATTEMPTS = 1000;
+interface WorkspaceScope {
+  id: string;
+  prefix?: string;
+  path?: string;
+}
+interface RoadmapFile {
+  items?: Array<{ id?: string }>;
+}
+/** Find which roadmap.yaml files contain ids for this prefix. */
+export function resolveRoadmapPaths(repoRoot: string, prefix: string): string[] {
+  const tenbo = path.join(repoRoot, '.tenbo');
+  if (prefix === 'x') {
+    const p = path.join(tenbo, 'roadmap.yaml');
+    return existsSync(p) ? [p] : [];
+  }
+  const wsPath = path.join(tenbo, 'workspace.yaml');
+  if (!existsSync(wsPath)) return [];
+  const ws = parseYaml(readFileSync(wsPath, 'utf8')) as { scopes?: WorkspaceScope[] } | null;
+  const scopes = ws?.scopes ?? [];
+  const match = scopes.find((s) => s.prefix === prefix);
+  if (!match) return [];
+  const p = path.join(tenbo, 'scopes', match.id, 'roadmap.yaml');
+  return existsSync(p) ? [p] : [];
+}
+/** Collect numeric suffixes for `<prefix>-NNN` ids across the given roadmap files. */
+export function collectExistingNumbers(roadmapPaths: string[], prefix: string): number[] {
+  const re = new RegExp(`^${prefix}-(\\d{3})$`);
+  const nums: number[] = [];
+  for (const p of roadmapPaths) {
+    const text = readFileSync(p, 'utf8');
+    // Use a forgiving regex scan rather than full YAML parse — some roadmaps
+    // contain unrelated YAML errors that block parsing but leave the `id:`
+    // lines intact.
+    const idLines = text.match(/^\s*-?\s*id:\s*[^\s#]+/gm) ?? [];
+    for (const line of idLines) {
+      const m = line.match(/id:\s*([^\s#]+)/);
+      if (!m) continue;
+      const id = m[1].replace(/['"]/g, '');
+      const mm = id.match(re);
+      if (mm) nums.push(Number(mm[1]));
+    }
+  }
+  return nums;
+}
+function lockDir(repoRoot: string): string {
+  return path.join(repoRoot, '.tenbo', '.id-locks');
+}
+function lockPath(repoRoot: string, id: string): string {
+  return path.join(lockDir(repoRoot), `${id}.lock`);
+}
+/** Returns true if a usable lock for `id` exists; cleans stale locks as a side effect. */
+function lockIsActive(repoRoot: string, id: string, now: number): boolean {
+  const p = lockPath(repoRoot, id);
+  if (!existsSync(p)) return false;
+  try {
+    const st = statSync(p);
+    if (now - st.mtimeMs > STALE_LOCK_MS) {
+      try { unlinkSync(p); } catch { /* race; treat as gone */ }
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+/** Attempt to atomically create a lock file. Returns true on success. */
+function tryAcquireLock(repoRoot: string, id: string): boolean {
+  const dir = lockDir(repoRoot);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const p = lockPath(repoRoot, id);
+  try {
+    // 'wx' = exclusive create. Two parallel processes cannot both succeed.
+    const fd = openSync(p, 'wx');
+    const payload = JSON.stringify({ pid: process.pid, ts: new Date().toISOString() });
+    writeSync(fd, payload);
+    closeSync(fd);
+    return true;
+  } catch (e: unknown) {
+    const code = (e as NodeJS.ErrnoException)?.code;
+    if (code === 'EEXIST') return false;
+    throw e;
+  }
+}
+export interface AllocateOptions {
+  repoRoot: string;
+  prefix: string;
+  /** For tests: clock injection. */
+  now?: () => number;
+}
+export function allocateNextId(opts: AllocateOptions): string {
+  const { repoRoot, prefix } = opts;
+  const now = opts.now ?? Date.now;
+  const paths = resolveRoadmapPaths(repoRoot, prefix);
+  const existing = collectExistingNumbers(paths, prefix);
+  const startFrom = existing.length ? Math.max(...existing) + 1 : 1;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const n = startFrom + attempt;
+    const id = `${prefix}-${String(n).padStart(3, '0')}`;
+    // If a fresh lock already exists for this id, skip past it.
+    if (lockIsActive(repoRoot, id, now())) continue;
+    if (tryAcquireLock(repoRoot, id)) return id;
+    // Lost the race — another caller just grabbed this id. Try the next.
+  }
+  throw new Error(`next-id: could not allocate after ${MAX_ATTEMPTS} attempts for prefix "${prefix}"`);
+}
+function isMain(): boolean {
+  // Compare resolved path to argv[1]. Works under tsx.
+  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 prefix = process.argv[2];
+  if (!prefix) {
+    console.error('Usage: next-id <prefix>  (e.g. next-id ed)');
+    process.exit(2);
+  }
+  try {
+    const cwd = process.cwd();
+    const repoRoot = findRepoRoot(cwd) ?? path.resolve(cwd, '..', '..');
+    const id = allocateNextId({ repoRoot, prefix });
+    process.stdout.write(id + '\n');
+    process.exit(0);
+  } catch (e) {
+    console.error(`next-id: ${(e as Error).message}`);
+    process.exit(1);
+  }
+}