@gitpagedocs/cli

The published npm package of the Git Page Docs monorepo (the command it installs is gitpagedocs). It scaffolds the gitpagedocs/ docs contract, generates docs with AI, configures GitHub Pages, and runs the MCP server.

npm install -g @gitpagedocs/cli   # global (installs the `gitpagedocs` command)
gitpagedocs                       # generate gitpagedocs/ config (config-only)

# or one-off, no install:
npx @gitpagedocs/cli

This package ships its TypeScript sources and runs them via tsx; it depends on the workspace packages @gitpagedocs/tools and @gitpagedocs/mcp (published alongside it).

Commands

| Command | Description | |---|---| | gitpagedocs | Generate gitpagedocs/ config + versioned docs (config-only) | | gitpagedocs --layoutconfig | Also emit local layout templates in gitpagedocs/layouts/ | | gitpagedocs --push --owner <o> --repo <r> [--path <sub>] | Generate, configure Pages, create workflow, commit + push | | gitpagedocs --home | Standalone distribution (gitpagedocshome/: static site + .env + Dockerfile) | | gitpagedocs -i / --interactive | Interactive prompts | | gitpagedocs ai | Interactive AI documentation generator — writes pages in the gitpagedocs pattern (see below) | | gitpagedocs provider [id] · models [provider] | List AI providers / catalog models | | gitpagedocs document[:repo\|:file\|:folder] | Generate documentation with AI in the gitpagedocs pattern | | gitpagedocs password | Set a documentation access password (writes the public key to config.json, prints the private key) | | gitpagedocs deploy / pages [actions\|deploy] | Configure GitHub Pages via Actions + push | | gitpagedocs docs | Refresh managed regions of README/CONTRIBUTING/SECURITY | | gitpagedocs doctor · version · update | Diagnostics / version / update hint | | gitpagedocs mcp start | Start the MCP server over stdio |

The AI-CLI implementation lives in cli/ai/ (relocated from the frontend so the published package is self-contained).

CLI Architecture (Clean Architecture + SOLID)

Layer Overview

cli/
|-- index.mjs                          # Node entry (bootstraps TS presentation via tsx)
|-- package.json                       # the published `gitpagedocs` package
|-- ai/                                # AI documentation CLI (provider/model/paths → markdown)
|-- contracts/                         # Stable contracts for external tooling
|   `-- doc-versions.mjs
|
|-- presentation/                      # Interface/composition root
|   |-- index.ts
|   |-- options/
|   `-- ui/
|
|-- application/                       # Use-cases and ports
|   |-- config-only/handler.mjs
|   |-- home/handler.mjs
|   |-- report/config-only-reporter.mjs
|   |-- use-cases/dispatch-mode.ts
|   `-- ports/cli-runtime-ports.ts
|
|-- domain/                            # Business rules
|   `-- services/sanitize-segment.mjs
|
|-- infrastructure/                    # Side effects and adapters
|   |-- config-only/runtime.mjs
|   `-- home/runtime.mjs
|
|-- builders/                          # Pure config builders
|-- data/                              # Constants and metadata
|-- content/                           # Static docs content
|-- runtime/                           # Low-level runtime helpers
`-- home/                              # Home templates/files

SOLID Principles

| Principle | Application | |-----------|-------------| | SRP | application/report only formats messages; handlers only orchestrate | | OCP | New runtime implementations can be injected through ports | | LSP | dispatch-mode works with any runner implementing CliCommandRunner | | ISP | Split runtime contracts (ConfigOnlyRuntimePort, HomeRuntimePort) | | DIP | Use-cases depend on application/ports, not concrete fs/git/exec |

Clean Architecture

• Interfaces/Presentation: parse CLI args, resolve mode, wire dependencies in presentation/index.ts
• Application: orchestrate flows with explicit ports, without direct fs/git/exec imports
• Domain: sanitize and core rules with no infrastructure dependencies
• Infrastructure: concrete adapters for runtime side effects
• Contracts: tools/smoke consumes cli/contracts instead of internal CLI modules

Authorized Routes Pipeline

The CLI now generates authorized-route docs and config entries in PT/EN/ES.

• Source content: cli/content/docs.mjs (authorizedRoutes key per language)
• Route metadata: cli/data/route-metas.mjs (ROUTE_META_ID6)
• Route path mapping: cli/data/path-mappings.mjs (authorized-routes.md)
• Version config composition: cli/builders/version-config-builder.mjs
• Doc key resolution: cli/runtime/doc-path-resolver.mjs

Generated artifacts include:

• gitpagedocs/docs/versions/<version>/config.json with auth and route authorization
• gitpagedocs/docs/versions/<version>/{pt,en,es}/authorized-routes.md
• menus-header-md entry dedicated to Authorized Routes

GitHub Pages Push Paths

• Default project-site publish (--push without --path) targets /<repo>/.
• Custom project subpath publish (--push --path <segment>) targets /<repo>/<segment>/.
• --path accepts a single sanitized segment (letters, numbers, ., _, -).

Example:

npx gitpagedocs --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push

Expected URL after deployment:

https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/

AI CLI (interactive + config file)

The CLI now includes a dedicated interactive AI mode:

npx gitpagedocs ai

What it does

• asks provider (openai, claude, gemini, ollama)
• asks API key or Ollama URL
• asks paths to scan (supports one or many paths, including other repositories)
• generates documentation in pt, en, es in the gitpagedocs pattern
• optionally persists config in .gitpagedocsconfig

gitpagedocs pattern output

The model is given a gitpagedocs-aware system prompt and returns documentation split into pages (delimited by === PAGE: <slug> | <Title> ===). The CLI scaffolds the base gitpagedocs/ structure first, then writes each page to gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md for every language and wires it into that version's config.json (routes-md + menus-header-md) so the pages render in the viewer menu. Entries are tagged aiGenerated and idempotent (re-running replaces them). A later plain gitpagedocs rebuild drops the wiring — re-run gitpagedocs ai to restore.

.gitpagedocsconfig (manual mode)

You can create/edit this file manually and then run npx gitpagedocs ai:

{
	"version": 1,
	"ai": {
		"provider": "openai",
		"model": "gpt-4o-mini",
		"apiKey": "<YOUR_API_KEY>",
		"paths": ["src", "cli", "../another-repo/src"],
		"languages": ["pt", "en", "es"],
		"outputDir": "gitpagedocs/docs",
		"filePrefix": "ai-generated",
		"contextPrompt": "Você é um redator técnico sênior..."
	}
}

For Ollama, use baseUrl instead of apiKey.

Interactive fallback

If a directory is not found, CLI offers fallback choices:

• fix paths and retry
• skip missing paths and continue
• abort safely