tenbo-dashboard 0.10.0 → 0.10.2

package/bin/tenbo-dashboard.mjs

@@ -4,6 +4,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { topLevelItemHelpLines } from '../scripts/itemCommandRegistry.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
@@ -85,12 +86,7 @@ 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]
+${topLevelItemHelpLines().join('\n')}
   tenbo-dashboard items            Query roadmap items [--status <status>]
                                    [--verification <status>] [--goal <goal>]
                                    [--type <type>] [--priority <p0|p1|p2|p3>]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tenbo-dashboard",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Local-first architecture dashboard and CLI tools for .tenbo/ repos",
   "type": "module",
   "license": "MIT",

package/scripts/bin-output.test.ts

@@ -30,6 +30,19 @@ beforeEach(() => {
 afterEach(() => rmSync(dir, { recursive: true, force: true }));
 
 describe('bin output', () => {
+  it('lists item completion in top-level help', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'help'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).toContain('tenbo-dashboard item complete <id>');
+  });
+
   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'], {
@@ -56,4 +69,85 @@ describe('bin output', () => {
       { id: 'ed-001', title: 'Large Output', status: 'done' },
     ]);
   });
+
+  it('prints items help without running the query', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'items', '--help'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).toContain('Usage: tenbo-dashboard items');
+    expect(result.stdout).toContain('--fields <a,b>');
+    expect(result.stdout).not.toContain('ed-001');
+  });
+
+  it('prints item help without requiring an item id', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'item', '--help'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).toContain('Usage: tenbo-dashboard item <command> <id>');
+    expect(result.stdout).toContain('complete');
+    expect(result.stdout).toContain('link-commit');
+    expect(result.stdout).not.toContain('ed-001');
+  });
+
+  it('prints item complete help without requiring an item id', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [bin, 'item', 'complete', '--help'], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout).toContain('Usage: tenbo-dashboard item complete <id>');
+    expect(result.stdout).toContain('--doc-update today|YYYY-MM-DD');
+    expect(result.stdout).toContain('--commit <sha>');
+  });
+
+  it('completes status, doc_update, verification, and commit through the bin wrapper', () => {
+    const bin = path.resolve('bin/tenbo-dashboard.mjs');
+    const result = spawnSync(process.execPath, [
+      bin,
+      'item',
+      'complete',
+      'ed-001',
+      '--evidence',
+      'npm test -- --run',
+      '--doc-update',
+      'today',
+      '--commit',
+      'abc123',
+      '--json',
+    ], {
+      cwd: dir,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+    const today = new Date().toISOString().slice(0, 10);
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    const payload = JSON.parse(result.stdout);
+    expect(payload.item).toMatchObject({
+      status: 'done',
+      doc_update: today,
+      links: ['commit:abc123'],
+      verification: {
+        status: 'verified',
+        evidence: ['npm test -- --run'],
+      },
+    });
+  });
 });

package/scripts/item.ts

