Format recap command output as markdown

[acreeger]

Follow-up from #363.

The recap command currently outputs structured data. We should format it as markdown for better readability, which will also make it more suitable for injection into prompts (like the session summary).

Proposed Changes

• Format the recap output as human-readable markdown
• Maintain the same information (goal, complexity, entries, artifacts)
• Use consistent heading structure and formatting

Context

This enables the session summary prompt to receive recap data in a format consistent with the transcript context.

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 2 (recap.ts for output formatting, recap.test.ts for test updates)
• Estimated lines of code: 100-150 (output formatting logic and test assertions)
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good (well-structured command class)
• Overall risk level: Low

Reasoning: This is a straightforward output formatting task affecting only the recap command's non-JSON mode display. The change is isolated to lines 71-89 in recap.ts where plain text console output will be replaced with markdown formatting. Tests exist and will need assertion updates. No complex dependencies or architectural changes required.

[acreeger]

Combined Analysis & Plan - Issue #384

Executive Summary

Format the recap command's non-JSON output as markdown instead of plain text. This is a straightforward formatting change affecting lines 71-89 in recap.ts, replacing console.log plain text output with markdown headings and lists for better readability and prompt injection.

Implementation Overview

High-Level Execution Phases

1. Update Output Formatting: Replace plain text console.log statements with markdown formatting
2. Update Tests: Modify test assertions to expect markdown output

Quick Stats

• 1 file to modify (src/commands/recap.ts)
• 1 test file to update (src/commands/recap.test.ts)
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Recap output is plain text, needs markdown for better readability and prompt injection compatibility
• Architectural context: Isolated to RecapCommand.execute() non-JSON output path (lines 71-89)
• Edge cases: Empty goal (displays "(not set)"), empty entries/artifacts arrays, complexity with/without reason

Codebase Research

• Entry point: /src/commands/recap.ts:71-89 - Console.log statements for non-JSON output
• Dependencies: Uses RecapOutput type which remains unchanged
• Similar patterns: None in codebase - unique output formatting

Affected Files

• /src/commands/recap.ts:71-89 - Replace plain text output with markdown formatting
• /src/commands/recap.test.ts:138-191 - Update test assertions to expect markdown output

Current Output Format (lines 71-89)

Recap file: /path/to/file.json
Goal: Test goal
Complexity: simple - reason text
Entries: 2
  [decision] Test decision
  [insight] Test insight
Artifacts: 1
  [comment] Description - https://url.com

Target Markdown Format

# Loom Recap

**File:** `/path/to/file.json`

## Goal
Test goal

## Complexity
**simple** - reason text

## Entries (2)
- **[decision]** Test decision
- **[insight]** Test insight

## Artifacts (1)
- **[comment]** Description - https://url.com

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/commands/recap.test.ts (MODIFY)

Update existing test assertions in "execute without JSON mode" describe block:

// Verify markdown heading
expect(consoleSpy).toHaveBeenCalledWith('# Loom Recap')
expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('**File:**'))
expect(consoleSpy).toHaveBeenCalledWith('## Goal')
expect(consoleSpy).toHaveBeenCalledWith('Test goal')
// etc.

Files to Modify

1. /src/commands/recap.ts:71-89

Change: Replace plain text console.log output with markdown formatted output

Replace current output block with markdown formatting:

• Add # Loom Recap heading
• Use **File:** for file path
• Use ## Goal, ## Complexity, ## Entries, ## Artifacts headings
• Format entries as - **[type]** content
• Format artifacts as - **[type]** description - url
• Handle "(not set)" cases for missing goal/complexity

2. /src/commands/recap.test.ts:139-191

Change: Update test assertions to expect markdown formatting

Test "should print human-readable output to console including artifacts":

• Update assertions to check for markdown headings and formatting
• Keep behavior-focused (check key outputs exist, not exact call order)

Test "should print (not set) when goal is null and show zero artifacts":

• Update assertions to check markdown format with "(not set)" values

Detailed Execution Order

