tenbo-dashboard 0.10.1 → 0.10.3

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.1",
+  "version": "0.10.3",
   "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'], {
@@ -71,4 +84,70 @@ describe('bin output', () => {
     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

@@ -120,6 +120,31 @@ describe('items CLI', () => {
     expect(JSON.parse(full.stdout).items[0].item.description).toBe('second item');
   });
 
+  it('summarizes items whose notes are YAML sequences', () => {
+    writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+      'items:',
+      '  - id: ed-001',
+      '    title: First',
+      '    layer: app',
+      '    status: next',
+      '    description: first item',
+      '    notes:',
+      '      - First note',
+      '      - Latest list note',
+      '',
+    ].join('\n'));
+
+    const result = runItemsCli(dir, ['--status', 'next', '--summary', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout).items).toEqual([
+      expect.objectContaining({
+        id: 'ed-001',
+        latest_note: 'Latest list note',
+      }),
+    ]);
+  });
+
   it('returns misuse errors for invalid status lists and fields', () => {
     const badStatus = runItemsCli(dir, ['--status', 'next,unknown', '--json']);
     const badField = runItemsCli(dir, ['--fields', 'id,nope', '--json']);

package/scripts/next.test.ts

@@ -64,4 +64,29 @@ describe('next CLI', () => {
     ]);
     expect(payload.items[0]).not.toHaveProperty('description');
   });
+
+  it('returns agent summaries when notes are YAML sequences', () => {
+    writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+      'items:',
+      '  - id: ed-001',
+      '    title: First',
+      '    layer: app',
+      '    status: next',
+      '    description: first item',
+      '    notes:',
+      '      - First note',
+      '      - Latest list note',
+      '',
+    ].join('\n'));
+
+    const result = runNextCli(dir, ['--agent-summary', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout).items).toEqual([
+      expect.objectContaining({
+        id: 'ed-001',
+        latest_note: 'Latest list note',
+      }),
+    ]);
+  });
 });

package/scripts/work-queue.test.ts

@@ -62,4 +62,30 @@ describe('work-queue CLI', () => {
     ]);
     expect(payload.items[0]).not.toHaveProperty('description');
   });
+
+  it('returns compact work queue items when notes are YAML sequences', () => {
+    writeFileSync(path.join(dir, '.tenbo/scopes/editor/roadmap.yaml'), [
+      'items:',
+      '  - id: ed-001',
+      '    title: Active Refactor',
+      '    layer: app',
+      '    status: now',
+      '    type: refactor',
+      '    description: active refactor',
+      '    notes:',
+      '      - First note',
+      '      - Latest list note',
+      '',
+    ].join('\n'));
+
+    const result = runWorkQueueCli(dir, ['--type', 'refactor', '--json']);
+
+    expect(result.exitCode).toBe(0);
+    expect(JSON.parse(result.stdout).items).toEqual([
+      expect.objectContaining({
+        id: 'ed-001',
+        latest_note: 'Latest list note',
+      }),
+    ]);
+  });
 });

package/src/api/lib/itemProjection.ts

@@ -1,5 +1,6 @@
 import type { Item, Priority, Status, VerificationStatus } from '../../types';
 import type { LocatedItem } from './roadmapStore';
+import { normalizeNotes } from './notes';
 
 export interface ItemSummaryRecord {
   id: string;
@@ -45,9 +46,10 @@ export function parseItemFields(value: string): ItemFieldName[] {
   return fields as ItemFieldName[];
 }
 
-function latestNote(notes: string | undefined): string | undefined {
-  if (!notes) return undefined;
-  const lines = notes.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+function latestNote(notes: unknown): string | undefined {
+  const normalized = normalizeNotes(notes);
+  if (!normalized) return undefined;
+  const lines = normalized.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   return lines.at(-1)?.replace(/^- /, '');
 }
 

package/src/api/lib/notes.ts

@@ -0,0 +1,12 @@
+export function normalizeNotes(notes: unknown): string {
+  if (!notes) return '';
+  if (typeof notes === 'string') return notes.trimEnd();
+  if (Array.isArray(notes)) {
+    return notes
+      .map((entry) => String(entry).trim())
+      .filter(Boolean)
+      .map((entry) => entry.startsWith('- ') ? entry : `- ${entry}`)
+      .join('\n');
+  }
+  return String(notes).trimEnd();
+}

package/src/api/lib/roadmapStore.ts

@@ -6,6 +6,7 @@ import { readState } from './tenboFs';
 import { invalidate as invalidateCache } from './parseCache';
 import { validate } from './validator';
 import { comparePriority } from './priority';
+import { normalizeNotes } from './notes';
 import type { Item, Priority, Status, VerificationStatus, ValidateResult } from '../../types';
 
 export type RoadmapErrorCode = 'not_found' | 'conflict' | 'invalid_status' | 'invalid_args';
@@ -123,19 +124,6 @@ function validateVerificationStatus(status: string): VerificationStatus {
   throw new RoadmapStoreError('invalid_status', `invalid verification status: ${status}`);
 }
 
-function normalizeNotes(notes: unknown): string {
-  if (!notes) return '';
-  if (typeof notes === 'string') return notes.trimEnd();
-  if (Array.isArray(notes)) {
-    return notes
-      .map((entry) => String(entry).trim())
-      .filter(Boolean)
-      .map((entry) => entry.startsWith('- ') ? entry : `- ${entry}`)
-      .join('\n');
-  }
-  return String(notes).trimEnd();
-}
-
 function mutateItem(
   repoRoot: string,
   itemId: string,