feat(cli): add Framna Docs CLI package#657
Draft
ulrikandersen wants to merge 61 commits intofeature/two-phase-project-loadingfrom
Draft
feat(cli): add Framna Docs CLI package#657ulrikandersen wants to merge 61 commits intofeature/two-phase-project-loadingfrom
ulrikandersen wants to merge 61 commits intofeature/two-phase-project-loadingfrom
Conversation
Add POST /api/cli/auth/device endpoint that initiates GitHub device flow authentication for CLI clients. Returns user code, verification URI, device code, session ID, and timing parameters needed for the auth flow.
Wrap initiateDeviceFlow() in try/catch to prevent exposing sensitive error details in 500 responses.
Add GET /api/cli/auth/status endpoint that CLI uses to poll for device flow completion. Returns pending/complete status with sessionId when authorization succeeds.
Add test case for when pollForToken fails, verifying that the endpoint returns 500 status with error details.
Add POST /api/cli/auth/logout endpoint that extracts session ID from Bearer token in Authorization header and deletes the session from Redis.
Add CLI session middleware helper for authenticated endpoints: - getSessionFromRequest: extracts session ID from Bearer token - withAuth: higher-order function that validates sessions via Redis and provides GitHub access token to route handlers This middleware will be used by CLI endpoints (projects, endpoints, schemas) to authenticate requests using MCP session tokens.
Add CLI projects endpoint that returns a list of projects using the authenticated user's GitHub access token. Includes helper functions for creating GitHubClient and ProjectDataSource specific to CLI usage. Also fix pre-existing build issues in MCP route (Map iteration and session null check).
Add try-catch wrapper to handler for proper error responses and move Octokit instantiation to constructor to avoid creating new instances on every GraphQL request.
- Task 1.6: Single project endpoint /api/cli/projects/[name] - Task 1.7: Endpoints list /api/cli/endpoints - Task 1.8: Endpoints search /api/cli/endpoints/search - Task 1.9: Single endpoint details /api/cli/endpoint - Task 1.10: Schemas list /api/cli/schemas - Task 1.11: Single schema /api/cli/schema All endpoints use withAuth middleware and include proper error handling.
Set up the CLI package structure with TypeScript configuration, session management via local config files, and an HTTP API client for communicating with the Framna Docs server.
Implement the command layer for the Framna Docs CLI including: - Auth commands: login (device flow), logout, status - Projects command: list all projects, get project details - Endpoints commands: list, search, get endpoint details - Schemas commands: list schemas, get schema definition - Shared utilities: authenticated client helper, table formatting - MCP command placeholder for future implementation
Add full MCP server implementation with 7 tools for AI assistant integration: - list_projects, get_project for project discovery - list_endpoints, search_endpoints, get_endpoint_details for API exploration - list_schemas, get_schema for schema introspection Wire up CLI entry point with all commands including auth, projects, endpoints, schemas, and mcp serve subcommand.
- Create types.ts with shared EndpointSummary and Project interfaces - Update mcp.ts to use getAuthenticatedClient() helper from shared.ts - Update endpoints.ts to import EndpointSummary from types.ts - Update server.ts to import Project and EndpointSummary from types.ts
- Add workspaces configuration to root package.json - Rename CLI package to @framna-docs/cli to avoid conflict - Add cli:build, cli:dev, cli:lint scripts for workspace commands
- Move ignores to top-level config object for ESLint flat config - Add glob patterns to ignore packages/*/dist and node_modules - Add eslint-disable comments for intentional await-in-loop in device auth
- Document installation via npx and npm - Document authentication commands (login, status, logout) - Document project, endpoint, and schema commands - Document MCP integration setup for AI assistants - Document environment configuration
- Add NODE_ENV check to dev token bypass to prevent accidental production use - Return 500 status for server errors instead of 404 in CLI endpoint/schema routes - Default CLI server URL to localhost:3000 instead of non-functional example.com - Remove duplicate Project interface, import from types.ts instead
Update CLI API routes and MCP server to use the new two-phase project loading architecture (GitHubProjectListDataSource for fast listing, GitHubProjectDetailsDataSource for on-demand details). This replaces the previous single-phase loading approach and aligns with the web UI's project loading strategy.
- Update projects list to show PROJECT column with owner/name format - Update all CLI command arguments to use owner/name format - Update MCP server tool descriptions to use owner/name format - Add CLI auth support to blob endpoint for spec fetching
- Add getEndpointSlice() to extract single endpoint with all referenced schemas - Update CLI endpoint command with --json and --yaml output options - Update MCP get_endpoint_details to return full endpoint slice
Parse raw spec to extract schema names from $ref paths (e.g., #/components/schemas/Invoice) instead of generating names like Response200 or RequestBody.
- Keeps $ref paths intact instead of inlining everything - Single spec fetch instead of double (raw + dereferenced) - More readable output for LLMs - schema names visible in refs - All referenced schemas still included in output
Output is now a proper OpenAPI spec with: - openapi: "3.0.0" - info with title and version - paths with the single endpoint - components.schemas with referenced schemas LLMs trained on OpenAPI specs will recognize the standard format.
- Add CLI auth to /api/remotes endpoint - Don't cache remote specs (content changes on each fetch) - Fix Set iteration for older TypeScript targets
- Change all commands to use -p/--project, -a/--api-version, -s/--spec - Make version and spec required (no defaults) - Use -a for api-version to avoid clash with commander's -v/--version - Update MCP server tools to match CLI interface
- Add --json and --yaml flags to endpoints, schemas, projects commands - Consistent output format options across all CLI commands
Replace custom table formatting with cli-table3 for proper unicode box-drawing characters and better visual presentation.
- Parameters and responses in endpoint view now use tables - Referenced schemas displayed in a table
- Remove all MCP code (server, tools, API routes) - CLI is preferred - Add CLI auth infrastructure with token auto-refresh using GitHub Apps - Restructure commands to use consistent subcommand pattern: - projects list/get - endpoints list/search/get - schemas list/get - Rename --api-version to --at (-v/--version reserved for CLI version)
- Change /api/cli/auth/status from GET to POST with device_code in body - Add rate limiting (1 request per 5 seconds per IP) with 429 response - Use OS keychain for session storage via keytar with file fallback - File fallback uses restrictive 0o600 permissions
- Show available methods when endpoint path exists but method doesn't - Fix TypeScript union type handling for GitHub App auth response
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add a standalone CLI package for Framna Docs that enables developers to explore OpenAPI specifications from the command line. The CLI provides commands for authentication, listing projects, browsing endpoints and schemas, and exporting specs in multiple formats.
Key features:
projects,endpoints,schemas,spec,cache--json,--yamlMotivation and Context
Provides a CLI alternative to the web interface for developers who prefer terminal workflows. Enables quick API exploration and spec retrieval without leaving the terminal.
Types of changes