tenbo-dashboard 0.8.0 → 0.10.0

package/README.md

@@ -38,6 +38,14 @@ Surfaces the things that would otherwise become tech debt nobody mentions: overs
 The same package ships commands the skill uses behind the scenes — also runnable directly:
 
 ```bash
+npx tenbo-dashboard item show sk-030 --json
+npx tenbo-dashboard item set-status sk-030 done
+npx tenbo-dashboard item add-note sk-030 "Implemented; live verification pending"
+npx tenbo-dashboard item verify sk-030 --status pending_live --evidence "npm test -- --run"
+npx tenbo-dashboard item link-commit sk-030 7fc09a5
+npx tenbo-dashboard items --status done --verification pending_live --json
+npx tenbo-dashboard next --json
+npx tenbo-dashboard context feature --query "help me build X" --json
 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
@@ -45,6 +53,12 @@ npx tenbo-dashboard next-id <prefix>  # Allocate next roadmap item ID
 npx tenbo-dashboard --version         # Print the installed version
 ```
 
+Installed packages also expose a shorter `tenbo` binary alias for the same commands.
+
+`context feature` is the agent-facing read path. It returns likely scope/layers,
+matching roadmap items, active work, goal refs, recommended files, and freshness warnings
+as one JSON payload so agents do not have to re-read every roadmap file by hand.
+
 ## What is tenbo?
 
 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.

package/bin/tenbo-dashboard.mjs

@@ -41,6 +41,13 @@ const commands = {
   'init-check': 'scripts/init-check.ts',
   sync: 'scripts/sync.ts',
   archive: 'scripts/archive.ts',
+  'commit-ready': 'scripts/commit-ready.ts',
+  item: 'scripts/item.ts',
+  items: 'scripts/items.ts',
+  list: 'scripts/items.ts',
+  next: 'scripts/next.ts',
+  'work-queue': 'scripts/work-queue.ts',
+  context: 'scripts/context.ts',
   hook: 'scripts/hook.ts',
 };
 
@@ -78,6 +85,22 @@ Usage:
   tenbo-dashboard                  Launch the dashboard (http://localhost:5174)
   tenbo-dashboard serve            Same as bare invocation (also: 'start', 'dev')
   tenbo-dashboard sync             Refresh tenbo state after a change (metrics + init-check + validate, surfaces new findings)
+  tenbo-dashboard item show <id> [--json]
+  tenbo-dashboard item set-status <id> <now|next|later|done|dropped> [--json]
+  tenbo-dashboard item add-note <id> "<note>" [--json]
+  tenbo-dashboard item verify <id> --status <not_required|pending_live|verified|failed>
+                                   [--evidence "<text>"] [--note "<text>"] [--json]
+  tenbo-dashboard item link-commit <id> <sha> [--json]
+  tenbo-dashboard items            Query roadmap items [--status <status>]
+                                   [--verification <status>] [--goal <goal>]
+                                   [--type <type>] [--priority <p0|p1|p2|p3>]
+                                   [--layer <id>] [--fields <a,b>] [--summary] [--json]
+  tenbo-dashboard list             Alias for items
+  tenbo-dashboard next             Show next actionable roadmap items [--json]
+  tenbo-dashboard work-queue       Compact agent task flow [--status <a,b>]
+                                   [--type <type>] [--json]
+  tenbo-dashboard context feature  Fetch agent planning context for a natural-language request
+                                   --query "<request>" [--json]
   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
@@ -87,6 +110,8 @@ Usage:
   tenbo-dashboard hook install     Install opt-in pre-commit validation hook
                                    [--dry-run] [--force]
   tenbo-dashboard hook uninstall   Remove the tenbo pre-commit hook (idempotent)
+  tenbo-dashboard commit-ready     Report branch, diff, validation, and staging gates
+                                   without committing [--json]
   tenbo-dashboard --version        Print package version
   tenbo-dashboard help             Show this help
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,8 @@
     "node": ">=18"
   },
   "bin": {
-    "tenbo-dashboard": "./bin/tenbo-dashboard.mjs"
+    "tenbo-dashboard": "./bin/tenbo-dashboard.mjs",
+    "tenbo": "./bin/tenbo-dashboard.mjs"
   },
   "files": [
     "bin/",

package/scripts/bin-output.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-bin-output-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/editor/layers/app'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), 'scopes:\n  - id: editor\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/architecture.yaml'), 'layers:\n  - id: app\n    name: App\n    description: application layer\n    files: ["src/**"]\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/layers/app/README.md'), '# App\n');
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), '# Overview\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+    'items:',
+    '  - id: ed-001',
+    '    title: Large Output',
+    '    layer: app',
+    '    status: done',
+    '    description: item with a large field',
+    '    risks:',
+    `      - ${'x'.repeat(12_000)}`,
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('bin output', () => {
+  it('flushes large JSON output before exiting', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'items', '--status', 'done', '--json'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload.items[0].item.risks[0]).toHaveLength(12_000);
+  });
+
+  it('supports list as an alias for items', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'list', '--status', 'done', '--fields', 'id,title,status', '--json'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).items).toEqual([
+      { id: 'ed-001', title: 'Large Output', status: 'done' },
+    ]);
+  });
+});