Phase 1: Update Output Formatting

1. Modify /src/commands/recap.ts:71-89 to output markdown format -> Verify: Output has markdown headings

Phase 2: Update Tests

1. Update test assertions in /src/commands/recap.test.ts:139-174 -> Verify: pnpm test src/commands/recap.test.ts passes
2. Update test assertions in /src/commands/recap.test.ts:178-191 -> Verify: Tests pass

Phase 3: Build Verification

1. Run pnpm build -> Verify: TypeScript compiles without errors

Dependencies and Configuration

None

[acreeger]

Implementation Complete - Issue #384

Summary

Formatted the recap command's non-JSON output as markdown instead of plain text. The output now includes proper markdown headings, bold formatting, and list items for better readability and prompt injection compatibility.

Changes Made

• src/commands/recap.ts: Replaced plain text console output (lines 71-89) with markdown-formatted output
• src/commands/recap.test.ts: Updated test assertions to validate markdown format

Validation Results

• Tests: 16 passed / 16 total
• Typecheck: Passed
• Lint: Passed
• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

src/commands/recap.ts

Changes: Updated non-JSON output format from plain text to markdown

• Added # Loom Recap heading
• File path now displayed as **File:** \path``
• Section headings: ## Goal, ## Complexity, ## Entries (N), ## Artifacts (N)
• Entries formatted as - **[type]** content
• Artifacts formatted as - **[type]** description - url
• Complexity level formatted with bold: **level** - reason

src/commands/recap.test.ts

Changes: Updated test assertions to expect markdown format

• Test "should print markdown-formatted output to console including artifacts": Updated to check for markdown headings and formatting
• Test "should print (not set) when goal is null and show zero entries/artifacts": Updated to check markdown format with "(not set)" values

New Output Format

# Loom Recap

**File:** `/path/to/recap.json`

## Goal
Test goal

## Complexity
**simple** - reason text

## Entries (2)
- **[decision]** Test decision
- **[insight]** Test insight

## Artifacts (1)
- **[comment]** Description - https://url.com

[acreeger]

Combined Analysis & Plan - Issue #384 (Refactoring)

Executive Summary

Refactor the recap command's markdown output into a composable design with individual functions for each section (goal, complexity, entries, artifacts) and a main function that returns the complete markdown string. This enables generating recap markdown without running the CLI.

Implementation Overview

High-Level Execution Phases

1. Create formatter module: New src/utils/recap-formatter.ts with section functions and main formatRecapMarkdown() function
2. Update RecapCommand: Replace inline console.log logic with call to formatRecapMarkdown()
3. Add unit tests: Test each section function and the composed output

Quick Stats

• 1 file to modify (src/commands/recap.ts)
• 1 new file to create (src/utils/recap-formatter.ts)
• 1 test file to create (src/utils/recap-formatter.test.ts)
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Recap markdown generation is embedded in CLI command, not usable programmatically
• Architectural context: Codebase uses standalone utility functions in src/utils/ for composable logic
• Edge cases: Null goal, null complexity, empty entries/artifacts arrays, complexity with/without reason

Codebase Research

• Entry point: /src/commands/recap.ts:71-105 - Markdown generation logic embedded in execute()
• Dependencies: Uses RecapOutput type from src/mcp/recap-types.ts
• Similar patterns: /src/utils/env.ts - Uses standalone exported functions for composable utilities
• Types needed: RecapOutput, RecapComplexity, RecapEntry, RecapArtifact from src/mcp/recap-types.ts

Affected Files

• /src/commands/recap.ts:71-105 - Replace inline markdown logic with formatter call
• /src/utils/recap-formatter.ts (NEW) - New formatter module with section functions

Current Implementation (lines 71-105)

The current code has 5 inline console.log blocks:

1. Header: "# Loom Recap" + file path
2. Goal section: "## Goal" + goal or "(not set)"
3. Complexity section: "## Complexity" + formatted complexity or "(not set)"
4. Entries section: "## Entries (N)" + list of entries
5. Artifacts section: "## Artifacts (N)" + list of artifacts

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/utils/recap-formatter.test.ts (NEW)

