tenbo-dashboard 0.10.1 → 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.1",
+  "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'], {
@@ -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;
+  });
+}