@@ -10,12 +10,28 @@ import {
 import { summarizeItem } from '../src/api/lib/itemProjection';
 import { checkItemEvidence } from '../src/api/lib/itemEvidence';
 import { hasFlag, positionalArgs, readOption, readRepeated } from './cliArgs';
-import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+import { handleCliError, isMain, misuse, ok, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+import { findItemCommand, formatItemCommandHelp, formatItemHelp } from './itemCommandRegistry.mjs';
 
 export function runItemCli(repoRoot: string, args: string[]): CliResult {
   const json = hasFlag(args, '--json');
   const [command, itemId, value] = positionalArgs(args);
-  if (!command || !itemId) return misuse('Usage: tenbo item <show|set-status|add-note|verify|link-commit> <item-id>', json);
+
+  if (hasFlag(args, '--help') || command === 'help') {
+    const helpCommand = command === 'help' ? itemId : command;
+    if (helpCommand) {
+      const help = formatItemCommandHelp(helpCommand);
+      if (help) return ok(help);
+      return misuse(`unknown item command: ${helpCommand}`, json);
+    }
+    return ok(formatItemHelp());
+  }
+
+  if (!command) return misuse(formatItemHelp().trimEnd(), json);
+  if (!itemId) {
+    const definition = findItemCommand(command);
+    return misuse(definition ? `Usage: ${definition.usage}` : `unknown item command: ${command}`, json);
+  }
 
   try {
     if (command === 'show') {
@@ -76,13 +92,13 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
     }
 
     if (command === 'set-status') {
-      if (!value) return misuse('Usage: tenbo item set-status <item-id> <status>', json);
+      if (!value) return misuse(`Usage: ${findItemCommand('set-status')?.usage ?? 'tenbo-dashboard item set-status <id> <status>'}`, json);
       const result = setItemStatus(repoRoot, itemId, value);
       return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} status: ${result.item.status}\n`);
     }
 
     if (command === 'add-note') {
-      if (!value) return misuse('Usage: tenbo item add-note <item-id> <note>', json);
+      if (!value) return misuse(`Usage: ${findItemCommand('add-note')?.usage ?? 'tenbo-dashboard item add-note <id> <note>'}`, json);
       const result = addItemNote(repoRoot, itemId, value);
       return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} note added\n`);
     }
@@ -93,7 +109,7 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
         return serialize(report, json, `${itemId} evidence: ${report.verdict}\n`);
       }
       const status = readOption(args, '--status');
-      if (!status) return misuse('Usage: tenbo item verify <item-id> --status <status> [--evidence <text>] [--note <text>]', json);
+      if (!status) return misuse(`Usage: ${findItemCommand('verify')?.usage ?? 'tenbo-dashboard item verify <id> --status <status>'}`, json);
       const result = setItemVerification(repoRoot, itemId, {
         status,
         evidence: readRepeated(args, '--evidence'),
@@ -106,8 +122,8 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
       const date = readOption(args, '--date');
       const skipped = hasFlag(args, '--skipped');
       const reason = readOption(args, '--reason');
-      if (!date && !skipped) return misuse('Usage: tenbo item doc-update <item-id> --date <today|YYYY-MM-DD> OR --skipped --reason "<text>"', json);
-      if (skipped && !reason) return misuse('Usage: tenbo item doc-update <item-id> --skipped --reason "<text>"', json);
+      if (!date && !skipped) return misuse(`Usage: ${findItemCommand('doc-update')?.usage ?? 'tenbo-dashboard item doc-update <id> --date <today|YYYY-MM-DD>'}`, json);
+      if (skipped && !reason) return misuse('Usage: tenbo-dashboard item doc-update <id> --skipped --reason "<text>"', json);
       const today = new Date().toISOString().slice(0, 10);
       const docUpdate = skipped ? `skipped — ${reason}` : date === 'today' ? today : date;
       const result = setItemDocUpdate(repoRoot, itemId, docUpdate ?? today);
@@ -119,7 +135,7 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
       const docUpdateArg = readOption(args, '--doc-update');
       const commit = readOption(args, '--commit');
       const verificationStatus = readOption(args, '--verification');
-      if (evidence.length === 0) return misuse('Usage: tenbo item complete <item-id> --evidence "<text>" [--doc-update today|YYYY-MM-DD] [--commit <sha>] [--verification <status>]', json);
+      if (evidence.length === 0) return misuse(`Usage: ${findItemCommand('complete')?.usage ?? 'tenbo-dashboard item complete <id> --evidence "<text>"'}`, json);
       const today = new Date().toISOString().slice(0, 10);
       const docUpdate = docUpdateArg === 'today' ? today : docUpdateArg;
       const result = completeItem(repoRoot, itemId, {
@@ -132,7 +148,7 @@ export function runItemCli(repoRoot: string, args: string[]): CliResult {
     }
 
     if (command === 'link-commit') {
-      if (!value) return misuse('Usage: tenbo item link-commit <item-id> <sha>', json);
+      if (!value) return misuse(`Usage: ${findItemCommand('link-commit')?.usage ?? 'tenbo-dashboard item link-commit <id> <sha>'}`, json);
       const result = linkItemCommit(repoRoot, itemId, value);
       return serialize({ ok: true, scope: result.scopeId, item: result.item, validation: result.validation }, json, `${itemId} linked commit: ${value}\n`);
     }

package/scripts/itemCommandRegistry.d.mts

@@ -0,0 +1,12 @@
+export interface ItemCommandDefinition {
+  name: string;
+  usage: string;
+  summary: string;
+  details?: string[];
+}
+
+export const ITEM_COMMANDS: ItemCommandDefinition[];
+export function findItemCommand(name: string): ItemCommandDefinition | undefined;
+export function formatItemHelp(): string;
+export function formatItemCommandHelp(name: string): string | undefined;
+export function topLevelItemHelpLines(): string[];

package/scripts/itemCommandRegistry.mjs

@@ -0,0 +1,98 @@
+export const ITEM_COMMANDS = [
+  {
+    name: 'show',
+    usage: 'tenbo-dashboard item show <id> [--json]',
+    summary: 'Show the full roadmap item.',
+  },
+  {
+    name: 'brief',
+    usage: 'tenbo-dashboard item brief <id> [--json]',
+    summary: 'Print compact execution context for one item.',
+  },
+  {
+    name: 'handoff',
+    usage: 'tenbo-dashboard item handoff <id> [--json]',
+    summary: 'Generate a copy/paste handoff prompt.',
+  },
+  {
+    name: 'set-status',
+    usage: 'tenbo-dashboard item set-status <id> <now|next|later|done|dropped> [--json]',
+    summary: 'Set the roadmap status.',
+  },
+  {
+    name: 'add-note',
+    usage: 'tenbo-dashboard item add-note <id> "<note>" [--json]',
+    summary: 'Append a dated item note.',
+  },
+  {
+    name: 'verify',
+    usage: 'tenbo-dashboard item verify <id> --check [--json]',
+    summary: 'Check whether recorded evidence matches completion state.',
+    details: [
+      'tenbo-dashboard item verify <id> --status <not_required|pending_live|verified|failed>',
+      '                                  [--evidence "<text>"] [--note "<text>"] [--json]',
+    ],
+  },
+  {
+    name: 'doc-update',
+    usage: 'tenbo-dashboard item doc-update <id> --date <today|YYYY-MM-DD> [--json]',
+    summary: 'Record documentation freshness for an item.',
+    details: [
+      'tenbo-dashboard item doc-update <id> --skipped --reason "<text>" [--json]',
+    ],
+  },
+  {
+    name: 'complete',
+    usage: 'tenbo-dashboard item complete <id> --evidence "<text>" [--doc-update today|YYYY-MM-DD] [--commit <sha>] [--verification <status>] [--json]',
+    summary: 'Complete status, verification, docs, and optional commit link in one transaction.',
+  },
+  {
+    name: 'link-commit',
+    usage: 'tenbo-dashboard item link-commit <id> <sha> [--json]',
+    summary: 'Attach a commit link to an item.',
+  },
+];
+
+const commandByName = new Map(ITEM_COMMANDS.map((command) => [command.name, command]));
+
+export function findItemCommand(name) {
+  return commandByName.get(name);
+}
+
+export function formatItemHelp() {
+  const maxNameLength = Math.max(...ITEM_COMMANDS.map((command) => command.name.length));
+  const commandLines = ITEM_COMMANDS.flatMap((command) => [
+    `  ${command.name.padEnd(maxNameLength)}  ${command.summary}`,
+    `  ${' '.repeat(maxNameLength)}  ${command.usage}`,
+  ]);
+
+  return [
+    'Usage: tenbo-dashboard item <command> <id> [options]',
+    '',
+    'Commands:',
+    ...commandLines,
+    '',
+    'Run tenbo-dashboard item <command> --help for command-specific usage.',
+    '',
+  ].join('\n');
+}
+
+export function formatItemCommandHelp(name) {
+  const command = findItemCommand(name);
+  if (!command) return undefined;
+  return [
+    `Usage: ${command.usage}`,
+    '',
+    command.summary,
+    ...(command.details?.length ? ['', 'Additional forms:', ...command.details.map((line) => `  ${line}`)] : []),
+    '',
+  ].join('\n');
+}
+
+export function topLevelItemHelpLines() {
+  return ITEM_COMMANDS.flatMap((command) => {
+    const lines = [`  ${command.usage}`];
+    if (command.details?.length) lines.push(...command.details.map((line) => `  ${line}`));
+    return lines;
+  });
+}

package/scripts/items.test.ts

@@ -82,6 +82,26 @@ describe('items CLI', () => {
     ]);
   });
 
+  it('includes goal_ref in selected compact fields', () => {
+    writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+      'items:',
+      '  - id: ed-001',
+      '    title: First',
+      '    layer: app',
+      '    status: next',
+      '    description: first item',
+      '    goal_ref: [g1, g2]',
+      '',
+    ].join('\n'));
+
+    const result = runItemsCli(dir, ['--fields', 'id,title,goal_ref', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout).items).toEqual([
+      { id: 'ed-001', title: 'First', goal_ref: ['g1', 'g2'] },
+    ]);
+  });
+
   it('returns compact summaries without changing full JSON by default', () => {
     const summary = runItemsCli(dir, ['--status', 'next', '--summary', '--json']);
     const full = runItemsCli(dir, ['--status', 'next', '--json']);

package/scripts/items.ts

@@ -1,9 +1,11 @@
 import { listItems, type ListItemFilters } from '../src/api/lib/roadmapStore';
 import { parseItemFields, projectItem, summarizeItem } from '../src/api/lib/itemProjection';
 import { hasFlag, readOption } from './cliArgs';
-import { handleCliError, isMain, misuse, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
+import { handleCliError, isMain, misuse, ok, repoRootFromCwd, runMain, serialize, type CliResult } from './cliResult';
 
 const STATUSES = new Set(['now', 'next', 'later', 'done', 'dropped']);
+const USAGE = `Usage: tenbo-dashboard items [--status <status[,status]>] [--verification <status>] [--goal <goal>] [--type <type>] [--priority <p0|p1|p2|p3>] [--layer <id>] [--fields <a,b>] [--summary] [--json]
+`;
 
 function readStatusFilter(value: string | undefined): ListItemFilters['status'] {
   if (!value) return undefined;
@@ -49,7 +51,8 @@ export function runItemsCli(repoRoot: string, args: string[]): CliResult {
 if (isMain(import.meta.url)) {
   const args = process.argv.slice(2);
   if (args.includes('--help')) {
-    runMain(fail('invalid_args', 'Usage: tenbo items [--status <status>] [--verification <status>] [--goal <goal>] [--json]', false));
+    runMain(ok(USAGE));
+  } else {
+    runMain(runItemsCli(repoRootFromCwd(), args));
   }
-  runMain(runItemsCli(repoRootFromCwd(), args));
 }

package/scripts/next-id.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readdirSync, utimesSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readdirSync, utimesSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';

package/scripts/next-id.ts

@@ -27,7 +27,7 @@
  *   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 { readFileSync, existsSync, mkdirSync, 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';
@@ -41,10 +41,6 @@ interface WorkspaceScope {
   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');

package/src/api/lib/itemProjection.ts

@@ -10,6 +10,7 @@ export interface ItemSummaryRecord {
   layers?: string[];
   type?: Item['type'];
   priority?: Priority;
+  goal_ref?: Item['goal_ref'];
   verification?: VerificationStatus;
   risk_count?: number;
   done_when_count?: number;
@@ -25,6 +26,7 @@ export const ITEM_FIELD_NAMES = [
   'layers',
   'type',
   'priority',
+  'goal_ref',
   'verification',
   'risk_count',
   'done_when_count',
@@ -60,6 +62,7 @@ export function summarizeItem(entry: LocatedItem): ItemSummaryRecord {
     ...(item.layers ? { layers: item.layers } : {}),
     ...(item.type ? { type: item.type } : {}),
     ...(item.priority ? { priority: item.priority } : {}),
+    ...(item.goal_ref ? { goal_ref: item.goal_ref } : {}),
     ...(item.verification?.status ? { verification: item.verification.status } : {}),
     ...(item.risks ? { risk_count: item.risks.length } : {}),
     ...(item.done_when ? { done_when_count: item.done_when.length } : {}),

package/tsconfig.json

@@ -14,5 +14,5 @@
     "allowImportingTsExtensions": false,
     "noEmit": true
   },
-  "include": ["src", "tests", "vite.config.ts"]
+  "include": ["src", "tests", "scripts", "vite.config.ts"]
 }