describe('recap-formatter', () => {
  describe('formatGoalSection', () => {
    // Test with goal string -> returns "## Goal\n{goal}"
    // Test with null -> returns "## Goal\n(not set)"
  })
  
  describe('formatComplexitySection', () => {
    // Test with level+reason -> "## Complexity\n**{level}** - {reason}"
    // Test with level only -> "## Complexity\n**{level}**"
    // Test with null -> "## Complexity\n(not set)"
  })
  
  describe('formatEntriesSection', () => {
    // Test with entries -> "## Entries (N)\n- **[type]** content..."
    // Test with empty array -> "## Entries (0)"
  })
  
  describe('formatArtifactsSection', () => {
    // Test with artifacts -> "## Artifacts (N)\n- **[type]** desc - url..."
    // Test with empty array -> "## Artifacts (0)"
  })
  
  describe('formatRecapMarkdown', () => {
    // Test full composition with all fields
    // Test with empty/null fields
    // Test includes file path in header
  })
})

New Files to Create

/src/utils/recap-formatter.ts (NEW)

Purpose: Composable markdown formatting functions for recap output

import type { RecapOutput, RecapComplexity, RecapEntry, RecapArtifact } from '../mcp/recap-types.js'

// Format header section with title and file path
export function formatHeaderSection(filePath: string): string {
  // Returns "# Loom Recap\n\n**File:** `{filePath}`"
}

// Format goal section
export function formatGoalSection(goal: string | null): string {
  // Returns "## Goal\n{goal or (not set)}"
}

// Format complexity section
export function formatComplexitySection(complexity: RecapComplexity | null): string {
  // Returns "## Complexity\n{formatted level+reason or (not set)}"
}

// Format entries section with count and list
export function formatEntriesSection(entries: RecapEntry[]): string {
  // Returns "## Entries (N)\n{list of - **[type]** content}"
}

// Format artifacts section with count and list
export function formatArtifactsSection(artifacts: RecapArtifact[]): string {
  // Returns "## Artifacts (N)\n{list of - **[type]** desc - url}"
}

// Main function: compose all sections into full markdown string
export function formatRecapMarkdown(recap: RecapOutput): string {
  // Join all sections with blank lines between them
  // Return complete markdown string
}

Files to Modify

1. /src/commands/recap.ts:71-105

Change: Replace inline markdown generation with single call to formatRecapMarkdown()

Before (lines 71-105):

// Non-JSON mode: print markdown format (intentionally using console.log for piping/redirection)
// eslint-disable-next-line no-console
console.log('# Loom Recap')
// ... 30+ lines of console.log statements

After:

import { formatRecapMarkdown } from '../utils/recap-formatter.js'

// Non-JSON mode: print markdown format (intentionally using console.log for piping/redirection)
// eslint-disable-next-line no-console
console.log(formatRecapMarkdown(result))

Detailed Execution Order

Phase 1: Create Formatter Module

1. Create /src/utils/recap-formatter.ts with all section functions -> Verify: File exists with correct exports
2. Implement formatHeaderSection(filePath) -> Verify: Returns "# Loom Recap\n\nFile: `{path}`"
3. Implement formatGoalSection(goal) -> Verify: Handles null case
4. Implement formatComplexitySection(complexity) -> Verify: Handles null, with/without reason
5. Implement formatEntriesSection(entries) -> Verify: Handles empty array
6. Implement formatArtifactsSection(artifacts) -> Verify: Handles empty array
7. Implement formatRecapMarkdown(recap) -> Verify: Composes all sections correctly

Phase 2: Create Tests

1. Create /src/utils/recap-formatter.test.ts with tests for each function -> Verify: pnpm test src/utils/recap-formatter.test.ts passes

Phase 3: Update RecapCommand

