feat: add CLI for automated documentation updates#12
Conversation
- Implemented update-docs pipeline to generate and update docs - Added support for Codex integration to automate documentation updates - Created necessary utility classes and constants for functionality
- Recommend using top-level await with try/catch in CLI entry points - Emphasize Logger usage over console.log for output
- Add update-docs CLI description and usage instructions - Revise README for clarity on CLI functionalities - Enhance template README with setup notes
…ines - Add object destructuring for public method parameters in AGENTS.md - Update README.md with new client files and descriptions - Rename GhClient to GitHubClient for consistency - Introduce CodexClient for Codex interactions
There was a problem hiding this comment.
Pull request overview
This PR introduces a new CLI tool for automated documentation updates that compares the current branch against a base branch and uses Codex to sync documentation. The changes also include a significant refactoring that extracts GitHub-related code into shared clients and establishes new coding conventions for error handling and method parameters.
Changes:
- Added
run:update-docsCLI with GitClient, CodexClient, and diff-based documentation workflow - Refactored GitHub API wrapper from CLI-specific code into shared GitHubClient with schema exports
- Updated AGENTS.md with new conventions for top-level await/try-catch and object destructuring
- Removed template CHECKLIST.md in favor of inline README notes
Reviewed changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
src/cli/update-docs/main.ts |
New CLI entry point following updated error handling conventions |
src/cli/update-docs/types/schemas.ts |
CLI argument schema for base branch and codex flag |
src/cli/update-docs/constants.ts |
Output paths and Codex prompt template |
src/cli/update-docs/clients/update-docs-pipeline.ts |
Orchestrates git diff generation, markdown formatting, and Codex launch |
src/cli/update-docs/clients/diff-formatter.ts |
Formats branch diff into markdown for Codex consumption |
src/cli/update-docs/README.md |
Comprehensive documentation for the new CLI |
src/clients/git-client.ts |
New wrapper for git CLI operations (branch, diff, changed files) |
src/clients/codex-client.ts |
Extracted Codex CLI launcher with availability check |
src/clients/github-client.ts |
Refactored from GhClient with schemas moved from CLI-specific location |
src/cli/fix-pr-comments/types/schemas.ts |
Updated to re-export shared types from GitHubClient |
src/cli/fix-pr-comments/clients/fix-pr-pipeline.ts |
Updated to use GitHubClient and CodexClient |
src/cli/fix-pr-comments/README.md |
Updated client reference from GhClient to GitHubClient |
templates/cli-basic/README.md |
Added inline notes replacing CHECKLIST.md reference |
templates/cli-basic/CHECKLIST.md |
Removed in favor of inline README guidance |
README.md |
Added update-docs CLI documentation and structure updates |
AGENTS.md |
Added conventions for try-catch and object destructuring |
package.json |
Added run:update-docs script |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
src/cli/update-docs/README.md
Outdated
| When Codex runs, it updates: | ||
|
|
||
| 1. `README.md` - If new features, changed usage, or new dependencies | ||
| 2. `CLAUDE.md/AGENTS.md` - If new patterns, conventions, or tools added |
There was a problem hiding this comment.
The Documentation Targets section mentions "CLAUDE.md/AGENTS.md" but the constants file at line 19 explicitly states "do NOT edit CLAUDE.md - it is a symlink to AGENTS.md". This should be updated to only reference AGENTS.md to be consistent with the constant and avoid confusion.
| 2. `CLAUDE.md/AGENTS.md` - If new patterns, conventions, or tools added | |
| 2. `AGENTS.md` - If new patterns, conventions, or tools added |
| export class DiffFormatter { | ||
| formatMarkdown( | ||
| branch: string, | ||
| base: string, | ||
| changedFiles: string[], | ||
| diff: string | ||
| ): string { | ||
| const lines: string[] = [ | ||
| `# Changes: ${branch} vs ${base}`, | ||
| "", | ||
| `## Changed Files (${changedFiles.length})`, | ||
| "", | ||
| ]; | ||
|
|
||
| for (const file of changedFiles) { | ||
| lines.push(`- ${file}`); | ||
| } | ||
|
|
||
| lines.push("", "## Full Diff", "", "```diff", diff, "```"); | ||
|
|
||
| return lines.join("\n"); | ||
| } | ||
| } |
There was a problem hiding this comment.
The DiffFormatter class lacks test coverage. The repository has comprehensive automated testing, and similar formatting classes like CommentFormatter in src/cli/fix-pr-comments/clients/comment-formatter.test.ts have test coverage. Tests should be added to verify the markdown formatting output for different scenarios (e.g., no changed files, single file, multiple files, diff content).
What
Introduce a new CLI tool that automates the process of updating documentation based on changes in the code. This feature compares the current branch against a specified base branch, generates a diff, and utilizes Codex for documentation updates. The implementation includes enhancements to existing documentation files to reflect new CLI functionalities and guidelines.
Added
run:update-docscommand to update documentation.Integrated Codex for automated documentation updates.
Updated
AGENTS.mdandREADME.mdwith new CLI usage instructions and logging guidelines.Improved error handling and logging practices in CLI entry points.
How to test
Run
pnpm run:update-docsto execute the new CLI command.Verify that documentation updates occur as expected based on the changes in the branch.
Check the output in
tmp/update-docs/<branch>/changes.mdfor correctness.Expected results include a successful update of documentation files and appropriate logging of actions taken.
Security review
Secrets / env vars: not changed.
Auth / session: not changed.
Network / API calls: changed. (New calls to Codex for documentation updates.)
Data handling / PII: not changed.
Dependencies: added. (New dependencies for Codex integration.)
No security-impacting changes identified.
No new dependencies and no network calls outside of Codex.
No env var changes and no auth/session logic touched.