feat: add JSON output option to various commands

Author: Marvin Zhang

packages/cli/src/commands/backfill.ts

@@ -29,6 +29,7 @@ export interface BackfillOptions {
   includeAssignee?: boolean;
   includeTransitions?: boolean;
   specs?: string[]; // specific specs to target
+  json?: boolean;
 }
 
 /**
@@ -43,19 +44,22 @@ export function backfillCommand(): Command {
     .option('--assignee', 'Include assignee from first commit author')
     .option('--transitions', 'Include full status transition history')
     .option('--all', 'Include all optional fields (assignee + transitions)')
+    .option('--json', 'Output as JSON')
     .action(async (specs: string[] | undefined, options: {
       dryRun?: boolean;
       force?: boolean;
       assignee?: boolean;
       transitions?: boolean;
       all?: boolean;
+      json?: boolean;
     }) => {
       await backfillTimestamps({
         dryRun: options.dryRun,
         force: options.force,
         includeAssignee: options.assignee || options.all,
         includeTransitions: options.transitions || options.all,
         specs: specs && specs.length > 0 ? specs : undefined,
+        json: options.json,
       });
     });
 }

packages/cli/src/commands/board.ts

@@ -21,12 +21,14 @@ export function boardCommand(): Command {
     .option('--completion-only', 'Show only completion summary (no kanban)')
     .option('--tag <tag>', 'Filter by tag')
     .option('--assignee <name>', 'Filter by assignee')
+    .option('--json', 'Output as JSON')
     .action(async (options: {
       showComplete?: boolean;
       simple?: boolean;
       completionOnly?: boolean;
       tag?: string;
       assignee?: string;
+      json?: boolean;
     }) => {
       await showBoard(options);
     });
@@ -38,6 +40,7 @@ export async function showBoard(options: {
   completionOnly?: boolean;
   tag?: string;
   assignee?: string;
+  json?: boolean;
 }): Promise<void> {
   // Auto-check for conflicts before display
   await autoCheckIfEnabled();
@@ -61,7 +64,11 @@ export async function showBoard(options: {
   );
 
   if (specs.length === 0) {
-    console.log(chalk.dim('No specs found.'));
+    if (options.json) {
+      console.log(JSON.stringify({ columns: {}, total: 0 }, null, 2));
+    } else {
+      console.log(chalk.dim('No specs found.'));
+    }
     return;
   }
 
@@ -85,6 +92,32 @@ export async function showBoard(options: {
     }
   }
 
+  // JSON output
+  if (options.json) {
+    const completionMetrics = calculateCompletion(specs);
+    const velocityMetrics = calculateVelocityMetrics(specs);
+    
+    const jsonOutput = {
+      columns: {
+        planned: columns.planned.map(s => ({ path: s.path, priority: s.frontmatter.priority, assignee: s.frontmatter.assignee, tags: s.frontmatter.tags })),
+        'in-progress': columns['in-progress'].map(s => ({ path: s.path, priority: s.frontmatter.priority, assignee: s.frontmatter.assignee, tags: s.frontmatter.tags })),
+        complete: columns.complete.map(s => ({ path: s.path, priority: s.frontmatter.priority, assignee: s.frontmatter.assignee, tags: s.frontmatter.tags })),
+      },
+      summary: {
+        total: completionMetrics.totalSpecs,
+        active: completionMetrics.activeSpecs,
+        complete: completionMetrics.completeSpecs,
+        completionRate: completionMetrics.score,
+        velocity: {
+          avgCycleTime: velocityMetrics.cycleTime.average,
+          throughputPerWeek: velocityMetrics.throughput.perWeek / 7 * 7,
+        },
+      },
+    };
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return;
+  }
+
   // Display header
   console.log(chalk.bold.cyan('📋 Spec Kanban Board'));
 

packages/cli/src/commands/check.ts

@@ -13,7 +13,8 @@ export function checkCommand(): Command {
   return new Command('check')
     .description('Check for sequence conflicts')
     .option('-q, --quiet', 'Brief output')
-    .action(async (options: { quiet?: boolean }) => {
+    .option('--json', 'Output as JSON')
+    .action(async (options: { quiet?: boolean; json?: boolean }) => {
       const hasNoConflicts = await checkSpecs(options);
       process.exit(hasNoConflicts ? 0 : 1);
     });
@@ -25,6 +26,7 @@ export function checkCommand(): Command {
 export async function checkSpecs(options: {
   quiet?: boolean;
   silent?: boolean;
+  json?: boolean;
 } = {}): Promise<boolean> {
   const config = await loadConfig();
   const cwd = process.cwd();
@@ -59,11 +61,28 @@ export async function checkSpecs(options: {
 
   if (conflicts.length === 0) {
     if (!options.quiet && !options.silent) {
-      console.log(chalk.green('✓ No sequence conflicts detected'));
+      if (options.json) {
+        console.log(JSON.stringify({ conflicts: [], hasConflicts: false }, null, 2));
+      } else {
+        console.log(chalk.green('✓ No sequence conflicts detected'));
+      }
     }
     return true;
   }
 
+  // JSON output
+  if (options.json) {
+    const jsonOutput = {
+      hasConflicts: true,
+      conflicts: conflicts.map(([seq, paths]) => ({
+        sequence: seq,
+        specs: paths,
+      })),
+    };
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return false;
+  }
+  
   // Report conflicts
   if (!options.silent) {
     if (!options.quiet) {

packages/cli/src/commands/files.ts

@@ -12,6 +12,7 @@ import { countTokens } from '@leanspec/core';
 export interface FilesOptions {
   type?: 'docs' | 'assets';
   tree?: boolean;
+  json?: boolean;
 }
 
 export function filesCommand(): Command;
@@ -26,6 +27,7 @@ export function filesCommand(specPath?: string, options: FilesOptions = {}): Com
     .argument('<spec>', 'Spec to list files for')
     .option('--type <type>', 'Filter by type: docs, assets')
     .option('--tree', 'Show tree structure')
+    .option('--json', 'Output as JSON')
     .action(async (target: string, opts: FilesOptions) => {
       await showFiles(target, opts);
     });
@@ -57,6 +59,34 @@ export async function showFiles(
   // Load sub-files
   const subFiles = await loadSubFiles(spec.fullPath);
 
+  // JSON output
+  if (options.json) {
+    const readmeStat = await fs.stat(spec.filePath);
+    const readmeContent = await fs.readFile(spec.filePath, 'utf-8');
+    const readmeTokens = await countTokens({ content: readmeContent });
+    
+    const jsonOutput = {
+      spec: spec.name,
+      path: spec.fullPath,
+      files: [
+        {
+          name: 'README.md',
+          type: 'required',
+          size: readmeStat.size,
+          tokens: readmeTokens.total,
+        },
+        ...subFiles.map(f => ({
+          name: f.name,
+          type: f.type,
+          size: f.size,
+        })),
+      ],
+      total: subFiles.length + 1,
+    };
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return;
+  }
+
   console.log('');
   console.log(chalk.cyan(`📄 Files in ${sanitizeUserInput(spec.name)}`));
   console.log('');

packages/cli/src/commands/gantt.ts

@@ -39,7 +39,8 @@ export function ganttCommand(): Command {
     .option('--weeks <n>', 'Show N weeks (default: 4)', parseInt)
     .option('--show-complete', 'Include completed specs')
     .option('--critical-path', 'Highlight critical path')
-    .action(async (options: { weeks?: number; showComplete?: boolean; criticalPath?: boolean }) => {
+    .option('--json', 'Output as JSON')
+    .action(async (options: { weeks?: number; showComplete?: boolean; criticalPath?: boolean; json?: boolean }) => {
       await showGantt(options);
     });
 }
@@ -48,6 +49,7 @@ export async function showGantt(options: {
   weeks?: number;
   showComplete?: boolean;
   criticalPath?: boolean;
+  json?: boolean;
 }): Promise<void> {
   // Auto-check for conflicts before display
   await autoCheckIfEnabled();
@@ -79,8 +81,30 @@ export async function showGantt(options: {
   });
 
   if (relevantSpecs.length === 0) {
-    console.log(chalk.dim('No active specs found.'));
-    console.log(chalk.dim('Tip: Use --show-complete to include completed specs.'));
+    if (options.json) {
+      console.log(JSON.stringify({ specs: [], weeks }, null, 2));
+    } else {
+      console.log(chalk.dim('No active specs found.'));
+      console.log(chalk.dim('Tip: Use --show-complete to include completed specs.'));
+    }
+    return;
+  }
+
+  // JSON output
+  if (options.json) {
+    const jsonOutput = {
+      weeks,
+      specs: relevantSpecs.map(spec => ({
+        path: spec.path,
+        status: spec.frontmatter.status,
+        priority: spec.frontmatter.priority,
+        created: spec.frontmatter.created,
+        completed: spec.frontmatter.completed,
+        due: spec.frontmatter.due,
+        dependsOn: spec.frontmatter.depends_on,
+      })),
+    };
+    console.log(JSON.stringify(jsonOutput, null, 2));
     return;
   }
 

packages/cli/src/commands/list.ts

@@ -26,6 +26,7 @@ export function listCommand(): Command {
     .option('--field <name=value...>', 'Filter by custom field (can specify multiple)')
     .option('--sort <field>', 'Sort by field (id, created, name, status, priority)', 'id')
     .option('--order <order>', 'Sort order (asc, desc)', 'desc')
+    .option('--json', 'Output as JSON')
     .action(async (options: {
       archived?: boolean;
       status?: SpecStatus;
@@ -35,6 +36,7 @@ export function listCommand(): Command {
       field?: string[];
       sort?: string;
       order?: string;
+      json?: boolean;
     }) => {
       const customFields = parseCustomFieldOptions(options.field);
       const listOptions: {
@@ -46,6 +48,7 @@ export function listCommand(): Command {
         customFields?: Record<string, unknown>;
         sortBy?: string;
         sortOrder?: 'asc' | 'desc';
+        json?: boolean;
       } = {
         showArchived: options.archived,
         status: options.status,
@@ -55,6 +58,7 @@ export function listCommand(): Command {
         customFields: Object.keys(customFields).length > 0 ? customFields : undefined,
         sortBy: options.sort || 'id',
         sortOrder: (options.order as 'asc' | 'desc') || 'desc',
+        json: options.json,
       };
       await listSpecs(listOptions);
     });
@@ -69,6 +73,7 @@ export async function listSpecs(options: {
   customFields?: Record<string, unknown>;
   sortBy?: string;
   sortOrder?: 'asc' | 'desc';
+  json?: boolean;
 } = {}): Promise<void> {
   // Auto-check for conflicts before listing
   await autoCheckIfEnabled();
@@ -106,7 +111,32 @@ export async function listSpecs(options: {
   );
 
   if (specs.length === 0) {
-    console.log(chalk.dim('No specs found.'));
+    if (options.json) {
+      console.log(JSON.stringify({ specs: [], total: 0 }, null, 2));
+    } else {
+      console.log(chalk.dim('No specs found.'));
+    }
+    return;
+  }
+
+  // JSON output
+  if (options.json) {
+    const jsonOutput = {
+      specs: specs.map(spec => ({
+        path: spec.path,
+        name: spec.name,
+        status: spec.frontmatter.status,
+        priority: spec.frontmatter.priority,
+        tags: spec.frontmatter.tags,
+        assignee: spec.frontmatter.assignee,
+        created: spec.frontmatter.created,
+        completed: spec.frontmatter.completed,
+        subFiles: spec.subFiles?.length || 0,
+      })),
+      total: specs.length,
+      filter: options,
+    };
+    console.log(JSON.stringify(jsonOutput, null, 2));
     return;
   }
 

packages/cli/src/commands/search.ts

@@ -22,12 +22,14 @@ export function searchCommand(): Command {
     .option('--priority <priority>', 'Filter by priority')
     .option('--assignee <name>', 'Filter by assignee')
     .option('--field <name=value...>', 'Filter by custom field (can specify multiple)')
+    .option('--json', 'Output as JSON')
     .action(async (query: string, options: {
       status?: SpecStatus;
       tag?: string;
       priority?: SpecPriority;
       assignee?: string;
       field?: string[];
+      json?: boolean;
     }) => {
       const customFields = parseCustomFieldOptions(options.field);
       await performSearch(query, {
@@ -36,6 +38,7 @@ export function searchCommand(): Command {
         priority: options.priority,
         assignee: options.assignee,
         customFields: Object.keys(customFields).length > 0 ? customFields : undefined,
+        json: options.json,
       });
     });
 }
@@ -46,6 +49,7 @@ export async function performSearch(query: string, options: {
   priority?: SpecPriority;
   assignee?: string;
   customFields?: Record<string, unknown>;
+  json?: boolean;
 }): Promise<void> {
   // Auto-check for conflicts before search
   await autoCheckIfEnabled();
@@ -93,6 +97,27 @@ export async function performSearch(query: string, options: {
 
   const { results, metadata } = searchResult;
 
+  // JSON output
+  if (options.json) {
+    const jsonOutput = {
+      query,
+      results: results.map(r => ({
+        spec: r.spec.path,
+        score: r.score,
+        totalMatches: r.totalMatches,
+        matches: r.matches.map(m => ({
+          field: m.field,
+          text: m.text,
+          lineNumber: m.lineNumber,
+        })),
+      })),
+      metadata,
+      filters: filter,
+    };
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return;
+  }
+
   // Display results
   if (results.length === 0) {
     console.log('');