1. Add import for formatRecapMarkdown at top of recap.ts
2. Replace lines 71-105 with single console.log(formatRecapMarkdown(result))
3. Run pnpm test src/commands/recap.test.ts -> Verify: Existing tests still pass

Phase 4: Build Verification

1. Run pnpm build -> Verify: TypeScript compiles without errors

Dependencies and Configuration

None

[acreeger]

Implementation Complete - Issue #384 (Refactoring)

Summary

Refactored the recap command's markdown output into a composable design with individual functions for each section (header, goal, complexity, entries, artifacts) and a main formatRecapMarkdown() function. This enables generating recap markdown programmatically without running the CLI.

Changes Made

• src/utils/recap-formatter.ts: New module with section formatting functions and main composer
• src/commands/recap.ts: Replaced inline console.log logic with single call to formatRecapMarkdown()
• src/utils/recap-formatter.test.ts: Unit tests for each section function and composed output
• src/commands/recap.test.ts: Updated assertions for single console.log call

Validation Results

• Tests: 3033 passed / 3033 total
• Typecheck: Passed
• Lint: Passed
• Build: Passed

---

Detailed Changes by File (click to expand)

Files Created

src/utils/recap-formatter.ts (NEW)

Purpose: Composable markdown formatting functions for recap output

• formatHeaderSection(filePath) - Returns # Loom Recap\n\n**File:** \path``
• formatGoalSection(goal) - Handles null case with "(not set)"
• formatComplexitySection(complexity) - Handles null, with/without reason
• formatEntriesSection(entries) - Handles empty array
• formatArtifactsSection(artifacts) - Handles empty array
• formatRecapMarkdown(recap) - Composes all sections with blank line separators

src/utils/recap-formatter.test.ts (NEW)

Purpose: Unit tests for formatter functions

• Tests for each section function with various inputs
• Tests for composed output with full/empty data

Files Modified

src/commands/recap.ts

Changes: Replaced 35 lines of inline console.log statements with single formatter call

• Added import for formatRecapMarkdown
• Replaced lines 71-105 with console.log(formatRecapMarkdown(result))

src/commands/recap.test.ts

Changes: Updated test assertions for refactored output

• Changed from checking multiple toHaveBeenCalledWith to single call with toContain checks
• Tests now verify markdown content within the single output string

[acreeger]

iloom Session Summary

Key Themes:

• Implemented markdown formatting for recap command output to improve readability and enable programmatic reuse
• Refactored inline formatting logic into composable utility functions following codebase patterns
• Improved semantic markup by making artifact types clickable links to their URLs

---

Session Details (click to expand)

Key Insights

• The recap command had two output modes (JSON and plain text); markdown formatting only affected the plain text path (lines 71-89 in recap.ts)
• The change isolated to non-JSON output meant existing integrations using --json flag remained unaffected
• Codebase follows pattern of standalone utility functions in src/utils/ for composable logic (similar to env.ts, port.ts)
• Extracting formatting to separate module enables generating recap markdown programmatically without running the CLI

Decisions Made

• Created src/utils/recap-formatter.ts: New module with individual section formatters (formatGoalSection, formatComplexitySection, etc.) and main composer formatRecapMarkdown() that returns full markdown string
• Composable design over monolithic: Each section has its own function, making it easy to reuse individual parts or compose them differently
• Artifact links as semantic markdown: Changed from **[type]** description - url to **[type](url)** description so the type becomes a clickable link, improving both semantics and user experience

Challenges Resolved

• Initial implementation too coupled: First version embedded all markdown generation directly in the CLI command's execute method with 30+ lines of console.log statements
• Resolution: Extracted to utility functions that return strings, with CLI simply calling console.log(formatRecapMarkdown(result)). This separation enables non-CLI use cases like session summaries

Lessons Learned

• When implementing formatting features, consider reusability from the start - "could something else need this without running the CLI?"
• Semantic markdown (clickable type labels) is better than plain text followed by URL
• Following existing codebase patterns (utils modules with focused functions) leads to more maintainable code

---

Generated with 🤖❤️ by iloom.ai