Add cli docs command for agents

[mickmister]

This PR adds a sb docs command for agents to run when working in a springboard project

[cloudflare-workers-and-pages]

Deploying jamtools-docs-new with    Cloudflare Pages

Latest commit:	72a1841
Status:	✅  Deploy successful!
Preview URL:	https://ad75adf3.jamtools-docs-new.pages.dev
Branch Preview URL:	https://vk-e9bf-analyze-svelte-m.jamtools-docs-new.pages.dev

View logs

[claude]

Claude finished @mickmister's task —— View job

---

PR Review: Add cli docs command for agents

I've completed my review of this PR. This is a well-implemented feature that adds comprehensive documentation support for AI agents working with Springboard projects.

Todo List:

• Read repository guidelines and context
• Analyze main CLI implementation changes
• Review docs command implementation
• Examine documentation content structure
• Check for security concerns and bugs
• Evaluate performance considerations
• Assess test coverage
• Provide comprehensive feedback

✅ Strengths

Architecture & Design:

• Clean separation of concerns: docs command (docs_command.ts) is well-separated from main CLI
• Good command structure: Intuitive subcommands (list, get, context, types, examples)
• AI-first design: The context command provides excellent comprehensive context for AI agents
• Extensible: Easy to add new documentation sections via JSON configuration

Code Quality:

• TypeScript interfaces: Well-defined types for DocSection and Example
• Error handling: Proper error messages when sections/examples not found
• Consistent patterns: Similar structure between docs and examples systems
• Good abstractions: formatSectionsList(), getDocContent() etc.

Documentation Content:

• Comprehensive coverage: 13 documentation sections covering all major Springboard concepts
• AI-optimized: Clear use cases and tags make content discoverable
• Practical examples: 3 working code examples for different state types
• Good organization: Logical grouping of related concepts

Build System:

• Proper asset copying: copy-docs and copy-examples scripts ensure content is bundled
• File inclusion: src and dist properly included in package files

⚠️ Areas for Improvement

Test Coverage (Critical):

• No tests found for the new docs command functionality
• Should test: section lookup, content retrieval, JSON output, error cases
• Examples: getSection('invalid'), getDocContent('missing-file')

Security & Robustness:

// packages/springboard/cli/src/docs/index.ts:54-58
try {
    return readFileSync(join(docsDir, 'content', filename), 'utf-8');
} catch {
    return null;
}

• Path traversal risk: No validation of filename - could theoretically read files outside content/ directory
• Recommendation: Validate filename against known sections before file operations

Performance Considerations:

• Synchronous file reads: readFileSync blocks event loop, but acceptable for CLI usage
• Multiple reads: Each sb docs get section1 section2 section3 reads files sequentially vs. in parallel
• Memory usage: Loading all examples into memory at module init - fine for current 3 examples but could scale poorly

API Inconsistencies:

// packages/springboard/cli/src/docs/index.ts:35-41
export function getSection(slug: string): DocSection | undefined {
    return sections.find(s =>
        s.slug === slug ||
        s.slug.endsWith(`/${slug}`) ||  // Allow partial matching
        s.title.toLowerCase() === slug.toLowerCase()  // Case insensitive
    );
}

• Multiple matching strategies could be confusing - may match unintended sections
• Recommendation: Be more explicit about partial vs exact matching

CLI Implementation Issues:

// packages/springboard/cli/src/cli.ts:91-113
// Dev and build commands have all code commented out

• Incomplete implementation: Main CLI commands are stubbed out
• Potential confusion: Users may expect sb dev and sb build to work

Error Handling:

• Generic catch blocks: Some error handling could be more specific
• No validation: Commands don't validate file existence before operations

📋 Minor Issues

Code Style:

• Mixed quote styles: Some files use single quotes, others double quotes
• Console.log formatting: Could be more consistent across commands
• Import organization: Some imports could be better organized

Documentation:

• JSDoc coverage: Some functions lack comprehensive JSDoc comments
• Usage examples: Could benefit from more usage examples in help text

🔒 Security Assessment

Overall: Low Risk - This is a CLI tool for development use, not production deployment.

Potential Issues:

• File system access limited to bundled documentation
• No external network requests
• No user input sanitization needed beyond path validation

🎯 Recommendations

High Priority:

1. Add comprehensive tests for docs command functionality
2. Implement path validation in getDocContent() to prevent directory traversal
3. Complete or remove commented code in main CLI commands

Medium Priority:

1. Parallel file reading for multiple sections in get command
2. Consistent error handling patterns across all commands
3. Add JSDoc to public functions

Low Priority:

1. Code style consistency (quotes, imports)
2. Performance monitoring for large documentation sets

🏆 Overall Assessment

This is a high-quality implementation that successfully addresses the need for AI agent documentation support. The code is well-structured, the documentation is comprehensive, and the user experience is thoughtful.

Strengths outweigh concerns - the missing test coverage and minor security considerations are addressable in follow-up PRs without blocking this valuable feature.

Recommendation: ✅ APPROVE with the understanding that test coverage should be addressed in a follow-up PR.

---

Job Run | Branch: vk/e9bf-analyze-svelte-m

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7646ba7ad7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add .js extension to docs command import

This package is published as ESM ("type": "module"), but this relative import is emitted without an extension in dist/cli.js, so Node cannot resolve it at runtime. Running the built CLI (node dist/cli.js --help) immediately throws ERR_MODULE_NOT_FOUND for ./docs_command, which makes every sb command unusable before argument parsing.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Resolve docs directory without __dirname in ESM

The docs loader runs as an ES module, where __dirname is not defined, so sb docs list/get/context crashes during import with ReferenceError: __dirname is not defined in ES module scope (reproduced via npx tsx src/cli.ts docs list). This should derive paths from import.meta.url instead of relying on CommonJS globals.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Resolve examples directory without __dirname in ESM

The examples loader has the same ESM/CJS mismatch: __dirname is undefined in this module format, so sb docs examples list/show fails at runtime with ReferenceError as soon as this file is imported. Using an import.meta.url-based path is required for these commands to work.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Install sb CLI before telling agents to run it

The scaffolded AGENTS/CLAUDE guidance tells users to run npx sb docs context, but this generator does not install springboard-cli (only springboard and runtime deps are installed earlier), so fresh projects have no local sb binary. In that state the first recommended command fails (or may resolve an unrelated package via npx), which breaks the onboarding flow this change introduces.

Useful? React with 👍 / 👎.