package/scripts/cliArgs.ts

@@ -0,0 +1,30 @@
+export function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+export function readOption(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i === -1) return undefined;
+  return args[i + 1];
+}
+
+export function readRepeated(args: string[], flag: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === flag && args[i + 1]) out.push(args[i + 1]);
+  }
+  return out;
+}
+
+export function positionalArgs(args: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      if (args[i + 1] && !args[i + 1].startsWith('--')) i++;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}

package/scripts/cliResult.ts

@@ -0,0 +1,59 @@
+import { findRepoRoot } from '../src/api/lib/repoRoot';
+import { isRoadmapStoreError } from '../src/api/lib/roadmapStore';
+
+export interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export function ok(stdout: string): CliResult {
+  return { stdout, stderr: '', exitCode: 0 };
+}
+
+export function fail(error: string, message: string, json: boolean, retryable = false, exitCode = 1): CliResult {
+  if (json) {
+    return {
+      stdout: '',
+      stderr: `${JSON.stringify({ ok: false, error, message, retryable })}\n`,
+      exitCode,
+    };
+  }
+  return { stdout: '', stderr: `${message}\n`, exitCode };
+}
+
+export function misuse(message: string, json: boolean): CliResult {
+  return fail('invalid_args', message, json, false, 2);
+}
+
+export function serialize(payload: unknown, json: boolean, text: string): CliResult {
+  return ok(json ? `${JSON.stringify(payload, null, 2)}\n` : text);
+}
+
+export function handleCliError(err: unknown, json: boolean): CliResult {
+  if (isRoadmapStoreError(err)) {
+    return fail(err.code, err.message, json, err.retryable);
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return fail('error', message, json);
+}
+
+export function repoRootFromCwd(cwd = process.cwd()): string {
+  return findRepoRoot(cwd) ?? cwd;
+}
+
+export function runMain(result: CliResult): void {
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.exitCode;
+}
+
+export function isMain(importMetaUrl: string): boolean {
+  try {
+    const invoked = process.argv[1] ? new URL(`file://${process.argv[1]}`).pathname : '';
+    const here = new URL(importMetaUrl).pathname;
+    return invoked === here;
+  } catch {
+    return false;
+  }
+}

package/scripts/commit-ready.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runCommitReadyCli } from './commit-ready';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-commit-ready-cli-'));
+  spawnSync('git', ['init', '-q'], { cwd: dir });
+  spawnSync('git', ['checkout', '-q', '-b', 'main'], { cwd: dir });
+  mkdirSync(path.join(dir, '.tenbo/scopes/editor/layers/app'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), 'scopes:\n  - id: editor\n    path: apps/editor\n    description: editor scope\ncross_cutting: []\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/architecture.yaml'), 'layers:\n  - id: app\n    name: App\n    description: application layer\n    files: ["src/**"]\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/layers/app/README.md'), '# App\n');
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), '# Overview\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+    'items:',
+    '  - id: ed-001',
+    '    title: First',
+    '    layer: app',
+    '    status: next',
+    '    description: first item',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('commit-ready CLI', () => {
+  it('reports branch, dirty files, diff check, and validation without committing', () => {
+    const result = runCommitReadyCli(dir, ['--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      branch: expect.objectContaining({ current: 'main' }),
+      diff_check: expect.objectContaining({ exitCode: 0 }),
+      validation: expect.objectContaining({ errors: 0 }),
+    });
+    expect(payload.dirty_files.length).toBeGreaterThan(0);
+    expect(payload.recommended_gates).toContain('git diff --check');
+  });
+});

package/scripts/commit-ready.ts

@@ -0,0 +1,69 @@
+import { spawnSync } from 'node:child_process';
+import { readState } from '../src/api/lib/tenboFs';
+import { validate } from '../src/api/lib/validator';
+import { hasFlag } from './cliArgs';
+import { handleCliError, isMain, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+function runGit(repoRoot: string, args: string[]) {
+  const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function parseStatus(stdout: string): { current: string | null; upstream?: string; dirtyFiles: string[] } {
+  const lines = stdout.split(/\r?\n/).filter(Boolean);
+  const header = lines[0] ?? '';
+  const unbornMatch = header.match(/^## No commits yet on (.+)$/);
+  if (unbornMatch) {
+    return {
+      current: unbornMatch[1],
+      dirtyFiles: lines.slice(1),
+    };
+  }
+  const branchMatch = header.match(/^## ([^.\s]+)(?:\.\.\.([^\s]+))?/);
+  return {
+    current: branchMatch?.[1] ?? null,
+    ...(branchMatch?.[2] ? { upstream: branchMatch[2] } : {}),
+    dirtyFiles: lines.slice(1),
+  };
+}
+
+export function runCommitReadyCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  try {
+    const status = runGit(repoRoot, ['status', '--short', '--branch']);
+    const parsed = parseStatus(status.stdout);
+    const diffCheck = runGit(repoRoot, ['diff', '--check']);
+    const staged = runGit(repoRoot, ['diff', '--cached', '--name-only']);
+    const validation = validate(readState(repoRoot));
+    const payload = {
+      ok: true,
+      branch: {
+        current: parsed.current,
+        upstream: parsed.upstream ?? null,
+      },
+      dirty_files: parsed.dirtyFiles,
+      staged_files: staged.stdout.split(/\r?\n/).filter(Boolean),
+      diff_check: diffCheck,
+      validation: {
+        errors: validation.errors.length,
+        warnings: validation.warnings.length,
+      },
+      recommended_gates: [
+        'git diff --check',
+        'tenbo-dashboard validate',
+        'git diff --cached --check',
+      ],
+    };
+    return serialize(payload, json, `branch: ${payload.branch.current ?? 'unknown'}\ndirty files: ${payload.dirty_files.length}\nvalidation: ${payload.validation.errors} errors, ${payload.validation.warnings} warnings\n`);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runCommitReadyCli(repoRootFromCwd(), process.argv.slice(2)));
+}

package/scripts/context.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { runContextCli } from './context';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), 'tenbo-context-cli-'));
+  mkdirSync(path.join(dir, '.git'));
+  mkdirSync(path.join(dir, '.tenbo/scopes/dashboard/layers/cli-tools'), { recursive: true });
+  writeFileSync(path.join(dir, '.tenbo/workspace.yaml'), [
+    'scopes:',
+    '  - id: dashboard',
+    '    path: tenbo-dashboard',
+    '    description: dashboard and CLI package',
+    'cross_cutting: []',
+    '',
+  ].join('\n'));
+  writeFileSync(path.join(dir, '.tenbo/overview.md'), [
+    '# Overview',
+    '',
+    '## Product goals',
+    '- **g1**: Give agents holistic context.',
+    '',
+  ].join('\n'));
+  writeFileSync(path.join(dir, '.tenbo/scopes/dashboard/architecture.yaml'), [
+    'layers:',
+    '  - id: cli-tools',
+    '    name: CLI Tools',
+    '    description: Commands for agents to fetch context.',
+    '    files: ["bin/**", "scripts/**"]',
+    '',
+  ].join('\n'));
+  writeFileSync(path.join(dir, '.tenbo/scopes/dashboard/layers/cli-tools/intent.md'), '# CLI Tools\n');
+  writeFileSync(path.join(dir, '.tenbo/scopes/dashboard/roadmap.yaml'), [
+    'items:',
+    '  - id: td-010',
+    '    title: Add context command',
+    '    layer: cli-tools',
+    '    status: next',
+    '    goal_ref: [g1]',
+    '    description: Add a context command for feature planning.',
+    '',
+  ].join('\n'));
+});
+
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('context CLI', () => {
+  it('prints feature context as JSON', () => {
+    const result = runContextCli(dir, ['feature', '--query', 'build a context command for agents', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    const payload = JSON.parse(result.stdout);
+    expect(payload).toMatchObject({
+      ok: true,
+      intent: 'feature',
+      recommendation: {
+        scope: 'dashboard',
+        layers: ['cli-tools'],
+      },
+    });
+    expect(payload.roadmap.matching_items.map((entry: { item: { id: string } }) => entry.item.id)).toEqual(['td-010']);
+  });
+
+  it('rejects feature context requests without a query', () => {
+    const result = runContextCli(dir, ['feature', '--json']);
+
+    expect(result.exitCode).toBe(2);
+    expect(JSON.parse(result.stderr)).toMatchObject({
+      ok: false,
+      error: 'invalid_args',
+    });
+  });
+});

package/scripts/context.ts

@@ -0,0 +1,29 @@
+import { resolveFeatureContext } from '../src/api/lib/contextResolver';
+import { hasFlag, readOption } from './cliArgs';
+import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+
+export function runContextCli(repoRoot: string, args: string[]): CliResult {
+  const json = hasFlag(args, '--json');
+  const command = args.find((arg) => !arg.startsWith('--'));
+
+  try {
+    if (command === 'feature') {
+      const query = readOption(args, '--query');
+      if (!query) return misuse('Usage: tenbo context feature --query "<request>" [--json]', json);
+      const bundle = resolveFeatureContext(repoRoot, query);
+      return serialize(
+        bundle,
+        json,
+        `${bundle.recommendation.confidence} confidence: ${bundle.recommendation.scope ?? 'unclassified'}${bundle.recommendation.layers.length ? `/${bundle.recommendation.layers.join(',')}` : ''}\n`,
+      );
+    }
+
+    return misuse('Usage: tenbo context feature --query "<request>" [--json]', json);
+  } catch (err) {
+    return handleCliError(err, json);
+  }
+}
+
+if (isMain(import.meta.url)) {
+  runMain(runContextCli(repoRootFromCwd(), process.argv.slice(2)));
+}