diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index cfccfd30..d25bb97b 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -225,7 +225,28 @@ export default defineConfig({ { label: "Reference", items: [ - { label: "CLI Commands", slug: "reference/cli-commands" }, + { + label: "CLI Commands", + items: [ + { label: "Overview", slug: "reference/cli" }, + { label: "archgate login", slug: "reference/cli/login" }, + { label: "archgate init", slug: "reference/cli/init" }, + { label: "archgate plugin", slug: "reference/cli/plugin" }, + { label: "archgate check", slug: "reference/cli/check" }, + { label: "archgate adr", slug: "reference/cli/adr" }, + { + label: "archgate review-context", + slug: "reference/cli/review-context", + }, + { + label: "archgate session-context", + slug: "reference/cli/session-context", + }, + { label: "archgate upgrade", slug: "reference/cli/upgrade" }, + { label: "archgate doctor", slug: "reference/cli/doctor" }, + { label: "archgate clean", slug: "reference/cli/clean" }, + ], + }, { label: "Rule API", slug: "reference/rule-api" }, { label: "ADR Schema", slug: "reference/adr-schema" }, { label: "Telemetry", slug: "reference/telemetry" }, diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 6c5ff751..9edbe975 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -2883,278 +2883,158 @@ ADRs that fail validation are skipped by `archgate check` and reported as errors --- -## Reference: CLI Commands - -Source: https://cli.archgate.dev/reference/cli-commands/ - -## Global options - -These options are available on all commands: - -| Option | Description | -| ----------------- | -------------------------- | -| `--version`, `-V` | Print the Archgate version | -| `--help`, `-h` | Show help for any command | - -```bash -archgate --version -archgate check --help -``` +## Reference: archgate adr ---- +Source: https://cli.archgate.dev/reference/cli/adr/ -## archgate login +## archgate adr create -Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, Copilot CLI, or Cursor), and use case, then registers you before completing the login. +Create a new ADR interactively or via flags. ```bash -archgate login +archgate adr create [options] ``` -Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`. - -If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically. - -Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, etc.) works without login. +When run without `--title` and `--domain`, the command prompts interactively for the domain, title, and optional file patterns. When both `--title` and `--domain` are provided, it runs non-interactively. -Editor plugins are currently in beta. Run `archgate login` to sign up and authenticate. +The ADR ID is auto-generated with the domain prefix and the next available sequence number (e.g., `ARCH-002`, `BE-001`). -### Subcommands +### Options -| Subcommand | Description | -| ------------------------ | ----------------------------------------- | -| `archgate login` | Authenticate (skips if already logged in) | -| `archgate login status` | Show current authentication status | -| `archgate login logout` | Remove stored credentials | -| `archgate login refresh` | Re-authenticate and claim a new token | +| Option | Description | +| -------------------- | --------------------------------------------------------------------- | +| `--title ` | ADR title (skip interactive prompt) | +| `--domain <domain>` | ADR domain (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | File patterns, comma-separated | +| `--body <markdown>` | Full ADR body markdown (skip template) | +| `--rules` | Set `rules: true` in frontmatter | +| `--json` | Output as JSON | ### Examples -Log in for the first time: +Interactive mode: ```bash -archgate login -``` - -``` -Authenticating with GitHub... - -Open https://github.com/login/device in your browser -and enter the code: ABCD-1234 - -Waiting for authorization... -GitHub user: yourname - -Your GitHub account yourname is not yet registered. -Let's sign you up now. - -Email: you@example.com -Editor: Claude Code -Use case: Enforcing ADRs in our monorepo - -Submitting signup request... -Claiming archgate plugin token... - -Authenticated as yourname. Plugin access is now available. -Run `archgate init` to set up a project with the archgate plugin. -``` - -If the project already has `.archgate/adrs/`, the final line reads: - -``` -Run `archgate check` to validate your project against its ADRs. +archgate adr create ``` -### Troubleshooting - -#### TLS/corporate proxy errors - -If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. - -On macOS/Linux: +Non-interactive mode: ```bash -export NODE_EXTRA_CA_CERTS=/path/to/your-corporate-ca.pem -archgate login +archgate adr create \ + --title "API Response Envelope" \ + --domain backend \ + --files "src/api/**/*.ts" \ + --rules ``` -On Windows (PowerShell): +--- -```powershell -$env:NODE_EXTRA_CA_CERTS = "C:\path\to\your-corporate-ca.pem" -archgate login -``` +## archgate adr list -On Windows (cmd): +List all ADRs in the project. -```cmd -set NODE_EXTRA_CA_CERTS=C:\path\to\your-corporate-ca.pem -archgate login +```bash +archgate adr list [options] ``` -On Windows (Git Bash): +### Options -```bash -export NODE_EXTRA_CA_CERTS=/c/path/to/your-corporate-ca.pem -archgate login -``` +| Option | Description | +| ------------------- | ---------------- | +| `--json` | Output as JSON | +| `--domain <domain>` | Filter by domain | -Ask your IT team for the correct certificate path if you are unsure. +### Examples -Check login status: +List all ADRs in table format: ```bash -archgate login status +archgate adr list ``` ``` -Logged in as yourname (since 2026-02-28) -``` - -Log out: - -```bash -archgate login logout +ID Domain Rules Title +──────────────────────────────────────────────────────── +ARCH-001 architecture true Command Structure +ARCH-002 architecture true Error Handling +BE-001 backend true API Response Envelope ``` -Re-authenticate: +List ADRs as JSON: ```bash -archgate login refresh +archgate adr list --json ``` ---- - -## archgate init - -Initialize Archgate governance in the current project. +Filter by domain: ```bash -archgate init [options] -``` - -Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin. - -### Options - -| Option | Default | Description | -| ------------------- | -------- | ------------------------------------------------------------------------- | -| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`) | -| `--install-plugin` | auto | Install the Archgate editor plugin (requires prior `archgate login`) | - -When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise. - -### Plugin installation behavior - -**Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. - -**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. - -### Output - -``` -Initialized Archgate governance in /path/to/project - adrs/ - architecture decision records - lint/ - linter-specific rules - .claude/ - Claude Code settings configured - -Archgate plugin installed for Claude Code. -``` - -When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. - -### Generated structure - -``` -.archgate/ - adrs/ - ARCH-001-example.md # Example ADR - ARCH-001-example.rules.ts # Example rules file - lint/ - archgate.config.ts # Archgate configuration +archgate adr list --domain backend ``` --- -## archgate plugin +## archgate adr show -Manage Archgate editor plugins independently of `archgate init`. +Print a specific ADR by ID. ```bash -archgate plugin <subcommand> [options] +archgate adr show <id> ``` -Use `archgate plugin` to install plugins or retrieve the authenticated repository URL on projects that have already been initialized. - -### Subcommands - -#### archgate plugin url - -Print the plugin repository URL for manual tool configuration. +Prints the full ADR content (frontmatter and body) to stdout. -```bash -archgate plugin url [options] -``` +### Arguments -| Option | Default | Description | -| ------------------- | -------- | ------------------------------------------------------- | -| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | +| Argument | Description | +| -------- | ----------------------------------- | +| `<id>` | ADR ID (e.g., `ARCH-001`, `BE-003`) | -The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code: +### Example ```bash -claude plugin marketplace add "$(archgate plugin url)" -claude plugin install archgate@archgate +archgate adr show ARCH-001 ``` -For VS Code, the URL points to a separate plugin repository: - -```bash -archgate plugin url --editor vscode -``` +--- -#### archgate plugin install +## archgate adr update -Install the Archgate plugin for the specified editor on an already-initialized project. +Update an existing ADR by ID. ```bash -archgate plugin install [options] +archgate adr update --id <id> --body <markdown> [options] ``` -| Option | Default | Description | -| ------------------- | -------- | ------------------------------------------------------- | -| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | - -Installation behavior varies by editor: - -- **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. -- **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. -- **Cursor:** Downloads and extracts the plugin bundle into `.cursor/`. -- **VS Code:** Adds the marketplace URL to VS Code user settings and installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. - -### Examples - -Get the plugin URL for manual configuration: - -```bash -archgate plugin url -``` +Replaces the ADR body with the provided markdown. Frontmatter fields (`--title`, `--domain`, `--files`, `--rules`) are updated only when explicitly passed; otherwise the existing values are preserved. -Install the plugin for Claude Code: +### Options -```bash -archgate plugin install -``` +| Option | Required | Description | +| -------------------- | -------- | --------------------------------------------------------------------- | +| `--id <id>` | Yes | ADR ID to update (e.g., `ARCH-001`) | +| `--body <markdown>` | Yes | Full replacement ADR body markdown | +| `--title <title>` | No | New ADR title (preserves existing if omitted) | +| `--domain <domain>` | No | New domain (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | No | New file patterns, comma-separated (preserves existing if omitted) | +| `--rules` | No | Set `rules: true` in frontmatter | +| `--json` | No | Output as JSON | -Install the plugin for Cursor: +### Example ```bash -archgate plugin install --editor cursor +archgate adr update \ + --id ARCH-001 \ + --title "Updated Command Structure" \ + --body "## Context\n\nUpdated context..." ``` --- -## archgate check +## Reference: archgate check + +Source: https://cli.archgate.dev/reference/cli/check/ Run all automated ADR compliance checks against the codebase. @@ -3164,7 +3044,7 @@ archgate check [options] [files...] Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose `files` patterns match those files are executed. -### Options +## Options | Option | Description | | ------------ | --------------------------------------------------------- | @@ -3174,13 +3054,13 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `. | `--adr <id>` | Only check rules from a specific ADR | | `--verbose` | Show passing rules and timing info | -### Arguments +## Arguments | Argument | Description | | ------------ | --------------------------------------------------------------------------------------------------------------- | | `[files...]` | Optional file paths to scope checks to. Only ADRs whose `files` patterns match will run. Supports stdin piping. | -### Exit codes +## Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------- | @@ -3188,7 +3068,7 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `. | 1 | One or more violations detected. | | 2 | Rule execution error (e.g., malformed rule, security scanner block). | -### Examples +## Examples Check the entire project: @@ -3232,7 +3112,7 @@ Get GitHub Actions annotations: archgate check --ci ``` -### JSON output format +## JSON output format When `--json` is used, the output is a single JSON object: @@ -3272,170 +3152,407 @@ When `--json` is used, the output is a single JSON object: } ``` -#### Violation fields +### Violation fields + +| Field | Type | Description | +| ----------- | ------- | ------------------------------------------------------- | +| `message` | string | What the violation is | +| `file` | string? | Relative file path | +| `line` | number? | Start line (1-based) | +| `endLine` | number? | End line (1-based) -- for precise editor highlighting | +| `endColumn` | number? | End column (0-based) -- for precise editor highlighting | +| `fix` | string? | Suggested fix (guidance only) | +| `severity` | string | `"error"`, `"warning"`, or `"info"` | + +### Blocked rule files + +When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions). + +--- + +## Reference: archgate clean + +Source: https://cli.archgate.dev/reference/cli/clean/ + +Remove the CLI cache directory. + +```bash +archgate clean +``` + +Removes `~/.archgate/`, which stores cached data such as update check timestamps. Safe to run at any time -- the directory is recreated automatically when needed. + +## Example + +```bash +archgate clean +``` + +``` +/home/user/.archgate cleaned up +``` + +--- + +## Reference: archgate doctor + +Source: https://cli.archgate.dev/reference/cli/doctor/ + +Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports. + +```bash +archgate doctor [options] +``` + +## Options + +| Option | Description | +| -------- | ----------------------- | +| `--json` | Machine-readable output | + +## Output sections + +- **System** -- OS, architecture, WSL detection, Bun and Node versions +- **Archgate** -- CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status +- **Project** -- Whether an `.archgate/` project exists, ADR count, domains +- **Editor CLIs** -- Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH +- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) + +## Example + +```bash +archgate doctor +``` + +``` +System + OS: win32/x64 + Bun: 1.3.11 + Node: v24.3.0 + +Archgate + Version: 0.25.1 + Install: binary + Exec path: /home/user/.archgate/bin/archgate + Config dir: /home/user/.archgate OK + Telemetry: enabled + Logged in: yes + +Project + ADRs: 5 (3 with rules) + Domains: ARCH, GEN + +Editor CLIs + claude: OK + cursor: MISSING + code (vscode):OK + copilot: MISSING + git: OK + +Project Integrations + Claude: OK (.claude/settings.local.json) + Cursor: MISSING (.cursor/rules/archgate-governance.mdc) + VS Code: OK (.vscode/settings.json) + Copilot: MISSING (.github/copilot/instructions.md) +``` + +--- + +## Reference: CLI Commands + +Source: https://cli.archgate.dev/reference/cli/ + +## Global options + +These options are available on all commands: + +| Option | Description | +| ----------------- | -------------------------- | +| `--version`, `-V` | Print the Archgate version | +| `--help`, `-h` | Show help for any command | + +```bash +archgate --version +archgate check --help +``` + +## Commands + +| Command | Description | +| ------------------------------------------------ | ----------------------------------------------------- | +| [`archgate login`](./login/) | Authenticate with GitHub | +| [`archgate init`](./init/) | Initialize Archgate governance | +| [`archgate plugin`](./plugin/) | Manage editor plugins | +| [`archgate check`](./check/) | Run ADR compliance checks | +| [`archgate adr`](./adr/) | Create, list, show, and update ADRs | +| [`archgate review-context`](./review-context/) | Pre-compute review context for CI/editor integrations | +| [`archgate session-context`](./session-context/) | Read AI editor session transcripts | +| [`archgate upgrade`](./upgrade/) | Upgrade Archgate to the latest version | +| [`archgate doctor`](./doctor/) | Check system environment and editor integrations | +| [`archgate clean`](./clean/) | Remove the CLI cache directory | + +--- + +## Reference: archgate init + +Source: https://cli.archgate.dev/reference/cli/init/ + +Initialize Archgate governance in the current project. + +```bash +archgate init [options] +``` + +Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin. + +## Options + +| Option | Default | Description | +| ------------------- | -------- | ------------------------------------------------------------------------- | +| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`) | +| `--install-plugin` | auto | Install the Archgate editor plugin (requires prior `archgate login`) | + +When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise. + +## Plugin installation behavior + +**Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. + +**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. + +## Output + +``` +Initialized Archgate governance in /path/to/project + adrs/ - architecture decision records + lint/ - linter-specific rules + .claude/ - Claude Code settings configured + +Archgate plugin installed for Claude Code. +``` + +When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. + +## Generated structure + +``` +.archgate/ + adrs/ + ARCH-001-example.md # Example ADR + ARCH-001-example.rules.ts # Example rules file + lint/ + archgate.config.ts # Archgate configuration +``` + +--- + +## Reference: archgate login + +Source: https://cli.archgate.dev/reference/cli/login/ + +Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, Copilot CLI, or Cursor), and use case, then registers you before completing the login. + +```bash +archgate login +``` + +Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`. + +If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically. + +Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, etc.) works without login. + +Editor plugins are currently in beta. Run `archgate login` to sign up and authenticate. + +## Subcommands + +| Subcommand | Description | +| ------------------------ | ----------------------------------------- | +| `archgate login` | Authenticate (skips if already logged in) | +| `archgate login status` | Show current authentication status | +| `archgate login logout` | Remove stored credentials | +| `archgate login refresh` | Re-authenticate and claim a new token | + +## Examples + +Log in for the first time: + +```bash +archgate login +``` -| Field | Type | Description | -| ----------- | ------- | ------------------------------------------------------ | -| `message` | string | What the violation is | -| `file` | string? | Relative file path | -| `line` | number? | Start line (1-based) | -| `endLine` | number? | End line (1-based) — for precise editor highlighting | -| `endColumn` | number? | End column (0-based) — for precise editor highlighting | -| `fix` | string? | Suggested fix (guidance only) | -| `severity` | string | `"error"`, `"warning"`, or `"info"` | +``` +Authenticating with GitHub... -#### Blocked rule files +Open https://github.com/login/device in your browser +and enter the code: ABCD-1234 -When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions). +Waiting for authorization... +GitHub user: yourname ---- +Your GitHub account yourname is not yet registered. +Let's sign you up now. -## archgate adr create +Email: you@example.com +Editor: Claude Code +Use case: Enforcing ADRs in our monorepo -Create a new ADR interactively or via flags. +Submitting signup request... +Claiming archgate plugin token... -```bash -archgate adr create [options] +Authenticated as yourname. Plugin access is now available. +Run `archgate init` to set up a project with the archgate plugin. ``` -When run without `--title` and `--domain`, the command prompts interactively for the domain, title, and optional file patterns. When both `--title` and `--domain` are provided, it runs non-interactively. +If the project already has `.archgate/adrs/`, the final line reads: -The ADR ID is auto-generated with the domain prefix and the next available sequence number (e.g., `ARCH-002`, `BE-001`). +``` +Run `archgate check` to validate your project against its ADRs. +``` -### Options +## Troubleshooting -| Option | Description | -| -------------------- | --------------------------------------------------------------------- | -| `--title <title>` | ADR title (skip interactive prompt) | -| `--domain <domain>` | ADR domain (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | File patterns, comma-separated | -| `--body <markdown>` | Full ADR body markdown (skip template) | -| `--rules` | Set `rules: true` in frontmatter | -| `--json` | Output as JSON | +### TLS/corporate proxy errors -### Examples +If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. -Interactive mode: +On macOS/Linux: ```bash -archgate adr create +export NODE_EXTRA_CA_CERTS=/path/to/your-corporate-ca.pem +archgate login ``` -Non-interactive mode: +On Windows (PowerShell): -```bash -archgate adr create \ - --title "API Response Envelope" \ - --domain backend \ - --files "src/api/**/*.ts" \ - --rules +```powershell +$env:NODE_EXTRA_CA_CERTS = "C:\path\to\your-corporate-ca.pem" +archgate login ``` ---- +On Windows (cmd): -## archgate adr list +```cmd +set NODE_EXTRA_CA_CERTS=C:\path\to\your-corporate-ca.pem +archgate login +``` -List all ADRs in the project. +On Windows (Git Bash): ```bash -archgate adr list [options] +export NODE_EXTRA_CA_CERTS=/c/path/to/your-corporate-ca.pem +archgate login ``` -### Options - -| Option | Description | -| ------------------- | ---------------- | -| `--json` | Output as JSON | -| `--domain <domain>` | Filter by domain | - -### Examples +Ask your IT team for the correct certificate path if you are unsure. -List all ADRs in table format: +Check login status: ```bash -archgate adr list +archgate login status ``` ``` -ID Domain Rules Title -──────────────────────────────────────────────────────── -ARCH-001 architecture true Command Structure -ARCH-002 architecture true Error Handling -BE-001 backend true API Response Envelope +Logged in as yourname (since 2026-02-28) ``` -List ADRs as JSON: +Log out: ```bash -archgate adr list --json +archgate login logout ``` -Filter by domain: +Re-authenticate: ```bash -archgate adr list --domain backend +archgate login refresh ``` --- -## archgate adr show +## Reference: archgate plugin -Print a specific ADR by ID. +Source: https://cli.archgate.dev/reference/cli/plugin/ + +Manage Archgate editor plugins independently of `archgate init`. ```bash -archgate adr show <id> +archgate plugin <subcommand> [options] ``` -Prints the full ADR content (frontmatter and body) to stdout. +Use `archgate plugin` to install plugins or retrieve the authenticated repository URL on projects that have already been initialized. -### Arguments +## Subcommands -| Argument | Description | -| -------- | ----------------------------------- | -| `<id>` | ADR ID (e.g., `ARCH-001`, `BE-003`) | +### archgate plugin url -### Example +Print the plugin repository URL for manual tool configuration. ```bash -archgate adr show ARCH-001 +archgate plugin url [options] ``` ---- +| Option | Default | Description | +| ------------------- | -------- | ------------------------------------------------------- | +| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | -## archgate adr update +The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code: -Update an existing ADR by ID. +```bash +claude plugin marketplace add "$(archgate plugin url)" +claude plugin install archgate@archgate +``` + +For VS Code, the URL points to a separate plugin repository: ```bash -archgate adr update --id <id> --body <markdown> [options] +archgate plugin url --editor vscode ``` -Replaces the ADR body with the provided markdown. Frontmatter fields (`--title`, `--domain`, `--files`, `--rules`) are updated only when explicitly passed; otherwise the existing values are preserved. +### archgate plugin install -### Options +Install the Archgate plugin for the specified editor on an already-initialized project. -| Option | Required | Description | -| -------------------- | -------- | --------------------------------------------------------------------- | -| `--id <id>` | Yes | ADR ID to update (e.g., `ARCH-001`) | -| `--body <markdown>` | Yes | Full replacement ADR body markdown | -| `--title <title>` | No | New ADR title (preserves existing if omitted) | -| `--domain <domain>` | No | New domain (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | No | New file patterns, comma-separated (preserves existing if omitted) | -| `--rules` | No | Set `rules: true` in frontmatter | -| `--json` | No | Output as JSON | +```bash +archgate plugin install [options] +``` -### Example +| Option | Default | Description | +| ------------------- | -------- | ------------------------------------------------------- | +| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | + +Installation behavior varies by editor: + +- **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. +- **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. +- **Cursor:** Downloads and extracts the plugin bundle into `.cursor/`. +- **VS Code:** Adds the marketplace URL to VS Code user settings and installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. + +## Examples + +Get the plugin URL for manual configuration: ```bash -archgate adr update \ - --id ARCH-001 \ - --title "Updated Command Structure" \ - --body "## Context\n\nUpdated context..." +archgate plugin url +``` + +Install the plugin for Claude Code: + +```bash +archgate plugin install +``` + +Install the plugin for Cursor: + +```bash +archgate plugin install --editor cursor ``` --- -## archgate review-context +## Reference: archgate review-context + +Source: https://cli.archgate.dev/reference/cli/review-context/ Pre-compute review context with ADR briefings for changed files. Designed for CI and editor plugin integrations that need a summary of which ADRs apply to the files being changed. @@ -3443,7 +3560,7 @@ Pre-compute review context with ADR briefings for changed files. Designed for CI archgate review-context [options] ``` -### Options +## Options | Option | Description | | ------------------- | ------------------------------------ | @@ -3451,7 +3568,7 @@ archgate review-context [options] | `--run-checks` | Include ADR compliance check results | | `--domain <domain>` | Filter to a single domain | -### Example +## Example ```bash archgate review-context --staged @@ -3459,7 +3576,9 @@ archgate review-context --staged --- -## archgate session-context +## Reference: archgate session-context + +Source: https://cli.archgate.dev/reference/cli/session-context/ Read AI editor session transcripts for the project. Useful for auditing what an AI agent did during a coding session. @@ -3467,9 +3586,9 @@ Read AI editor session transcripts for the project. Useful for auditing what an archgate session-context <subcommand> [options] ``` -### Subcommands +## Subcommands -#### archgate session-context claude-code +### archgate session-context claude-code Read the Claude Code session transcript for the project. @@ -3481,7 +3600,7 @@ archgate session-context claude-code [options] | ------------------- | ---------------------------------------- | | `--max-entries <n>` | Maximum entries to return (default: 200) | -#### archgate session-context cursor +### archgate session-context cursor Read the Cursor agent session transcript for the project. @@ -3494,7 +3613,7 @@ archgate session-context cursor [options] | `--max-entries <n>` | Maximum entries to return (default: 200) | | `--session-id <id>` | Specific session UUID to read | -### Examples +## Examples Read the latest Claude Code session: @@ -3510,7 +3629,9 @@ archgate session-context cursor --session-id abc123 --- -## archgate upgrade +## Reference: archgate upgrade + +Source: https://cli.archgate.dev/reference/cli/upgrade/ Upgrade Archgate to the latest version via npm. @@ -3520,7 +3641,7 @@ archgate upgrade Checks the npm registry for the latest published version. If a newer version is available, runs `npm install -g archgate@latest` to upgrade. If already up-to-date, prints a message and exits. -### Example +## Example ```bash archgate upgrade @@ -3534,90 +3655,6 @@ Archgate upgraded to 0.4.0 successfully. --- -## archgate doctor - -Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports. - -```bash -archgate doctor [options] -``` - -### Options - -| Option | Description | -| -------- | ----------------------- | -| `--json` | Machine-readable output | - -### Output sections - -- **System** — OS, architecture, WSL detection, Bun and Node versions -- **Archgate** — CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status -- **Project** — Whether an `.archgate/` project exists, ADR count, domains -- **Editor CLIs** — Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH -- **Project Integrations** — Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) - -### Example - -```bash -archgate doctor -``` - -``` -System - OS: win32/x64 - Bun: 1.3.11 - Node: v24.3.0 - -Archgate - Version: 0.25.1 - Install: binary - Exec path: /home/user/.archgate/bin/archgate - Config dir: /home/user/.archgate OK - Telemetry: enabled - Logged in: yes - -Project - ADRs: 5 (3 with rules) - Domains: ARCH, GEN - -Editor CLIs - claude: OK - cursor: MISSING - code (vscode):OK - copilot: MISSING - git: OK - -Project Integrations - Claude: OK (.claude/settings.local.json) - Cursor: MISSING (.cursor/rules/archgate-governance.mdc) - VS Code: OK (.vscode/settings.json) - Copilot: MISSING (.github/copilot/instructions.md) -``` - ---- - -## archgate clean - -Remove the CLI cache directory. - -```bash -archgate clean -``` - -Removes `~/.archgate/`, which stores cached data such as update check timestamps. Safe to run at any time -- the directory is recreated automatically when needed. - -### Example - -```bash -archgate clean -``` - -``` -/home/user/.archgate cleaned up -``` - ---- - ## Reference: Rule API Source: https://cli.archgate.dev/reference/rule-api/ diff --git a/docs/src/content/docs/pt-br/reference/cli-commands.mdx b/docs/src/content/docs/pt-br/reference/cli-commands.mdx deleted file mode 100644 index 4a5dadee..00000000 --- a/docs/src/content/docs/pt-br/reference/cli-commands.mdx +++ /dev/null @@ -1,733 +0,0 @@ ---- -title: Comandos da CLI -description: "Referência completa de todos os comandos da CLI do Archgate: init, check, adr create, adr list, adr show, adr update, login, review-context e mais." ---- - -## Opções globais - -Estas opções estão disponíveis em todos os comandos: - -| Opção | Descrição | -| ----------------- | ---------------------------------- | -| `--version`, `-V` | Exibe a versão do Archgate | -| `--help`, `-h` | Mostra ajuda para qualquer comando | - -```bash -archgate --version -archgate check --help -``` - ---- - -## archgate login - -Autentique-se com o GitHub para acessar os plugins de editor do Archgate. Se você ainda não possui cadastro, a CLI cuida do registro automaticamente -- solicita seu email, preferência de editor (Claude Code, VS Code, Copilot CLI ou Cursor) e caso de uso, e então realiza o cadastro antes de concluir o login. - -```bash -archgate login -``` - -Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. - -Se sua conta do GitHub ainda não estiver cadastrada, a CLI solicita seu email, editor preferido e caso de uso, e realiza o cadastro automaticamente. - -As credenciais são necessárias para instalar plugins de editor via `archgate init --install-plugin`. A CLI em si (check, init, etc.) funciona sem login. - -:::tip[Plugin em beta] -Os plugins de editor estão atualmente em beta. Execute `archgate login` para se cadastrar e autenticar. -::: - -### Subcomandos - -| Subcomando | Descrição | -| ------------------------ | -------------------------------------- | -| `archgate login` | Autenticar (pula se já estiver logado) | -| `archgate login status` | Mostrar o status atual de autenticação | -| `archgate login logout` | Remover credenciais armazenadas | -| `archgate login refresh` | Reautenticar e solicitar um novo token | - -### Exemplos - -Fazer login pela primeira vez: - -```bash -archgate login -``` - -``` -Authenticating with GitHub... - -Open https://github.com/login/device in your browser -and enter the code: ABCD-1234 - -Waiting for authorization... -GitHub user: yourname - -No account found. Let's get you signed up. -Email: you@example.com -Editor: Claude Code -Use case: Enforcing ADRs in our monorepo - -Registering... -Claiming archgate plugin token... - -Authenticated as yourname. Plugin access is now available. -Run `archgate init` to set up a project with the archgate plugin. -``` - -Se o projeto já possuir `.archgate/adrs/`, a última linha exibe: - -``` -Run `archgate check` to validate your project against its ADRs. -``` - -### Solução de problemas - -#### Erros de TLS/proxy corporativo - -Se `archgate login` falhar com um erro de certificado TLS (comum em redes com proxy corporativo), aponte o runtime para o certificado CA da sua organização usando a variável de ambiente `NODE_EXTRA_CA_CERTS`. - -No macOS/Linux: - -```bash -export NODE_EXTRA_CA_CERTS=/caminho/para/seu-ca-corporativo.pem -archgate login -``` - -No Windows (PowerShell): - -```powershell -$env:NODE_EXTRA_CA_CERTS = "C:\caminho\para\seu-ca-corporativo.pem" -archgate login -``` - -No Windows (cmd): - -```cmd -set NODE_EXTRA_CA_CERTS=C:\caminho\para\seu-ca-corporativo.pem -archgate login -``` - -No Windows (Git Bash): - -```bash -export NODE_EXTRA_CA_CERTS=/c/caminho/para/seu-ca-corporativo.pem -archgate login -``` - -Consulte sua equipe de TI para obter o caminho correto do certificado caso tenha dúvidas. - -Verificar o status do login: - -```bash -archgate login status -``` - -``` -Logged in as yourname (since 2026-02-28) -``` - -Fazer logout: - -```bash -archgate login logout -``` - -Reautenticar: - -```bash -archgate login refresh -``` - ---- - -## archgate init - -Inicializa a governança do Archgate no projeto atual. - -```bash -archgate init [options] -``` - -Cria o diretório `.archgate/` com um ADR de exemplo, arquivo de regras complementar e configuração do linter. Opcionalmente configura a integração com o editor para fluxos de trabalho com agentes de IA e instala o plugin de editor do Archgate. - -### Opções - -| Opção | Padrão | Descrição | -| ------------------- | -------- | --------------------------------------------------------------------------- | -| `--editor <editor>` | `claude` | Integração de editor a configurar (`claude`, `cursor`, `vscode`, `copilot`) | -| `--install-plugin` | auto | Instalar o plugin de editor do Archgate (requer `archgate login` prévio) | - -Quando `--install-plugin` é passado, a CLI instala o plugin do Archgate para o editor selecionado. Se a flag for omitida, a CLI faz detecção automática: instala o plugin quando existem credenciais válidas (de um `archgate login` anterior) e pula caso contrário. - -### Comportamento de instalação do plugin - -**Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` não for encontrada, o comando exibe os comandos de instalação manual. - -**Cursor:** O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. - -### Saída - -``` -Initialized Archgate governance in /path/to/project - adrs/ - architecture decision records - lint/ - linter-specific rules - .claude/ - Claude Code settings configured - -Archgate plugin installed for Claude Code. -``` - -Quando `--editor cursor` é usado, a saída mostra `.cursor/` em vez de `.claude/`. - -### Estrutura gerada - -``` -.archgate/ - adrs/ - ARCH-001-example.md # Example ADR - ARCH-001-example.rules.ts # Example rules file - lint/ - archgate.config.ts # Archgate configuration -``` - ---- - -## archgate plugin - -Gerencia os plugins de editor do Archgate independentemente do `archgate init`. - -```bash -archgate plugin <subcomando> [options] -``` - -Use `archgate plugin` para instalar plugins ou obter a URL autenticada do repositório em projetos que já foram inicializados. - -### Subcomandos - -#### archgate plugin url - -Exibe a URL autenticada do repositório de plugins para configuração manual de ferramentas. - -```bash -archgate plugin url [options] -``` - -| Opção | Padrão | Descrição | -| ------------------- | -------- | ----------------------------------------------------- | -| `--editor <editor>` | `claude` | Editor alvo (`claude`, `cursor`, `vscode`, `copilot`) | - -A URL inclui suas credenciais e pode ser usada para configurar manualmente as ferramentas do editor. Por exemplo, para adicionar o marketplace do Archgate no Claude Code: - -```bash -claude plugin marketplace add "$(archgate plugin url)" -claude plugin install archgate@archgate -``` - -Para o VS Code, a URL aponta para um repositório de plugin separado: - -```bash -archgate plugin url --editor vscode -``` - -#### archgate plugin install - -Instala o plugin do Archgate para o editor especificado em um projeto já inicializado. - -```bash -archgate plugin install [options] -``` - -| Opção | Padrão | Descrição | -| ------------------- | -------- | ----------------------------------------------------- | -| `--editor <editor>` | `claude` | Editor alvo (`claude`, `cursor`, `vscode`, `copilot`) | - -O comportamento de instalação varia por editor: - -- **Claude Code:** Instala automaticamente via CLI `claude` se disponível; exibe comandos manuais caso contrário. -- **Copilot CLI:** Instala automaticamente via CLI `copilot` se disponível; exibe comandos manuais caso contrário. -- **Cursor:** Baixa e extrai o pacote do plugin no diretório `.cursor/`. -- **VS Code:** Adiciona a URL do marketplace nas configurações de usuário do VS Code e instala a extensão VS Code (`.vsix`) via CLI `code` se disponível; exibe instruções manuais caso contrário. - -### Exemplos - -Obter a URL do plugin para configuração manual: - -```bash -archgate plugin url -``` - -Instalar o plugin para o Claude Code: - -```bash -archgate plugin install -``` - -Instalar o plugin para o Cursor: - -```bash -archgate plugin install --editor cursor -``` - ---- - -## archgate check - -Executa todas as verificações automatizadas de conformidade com ADRs no codebase. - -```bash -archgate check [options] [files...] -``` - -Carrega cada ADR com `rules: true` no frontmatter, executa o arquivo `.rules.ts` complementar e reporta violações com caminhos de arquivo e números de linha. Quando caminhos de arquivo são fornecidos como argumentos posicionais, apenas ADRs cujos padrões `files` correspondem a esses arquivos são executados. - -### Opções - -| Opção | Descrição | -| ------------ | ---------------------------------------------------------------------- | -| `--staged` | Verificar apenas arquivos no git stage (útil para hooks de pre-commit) | -| `--json` | Saída JSON legível por máquina | -| `--ci` | Formato de anotação do GitHub Actions | -| `--adr <id>` | Verificar apenas regras de um ADR específico | -| `--verbose` | Mostrar regras aprovadas e informações de tempo | - -### Argumentos - -| Argumento | Descrição | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `[files...]` | Caminhos de arquivo opcionais para limitar as verificações. Apenas ADRs cujos padrões `files` correspondem serão executados. Suporta pipe via stdin. | - -### Códigos de saída - -| Código | Significado | -| ------ | ------------------------------------------------------------------------------------ | -| 0 | Todas as regras passaram. Nenhuma violação encontrada. | -| 1 | Uma ou mais violações detectadas. | -| 2 | Erro na execução de regra (ex.: regra malformada, bloqueio do scanner de segurança). | - -### Exemplos - -Verificar o projeto inteiro: - -```bash -archgate check -``` - -Verificar apenas arquivos no stage antes de commitar: - -```bash -archgate check --staged -``` - -Verificar um único ADR: - -```bash -archgate check --adr ARCH-001 -``` - -Verificar arquivos específicos (apenas ADRs correspondentes são executados): - -```bash -archgate check src/foo.ts src/bar.ts -``` - -Pipe do git (verificar apenas arquivos alterados): - -```bash -git diff --name-only | archgate check --json -``` - -Obter saída JSON para integração com CI: - -```bash -archgate check --json -``` - -Obter anotações do GitHub Actions: - -```bash -archgate check --ci -``` - -### Formato da saída JSON - -Quando `--json` é usado, a saída é um único objeto JSON: - -```json -{ - "pass": false, - "total": 4, - "passed": 3, - "failed": 1, - "warnings": 0, - "errors": 1, - "infos": 0, - "ruleErrors": 0, - "truncated": false, - "results": [ - { - "adrId": "ARCH-001", - "ruleId": "register-function-export", - "description": "Command file must export a register*Command function", - "status": "fail", - "totalViolations": 1, - "shownViolations": 1, - "violations": [ - { - "message": "Command file must export a register*Command function", - "file": "src/commands/broken.ts", - "line": 1, - "endLine": 1, - "endColumn": 42, - "severity": "error" - } - ], - "durationMs": 12 - } - ], - "durationMs": 42 -} -``` - -#### Campos de violação - -| Campo | Tipo | Descrição | -| ----------- | ------- | ------------------------------------------------------- | -| `message` | string | Descrição da violação | -| `file` | string? | Caminho relativo do arquivo | -| `line` | number? | Linha inicial (base 1) | -| `endLine` | number? | Linha final (base 1) — para destaque preciso no editor | -| `endColumn` | number? | Coluna final (base 0) — para destaque preciso no editor | -| `fix` | string? | Correção sugerida (apenas orientação) | -| `severity` | string | `"error"`, `"warning"` ou `"info"` | - -#### Arquivos de regra bloqueados - -Quando um arquivo de regra é bloqueado pelo scanner de segurança (ex.: usa `Bun.spawn()`) ou um arquivo `.rules.ts` complementar está ausente, o resultado aparece na saída JSON com `status: "error"` e `ruleId: "security-scan"`. As violações incluem o arquivo e a linha exata do código bloqueado (ou a linha `rules: true` no ADR para arquivos complementares ausentes). - ---- - -## archgate adr create - -Cria um novo ADR interativamente ou via flags. - -```bash -archgate adr create [options] -``` - -Quando executado sem `--title` e `--domain`, o comando solicita interativamente o domínio, título e padrões de arquivo opcionais. Quando ambos `--title` e `--domain` são fornecidos, ele executa de forma não interativa. - -O ID do ADR é gerado automaticamente com o prefixo do domínio e o próximo número de sequência disponível (ex.: `ARCH-002`, `BE-001`). - -### Opções - -| Opção | Descrição | -| -------------------- | ------------------------------------------------------------------------- | -| `--title <title>` | Título do ADR (pula o prompt interativo) | -| `--domain <domain>` | Domínio do ADR (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | Padrões de arquivo, separados por vírgula | -| `--body <markdown>` | Corpo completo do ADR em markdown (pula o template) | -| `--rules` | Define `rules: true` no frontmatter | -| `--json` | Saída como JSON | - -### Exemplos - -Modo interativo: - -```bash -archgate adr create -``` - -Modo não interativo: - -```bash -archgate adr create \ - --title "API Response Envelope" \ - --domain backend \ - --files "src/api/**/*.ts" \ - --rules -``` - ---- - -## archgate adr list - -Lista todos os ADRs do projeto. - -```bash -archgate adr list [options] -``` - -### Opções - -| Opção | Descrição | -| ------------------- | ------------------- | -| `--json` | Saída como JSON | -| `--domain <domain>` | Filtrar por domínio | - -### Exemplos - -Listar todos os ADRs em formato de tabela: - -```bash -archgate adr list -``` - -``` -ID Domain Rules Title -──────────────────────────────────────────────────────── -ARCH-001 architecture true Command Structure -ARCH-002 architecture true Error Handling -BE-001 backend true API Response Envelope -``` - -Listar ADRs como JSON: - -```bash -archgate adr list --json -``` - -Filtrar por domínio: - -```bash -archgate adr list --domain backend -``` - ---- - -## archgate adr show - -Exibe um ADR específico pelo ID. - -```bash -archgate adr show <id> -``` - -Imprime o conteúdo completo do ADR (frontmatter e corpo) na saída padrão. - -### Argumentos - -| Argumento | Descrição | -| --------- | ------------------------------------- | -| `<id>` | ID do ADR (ex.: `ARCH-001`, `BE-003`) | - -### Exemplo - -```bash -archgate adr show ARCH-001 -``` - ---- - -## archgate adr update - -Atualiza um ADR existente pelo ID. - -```bash -archgate adr update --id <id> --body <markdown> [options] -``` - -Substitui o corpo do ADR pelo markdown fornecido. Campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) são atualizados apenas quando passados explicitamente; caso contrário, os valores existentes são preservados. - -### Opções - -| Opção | Obrigatório | Descrição | -| -------------------- | ----------- | ------------------------------------------------------------------------------- | -| `--id <id>` | Sim | ID do ADR a atualizar (ex.: `ARCH-001`) | -| `--body <markdown>` | Sim | Corpo completo do ADR em markdown (substitui o existente) | -| `--title <title>` | Não | Novo título do ADR (preserva o existente se omitido) | -| `--domain <domain>` | Não | Novo domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | Não | Novos padrões de arquivo, separados por vírgula (preserva existente se omitido) | -| `--rules` | Não | Define `rules: true` no frontmatter | -| `--json` | Não | Saída como JSON | - -### Exemplo - -```bash -archgate adr update \ - --id ARCH-001 \ - --title "Updated Command Structure" \ - --body "## Context\n\nUpdated context..." -``` - ---- - -## archgate review-context - -Pré-computa o contexto de revisão com briefings de ADRs para arquivos alterados. Projetado para integrações de CI e plugins de editor que precisam de um resumo de quais ADRs se aplicam aos arquivos sendo alterados. - -```bash -archgate review-context [options] -``` - -### Opções - -| Opção | Descrição | -| ------------------- | ---------------------------------------- | -| `--staged` | Incluir apenas arquivos no git stage | -| `--run-checks` | Incluir resultados de verificação de ADR | -| `--domain <domain>` | Filtrar por um único domínio | - -### Exemplo - -```bash -archgate review-context --staged -``` - ---- - -## archgate session-context - -Lê transcrições de sessão de editores de IA para o projeto. Útil para auditar o que um agente de IA fez durante uma sessão de codificação. - -```bash -archgate session-context <subcomando> [options] -``` - -### Subcomandos - -#### archgate session-context claude-code - -Lê a transcrição de sessão do Claude Code para o projeto. - -```bash -archgate session-context claude-code [options] -``` - -| Opção | Descrição | -| ------------------- | ------------------------------------------- | -| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) | - -#### archgate session-context cursor - -Lê a transcrição de sessão do agente Cursor para o projeto. - -```bash -archgate session-context cursor [options] -``` - -| Opção | Descrição | -| ------------------- | ------------------------------------------- | -| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) | -| `--session-id <id>` | UUID específico da sessão a ser lida | - -### Exemplos - -Ler a última sessão do Claude Code: - -```bash -archgate session-context claude-code -``` - -Ler uma sessão específica do Cursor: - -```bash -archgate session-context cursor --session-id abc123 -``` - ---- - -## archgate upgrade - -Atualiza o Archgate para a versão mais recente via npm. - -```bash -archgate upgrade -``` - -Verifica o registro npm para a versão mais recente publicada. Se uma versão mais nova estiver disponível, executa `npm install -g archgate@latest` para atualizar. Se já estiver atualizado, exibe uma mensagem e encerra. - -### Exemplo - -```bash -archgate upgrade -``` - -``` -Checking for latest Archgate release... -Upgrading 0.3.0 -> 0.4.0... -Archgate upgraded to 0.4.0 successfully. -``` - ---- - -## archgate doctor - -Verifica o ambiente do sistema, o método de instalação e as integrações com editores. Útil para diagnosticar problemas de configuração e compartilhar contexto de depuração em relatórios de bugs. - -```bash -archgate doctor [options] -``` - -### Opções - -| Opção | Descrição | -| -------- | ------------------------- | -| `--json` | Saída legível por máquina | - -### Seções da saída - -- **System** — SO, arquitetura, detecção de WSL, versões do Bun e Node -- **Archgate** — Versão da CLI, método de instalação (binary, proto, local, global-pm), diretório de configuração, status de telemetria e login -- **Project** — Se existe um projeto `.archgate/`, contagem de ADRs, domínios -- **Editor CLIs** — Se `claude`, `cursor`, `code` (VS Code), `copilot` e `git` estão disponíveis no PATH -- **Project Integrations** — Se os arquivos de plugin específicos de cada editor existem no projeto atual (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) - -### Exemplo - -```bash -archgate doctor -``` - -``` -System - OS: win32/x64 - Bun: 1.3.11 - Node: v24.3.0 - -Archgate - Version: 0.25.1 - Install: binary - Exec path: /home/user/.archgate/bin/archgate - Config dir: /home/user/.archgate OK - Telemetry: enabled - Logged in: yes - -Project - ADRs: 5 (3 with rules) - Domains: ARCH, GEN - -Editor CLIs - claude: OK - cursor: MISSING - code (vscode):OK - copilot: MISSING - git: OK - -Project Integrations - Claude: OK (.claude/settings.local.json) - Cursor: MISSING (.cursor/rules/archgate-governance.mdc) - VS Code: OK (.vscode/settings.json) - Copilot: MISSING (.github/copilot/instructions.md) -``` - ---- - -## archgate clean - -Remove o diretório de cache da CLI. - -```bash -archgate clean -``` - -Remove `~/.archgate/`, que armazena dados em cache como timestamps de verificação de atualização. Seguro para executar a qualquer momento -- o diretório é recriado automaticamente quando necessário. - -### Exemplo - -```bash -archgate clean -``` - -``` -/home/user/.archgate cleaned up -``` diff --git a/docs/src/content/docs/pt-br/reference/cli/adr.mdx b/docs/src/content/docs/pt-br/reference/cli/adr.mdx new file mode 100644 index 00000000..7263eea7 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/adr.mdx @@ -0,0 +1,147 @@ +--- +title: archgate adr +description: "Criar, listar, exibir e atualizar Architecture Decision Records." +--- + +## archgate adr create + +Cria um novo ADR interativamente ou via flags. + +```bash +archgate adr create [options] +``` + +Quando executado sem `--title` e `--domain`, o comando solicita interativamente o domínio, título e padrões de arquivo opcionais. Quando ambos `--title` e `--domain` são fornecidos, ele executa de forma não interativa. + +O ID do ADR é gerado automaticamente com o prefixo do domínio e o próximo número de sequência disponível (ex.: `ARCH-002`, `BE-001`). + +### Opções + +| Opção | Descrição | +| -------------------- | ------------------------------------------------------------------------- | +| `--title <title>` | Título do ADR (pula o prompt interativo) | +| `--domain <domain>` | Domínio do ADR (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | Padrões de arquivo, separados por vírgula | +| `--body <markdown>` | Corpo completo do ADR em markdown (pula o template) | +| `--rules` | Define `rules: true` no frontmatter | +| `--json` | Saída como JSON | + +### Exemplos + +Modo interativo: + +```bash +archgate adr create +``` + +Modo não interativo: + +```bash +archgate adr create \ + --title "API Response Envelope" \ + --domain backend \ + --files "src/api/**/*.ts" \ + --rules +``` + +--- + +## archgate adr list + +Lista todos os ADRs do projeto. + +```bash +archgate adr list [options] +``` + +### Opções + +| Opção | Descrição | +| ------------------- | ------------------- | +| `--json` | Saída como JSON | +| `--domain <domain>` | Filtrar por domínio | + +### Exemplos + +Listar todos os ADRs em formato de tabela: + +```bash +archgate adr list +``` + +``` +ID Domain Rules Title +──────────────────────────────────────────────────────── +ARCH-001 architecture true Command Structure +ARCH-002 architecture true Error Handling +BE-001 backend true API Response Envelope +``` + +Listar ADRs como JSON: + +```bash +archgate adr list --json +``` + +Filtrar por domínio: + +```bash +archgate adr list --domain backend +``` + +--- + +## archgate adr show + +Exibe um ADR específico pelo ID. + +```bash +archgate adr show <id> +``` + +Imprime o conteúdo completo do ADR (frontmatter e corpo) na saída padrão. + +### Argumentos + +| Argumento | Descrição | +| --------- | ------------------------------------- | +| `<id>` | ID do ADR (ex.: `ARCH-001`, `BE-003`) | + +### Exemplo + +```bash +archgate adr show ARCH-001 +``` + +--- + +## archgate adr update + +Atualiza um ADR existente pelo ID. + +```bash +archgate adr update --id <id> --body <markdown> [options] +``` + +Substitui o corpo do ADR pelo markdown fornecido. Campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) são atualizados apenas quando passados explicitamente; caso contrário, os valores existentes são preservados. + +### Opções + +| Opção | Obrigatório | Descrição | +| -------------------- | ----------- | ------------------------------------------------------------------------------- | +| `--id <id>` | Sim | ID do ADR a atualizar (ex.: `ARCH-001`) | +| `--body <markdown>` | Sim | Corpo completo do ADR em markdown (substitui o existente) | +| `--title <title>` | Não | Novo título do ADR (preserva o existente se omitido) | +| `--domain <domain>` | Não | Novo domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | Não | Novos padrões de arquivo, separados por vírgula (preserva existente se omitido) | +| `--rules` | Não | Define `rules: true` no frontmatter | +| `--json` | Não | Saída como JSON | + +### Exemplo + +```bash +archgate adr update \ + --id ARCH-001 \ + --title "Updated Command Structure" \ + --body "## Context\n\nUpdated context..." +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/check.mdx b/docs/src/content/docs/pt-br/reference/cli/check.mdx new file mode 100644 index 00000000..c31bbc46 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/check.mdx @@ -0,0 +1,136 @@ +--- +title: archgate check +description: "Executa todas as verificações automatizadas de conformidade com ADRs no codebase." +--- + +Executa todas as verificações automatizadas de conformidade com ADRs no codebase. + +```bash +archgate check [options] [files...] +``` + +Carrega cada ADR com `rules: true` no frontmatter, executa o arquivo `.rules.ts` complementar e reporta violações com caminhos de arquivo e números de linha. Quando caminhos de arquivo são fornecidos como argumentos posicionais, apenas ADRs cujos padrões `files` correspondem a esses arquivos são executados. + +## Opções + +| Opção | Descrição | +| ------------ | ---------------------------------------------------------------------- | +| `--staged` | Verificar apenas arquivos no git stage (útil para hooks de pre-commit) | +| `--json` | Saída JSON legível por máquina | +| `--ci` | Formato de anotação do GitHub Actions | +| `--adr <id>` | Verificar apenas regras de um ADR específico | +| `--verbose` | Mostrar regras aprovadas e informações de tempo | + +## Argumentos + +| Argumento | Descrição | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `[files...]` | Caminhos de arquivo opcionais para limitar as verificações. Apenas ADRs cujos padrões `files` correspondem serão executados. Suporta pipe via stdin. | + +## Códigos de saída + +| Código | Significado | +| ------ | ------------------------------------------------------------------------------------ | +| 0 | Todas as regras passaram. Nenhuma violação encontrada. | +| 1 | Uma ou mais violações detectadas. | +| 2 | Erro na execução de regra (ex.: regra malformada, bloqueio do scanner de segurança). | + +## Exemplos + +Verificar o projeto inteiro: + +```bash +archgate check +``` + +Verificar apenas arquivos no stage antes de commitar: + +```bash +archgate check --staged +``` + +Verificar um único ADR: + +```bash +archgate check --adr ARCH-001 +``` + +Verificar arquivos específicos (apenas ADRs correspondentes são executados): + +```bash +archgate check src/foo.ts src/bar.ts +``` + +Pipe do git (verificar apenas arquivos alterados): + +```bash +git diff --name-only | archgate check --json +``` + +Obter saída JSON para integração com CI: + +```bash +archgate check --json +``` + +Obter anotações do GitHub Actions: + +```bash +archgate check --ci +``` + +## Formato da saída JSON + +Quando `--json` é usado, a saída é um único objeto JSON: + +```json +{ + "pass": false, + "total": 4, + "passed": 3, + "failed": 1, + "warnings": 0, + "errors": 1, + "infos": 0, + "ruleErrors": 0, + "truncated": false, + "results": [ + { + "adrId": "ARCH-001", + "ruleId": "register-function-export", + "description": "Command file must export a register*Command function", + "status": "fail", + "totalViolations": 1, + "shownViolations": 1, + "violations": [ + { + "message": "Command file must export a register*Command function", + "file": "src/commands/broken.ts", + "line": 1, + "endLine": 1, + "endColumn": 42, + "severity": "error" + } + ], + "durationMs": 12 + } + ], + "durationMs": 42 +} +``` + +### Campos de violação + +| Campo | Tipo | Descrição | +| ----------- | ------- | -------------------------------------------------------- | +| `message` | string | Descrição da violação | +| `file` | string? | Caminho relativo do arquivo | +| `line` | number? | Linha inicial (base 1) | +| `endLine` | number? | Linha final (base 1) -- para destaque preciso no editor | +| `endColumn` | number? | Coluna final (base 0) -- para destaque preciso no editor | +| `fix` | string? | Correção sugerida (apenas orientação) | +| `severity` | string | `"error"`, `"warning"` ou `"info"` | + +### Arquivos de regra bloqueados + +Quando um arquivo de regra é bloqueado pelo scanner de segurança (ex.: usa `Bun.spawn()`) ou um arquivo `.rules.ts` complementar está ausente, o resultado aparece na saída JSON com `status: "error"` e `ruleId: "security-scan"`. As violações incluem o arquivo e a linha exata do código bloqueado (ou a linha `rules: true` no ADR para arquivos complementares ausentes). diff --git a/docs/src/content/docs/pt-br/reference/cli/clean.mdx b/docs/src/content/docs/pt-br/reference/cli/clean.mdx new file mode 100644 index 00000000..4dd5ad6c --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/clean.mdx @@ -0,0 +1,22 @@ +--- +title: archgate clean +description: "Remove o diretório de cache da CLI." +--- + +Remove o diretório de cache da CLI. + +```bash +archgate clean +``` + +Remove `~/.archgate/`, que armazena dados em cache como timestamps de verificação de atualização. Seguro para executar a qualquer momento -- o diretório é recriado automaticamente quando necessário. + +## Exemplo + +```bash +archgate clean +``` + +``` +/home/user/.archgate cleaned up +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/doctor.mdx b/docs/src/content/docs/pt-br/reference/cli/doctor.mdx new file mode 100644 index 00000000..64b4d762 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/doctor.mdx @@ -0,0 +1,62 @@ +--- +title: archgate doctor +description: "Verifica o ambiente do sistema, o método de instalação e as integrações com editores." +--- + +Verifica o ambiente do sistema, o método de instalação e as integrações com editores. Útil para diagnosticar problemas de configuração e compartilhar contexto de depuração em relatórios de bugs. + +```bash +archgate doctor [options] +``` + +## Opções + +| Opção | Descrição | +| -------- | ------------------------- | +| `--json` | Saída legível por máquina | + +## Seções da saída + +- **System** -- SO, arquitetura, detecção de WSL, versões do Bun e Node +- **Archgate** -- Versão da CLI, método de instalação (binary, proto, local, global-pm), diretório de configuração, status de telemetria e login +- **Project** -- Se existe um projeto `.archgate/`, contagem de ADRs, domínios +- **Editor CLIs** -- Se `claude`, `cursor`, `code` (VS Code), `copilot` e `git` estão disponíveis no PATH +- **Project Integrations** -- Se os arquivos de plugin específicos de cada editor existem no projeto atual (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) + +## Exemplo + +```bash +archgate doctor +``` + +``` +System + OS: win32/x64 + Bun: 1.3.11 + Node: v24.3.0 + +Archgate + Version: 0.25.1 + Install: binary + Exec path: /home/user/.archgate/bin/archgate + Config dir: /home/user/.archgate OK + Telemetry: enabled + Logged in: yes + +Project + ADRs: 5 (3 with rules) + Domains: ARCH, GEN + +Editor CLIs + claude: OK + cursor: MISSING + code (vscode):OK + copilot: MISSING + git: OK + +Project Integrations + Claude: OK (.claude/settings.local.json) + Cursor: MISSING (.cursor/rules/archgate-governance.mdc) + VS Code: OK (.vscode/settings.json) + Copilot: MISSING (.github/copilot/instructions.md) +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/index.mdx b/docs/src/content/docs/pt-br/reference/cli/index.mdx new file mode 100644 index 00000000..a36096fe --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/index.mdx @@ -0,0 +1,33 @@ +--- +title: Comandos da CLI +description: "Referência completa de todos os comandos da CLI do Archgate: init, check, adr, login, plugin, review-context, session-context, upgrade, doctor, clean e telemetria." +--- + +## Opções globais + +Estas opções estão disponíveis em todos os comandos: + +| Opção | Descrição | +| ----------------- | ---------------------------------- | +| `--version`, `-V` | Exibe a versão do Archgate | +| `--help`, `-h` | Mostra ajuda para qualquer comando | + +```bash +archgate --version +archgate check --help +``` + +## Comandos + +| Comando | Descrição | +| ------------------------------------------------ | -------------------------------------------------------- | +| [`archgate login`](./login/) | Autenticar com o GitHub | +| [`archgate init`](./init/) | Inicializar a governança do Archgate | +| [`archgate plugin`](./plugin/) | Gerenciar plugins de editor | +| [`archgate check`](./check/) | Executar verificações de conformidade com ADRs | +| [`archgate adr`](./adr/) | Criar, listar, exibir e atualizar ADRs | +| [`archgate review-context`](./review-context/) | Pré-computar contexto de revisão para CI/integrações | +| [`archgate session-context`](./session-context/) | Ler transcrições de sessão de editores de IA | +| [`archgate upgrade`](./upgrade/) | Atualizar o Archgate para a versão mais recente | +| [`archgate doctor`](./doctor/) | Verificar ambiente do sistema e integrações com editores | +| [`archgate clean`](./clean/) | Remover o diretório de cache da CLI | diff --git a/docs/src/content/docs/pt-br/reference/cli/init.mdx b/docs/src/content/docs/pt-br/reference/cli/init.mdx new file mode 100644 index 00000000..ea022454 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/init.mdx @@ -0,0 +1,51 @@ +--- +title: archgate init +description: "Inicializa a governança do Archgate no projeto atual." +--- + +Inicializa a governança do Archgate no projeto atual. + +```bash +archgate init [options] +``` + +Cria o diretório `.archgate/` com um ADR de exemplo, arquivo de regras complementar e configuração do linter. Opcionalmente configura a integração com o editor para fluxos de trabalho com agentes de IA e instala o plugin de editor do Archgate. + +## Opções + +| Opção | Padrão | Descrição | +| ------------------- | -------- | --------------------------------------------------------------------------- | +| `--editor <editor>` | `claude` | Integração de editor a configurar (`claude`, `cursor`, `vscode`, `copilot`) | +| `--install-plugin` | auto | Instalar o plugin de editor do Archgate (requer `archgate login` prévio) | + +Quando `--install-plugin` é passado, a CLI instala o plugin do Archgate para o editor selecionado. Se a flag for omitida, a CLI faz detecção automática: instala o plugin quando existem credenciais válidas (de um `archgate login` anterior) e pula caso contrário. + +## Comportamento de instalação do plugin + +**Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` não for encontrada, o comando exibe os comandos de instalação manual. + +**Cursor:** O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. + +## Saída + +``` +Initialized Archgate governance in /path/to/project + adrs/ - architecture decision records + lint/ - linter-specific rules + .claude/ - Claude Code settings configured + +Archgate plugin installed for Claude Code. +``` + +Quando `--editor cursor` é usado, a saída mostra `.cursor/` em vez de `.claude/`. + +## Estrutura gerada + +``` +.archgate/ + adrs/ + ARCH-001-example.md # Example ADR + ARCH-001-example.rules.ts # Example rules file + lint/ + archgate.config.ts # Archgate configuration +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/login.mdx b/docs/src/content/docs/pt-br/reference/cli/login.mdx new file mode 100644 index 00000000..32faa0ca --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/login.mdx @@ -0,0 +1,122 @@ +--- +title: archgate login +description: "Autentique-se com o GitHub para acessar os plugins de editor do Archgate." +--- + +Autentique-se com o GitHub para acessar os plugins de editor do Archgate. Se você ainda não possui cadastro, a CLI cuida do registro automaticamente -- solicita seu email, preferência de editor (Claude Code, VS Code, Copilot CLI ou Cursor) e caso de uso, e então realiza o cadastro antes de concluir o login. + +```bash +archgate login +``` + +Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. + +Se sua conta do GitHub ainda não estiver cadastrada, a CLI solicita seu email, editor preferido e caso de uso, e realiza o cadastro automaticamente. + +As credenciais são necessárias para instalar plugins de editor via `archgate init --install-plugin`. A CLI em si (check, init, etc.) funciona sem login. + +:::tip[Plugin em beta] +Os plugins de editor estão atualmente em beta. Execute `archgate login` para se cadastrar e autenticar. +::: + +## Subcomandos + +| Subcomando | Descrição | +| ------------------------ | -------------------------------------- | +| `archgate login` | Autenticar (pula se já estiver logado) | +| `archgate login status` | Mostrar o status atual de autenticação | +| `archgate login logout` | Remover credenciais armazenadas | +| `archgate login refresh` | Reautenticar e solicitar um novo token | + +## Exemplos + +Fazer login pela primeira vez: + +```bash +archgate login +``` + +``` +Authenticating with GitHub... + +Open https://github.com/login/device in your browser +and enter the code: ABCD-1234 + +Waiting for authorization... +GitHub user: yourname + +No account found. Let's get you signed up. +Email: you@example.com +Editor: Claude Code +Use case: Enforcing ADRs in our monorepo + +Registering... +Claiming archgate plugin token... + +Authenticated as yourname. Plugin access is now available. +Run `archgate init` to set up a project with the archgate plugin. +``` + +Se o projeto já possuir `.archgate/adrs/`, a última linha exibe: + +``` +Run `archgate check` to validate your project against its ADRs. +``` + +## Solução de problemas + +### Erros de TLS/proxy corporativo + +Se `archgate login` falhar com um erro de certificado TLS (comum em redes com proxy corporativo), aponte o runtime para o certificado CA da sua organização usando a variável de ambiente `NODE_EXTRA_CA_CERTS`. + +No macOS/Linux: + +```bash +export NODE_EXTRA_CA_CERTS=/caminho/para/seu-ca-corporativo.pem +archgate login +``` + +No Windows (PowerShell): + +```powershell +$env:NODE_EXTRA_CA_CERTS = "C:\caminho\para\seu-ca-corporativo.pem" +archgate login +``` + +No Windows (cmd): + +```cmd +set NODE_EXTRA_CA_CERTS=C:\caminho\para\seu-ca-corporativo.pem +archgate login +``` + +No Windows (Git Bash): + +```bash +export NODE_EXTRA_CA_CERTS=/c/caminho/para/seu-ca-corporativo.pem +archgate login +``` + +Consulte sua equipe de TI para obter o caminho correto do certificado caso tenha dúvidas. + +Verificar o status do login: + +```bash +archgate login status +``` + +``` +Logged in as yourname (since 2026-02-28) +``` + +Fazer logout: + +```bash +archgate login logout +``` + +Reautenticar: + +```bash +archgate login refresh +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx new file mode 100644 index 00000000..f6e0e85e --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx @@ -0,0 +1,78 @@ +--- +title: archgate plugin +description: "Gerencia os plugins de editor do Archgate independentemente do archgate init." +--- + +Gerencia os plugins de editor do Archgate independentemente do `archgate init`. + +```bash +archgate plugin <subcomando> [options] +``` + +Use `archgate plugin` para instalar plugins ou obter a URL autenticada do repositório em projetos que já foram inicializados. + +## Subcomandos + +### archgate plugin url + +Exibe a URL do repositório de plugins para configuração manual de ferramentas. + +```bash +archgate plugin url [options] +``` + +| Opção | Padrão | Descrição | +| ------------------- | -------- | ----------------------------------------------------- | +| `--editor <editor>` | `claude` | Editor alvo (`claude`, `cursor`, `vscode`, `copilot`) | + +A URL pode ser usada para configurar manualmente as ferramentas do editor. As credenciais são fornecidas automaticamente pelo seu gerenciador de credenciais git (armazenadas durante `archgate login`). Por exemplo, para adicionar o marketplace do Archgate no Claude Code: + +```bash +claude plugin marketplace add "$(archgate plugin url)" +claude plugin install archgate@archgate +``` + +Para o VS Code, a URL aponta para um repositório de plugin separado: + +```bash +archgate plugin url --editor vscode +``` + +### archgate plugin install + +Instala o plugin do Archgate para o editor especificado em um projeto já inicializado. + +```bash +archgate plugin install [options] +``` + +| Opção | Padrão | Descrição | +| ------------------- | -------- | ----------------------------------------------------- | +| `--editor <editor>` | `claude` | Editor alvo (`claude`, `cursor`, `vscode`, `copilot`) | + +O comportamento de instalação varia por editor: + +- **Claude Code:** Instala automaticamente via CLI `claude` se disponível; exibe comandos manuais caso contrário. +- **Copilot CLI:** Instala automaticamente via CLI `copilot` se disponível; exibe comandos manuais caso contrário. +- **Cursor:** Baixa e extrai o pacote do plugin no diretório `.cursor/`. +- **VS Code:** Adiciona a URL do marketplace nas configurações de usuário do VS Code e instala a extensão VS Code (`.vsix`) via CLI `code` se disponível; exibe instruções manuais caso contrário. + +## Exemplos + +Obter a URL do plugin para configuração manual: + +```bash +archgate plugin url +``` + +Instalar o plugin para o Claude Code: + +```bash +archgate plugin install +``` + +Instalar o plugin para o Cursor: + +```bash +archgate plugin install --editor cursor +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/review-context.mdx b/docs/src/content/docs/pt-br/reference/cli/review-context.mdx new file mode 100644 index 00000000..0ef6e9ed --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/review-context.mdx @@ -0,0 +1,24 @@ +--- +title: archgate review-context +description: "Pré-computa o contexto de revisão com briefings de ADRs para arquivos alterados." +--- + +Pré-computa o contexto de revisão com briefings de ADRs para arquivos alterados. Projetado para integrações de CI e plugins de editor que precisam de um resumo de quais ADRs se aplicam aos arquivos sendo alterados. + +```bash +archgate review-context [options] +``` + +## Opções + +| Opção | Descrição | +| ------------------- | ---------------------------------------- | +| `--staged` | Incluir apenas arquivos no git stage | +| `--run-checks` | Incluir resultados de verificação de ADR | +| `--domain <domain>` | Filtrar por um único domínio | + +## Exemplo + +```bash +archgate review-context --staged +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/session-context.mdx b/docs/src/content/docs/pt-br/reference/cli/session-context.mdx new file mode 100644 index 00000000..b6f0fab5 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/session-context.mdx @@ -0,0 +1,51 @@ +--- +title: archgate session-context +description: "Lê transcrições de sessão de editores de IA para o projeto." +--- + +Lê transcrições de sessão de editores de IA para o projeto. Útil para auditar o que um agente de IA fez durante uma sessão de codificação. + +```bash +archgate session-context <subcomando> [options] +``` + +## Subcomandos + +### archgate session-context claude-code + +Lê a transcrição de sessão do Claude Code para o projeto. + +```bash +archgate session-context claude-code [options] +``` + +| Opção | Descrição | +| ------------------- | ------------------------------------------- | +| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) | + +### archgate session-context cursor + +Lê a transcrição de sessão do agente Cursor para o projeto. + +```bash +archgate session-context cursor [options] +``` + +| Opção | Descrição | +| ------------------- | ------------------------------------------- | +| `--max-entries <n>` | Máximo de entradas a retornar (padrão: 200) | +| `--session-id <id>` | UUID específico da sessão a ser lida | + +## Exemplos + +Ler a última sessão do Claude Code: + +```bash +archgate session-context claude-code +``` + +Ler uma sessão específica do Cursor: + +```bash +archgate session-context cursor --session-id abc123 +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx b/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx new file mode 100644 index 00000000..03fcc3ac --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx @@ -0,0 +1,24 @@ +--- +title: archgate upgrade +description: "Atualiza o Archgate para a versão mais recente via npm." +--- + +Atualiza o Archgate para a versão mais recente via npm. + +```bash +archgate upgrade +``` + +Verifica o registro npm para a versão mais recente publicada. Se uma versão mais nova estiver disponível, executa `npm install -g archgate@latest` para atualizar. Se já estiver atualizado, exibe uma mensagem e encerra. + +## Exemplo + +```bash +archgate upgrade +``` + +``` +Checking for latest Archgate release... +Upgrading 0.3.0 -> 0.4.0... +Archgate upgraded to 0.4.0 successfully. +``` diff --git a/docs/src/content/docs/reference/cli-commands.mdx b/docs/src/content/docs/reference/cli-commands.mdx deleted file mode 100644 index afe93385..00000000 --- a/docs/src/content/docs/reference/cli-commands.mdx +++ /dev/null @@ -1,735 +0,0 @@ ---- -title: CLI Commands -description: "Complete reference for all Archgate CLI commands: init, check, adr, login, plugin, review-context, session-context, upgrade, doctor, clean, and telemetry." ---- - -## Global options - -These options are available on all commands: - -| Option | Description | -| ----------------- | -------------------------- | -| `--version`, `-V` | Print the Archgate version | -| `--help`, `-h` | Show help for any command | - -```bash -archgate --version -archgate check --help -``` - ---- - -## archgate login - -Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, Copilot CLI, or Cursor), and use case, then registers you before completing the login. - -```bash -archgate login -``` - -Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`. - -If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically. - -Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, etc.) works without login. - -:::tip[Plugin beta] -Editor plugins are currently in beta. Run `archgate login` to sign up and authenticate. -::: - -### Subcommands - -| Subcommand | Description | -| ------------------------ | ----------------------------------------- | -| `archgate login` | Authenticate (skips if already logged in) | -| `archgate login status` | Show current authentication status | -| `archgate login logout` | Remove stored credentials | -| `archgate login refresh` | Re-authenticate and claim a new token | - -### Examples - -Log in for the first time: - -```bash -archgate login -``` - -``` -Authenticating with GitHub... - -Open https://github.com/login/device in your browser -and enter the code: ABCD-1234 - -Waiting for authorization... -GitHub user: yourname - -Your GitHub account yourname is not yet registered. -Let's sign you up now. - -Email: you@example.com -Editor: Claude Code -Use case: Enforcing ADRs in our monorepo - -Submitting signup request... -Claiming archgate plugin token... - -Authenticated as yourname. Plugin access is now available. -Run `archgate init` to set up a project with the archgate plugin. -``` - -If the project already has `.archgate/adrs/`, the final line reads: - -``` -Run `archgate check` to validate your project against its ADRs. -``` - -### Troubleshooting - -#### TLS/corporate proxy errors - -If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. - -On macOS/Linux: - -```bash -export NODE_EXTRA_CA_CERTS=/path/to/your-corporate-ca.pem -archgate login -``` - -On Windows (PowerShell): - -```powershell -$env:NODE_EXTRA_CA_CERTS = "C:\path\to\your-corporate-ca.pem" -archgate login -``` - -On Windows (cmd): - -```cmd -set NODE_EXTRA_CA_CERTS=C:\path\to\your-corporate-ca.pem -archgate login -``` - -On Windows (Git Bash): - -```bash -export NODE_EXTRA_CA_CERTS=/c/path/to/your-corporate-ca.pem -archgate login -``` - -Ask your IT team for the correct certificate path if you are unsure. - -Check login status: - -```bash -archgate login status -``` - -``` -Logged in as yourname (since 2026-02-28) -``` - -Log out: - -```bash -archgate login logout -``` - -Re-authenticate: - -```bash -archgate login refresh -``` - ---- - -## archgate init - -Initialize Archgate governance in the current project. - -```bash -archgate init [options] -``` - -Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin. - -### Options - -| Option | Default | Description | -| ------------------- | -------- | ------------------------------------------------------------------------- | -| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`) | -| `--install-plugin` | auto | Install the Archgate editor plugin (requires prior `archgate login`) | - -When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise. - -### Plugin installation behavior - -**Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. - -**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. - -### Output - -``` -Initialized Archgate governance in /path/to/project - adrs/ - architecture decision records - lint/ - linter-specific rules - .claude/ - Claude Code settings configured - -Archgate plugin installed for Claude Code. -``` - -When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. - -### Generated structure - -``` -.archgate/ - adrs/ - ARCH-001-example.md # Example ADR - ARCH-001-example.rules.ts # Example rules file - lint/ - archgate.config.ts # Archgate configuration -``` - ---- - -## archgate plugin - -Manage Archgate editor plugins independently of `archgate init`. - -```bash -archgate plugin <subcommand> [options] -``` - -Use `archgate plugin` to install plugins or retrieve the authenticated repository URL on projects that have already been initialized. - -### Subcommands - -#### archgate plugin url - -Print the plugin repository URL for manual tool configuration. - -```bash -archgate plugin url [options] -``` - -| Option | Default | Description | -| ------------------- | -------- | ------------------------------------------------------- | -| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | - -The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code: - -```bash -claude plugin marketplace add "$(archgate plugin url)" -claude plugin install archgate@archgate -``` - -For VS Code, the URL points to a separate plugin repository: - -```bash -archgate plugin url --editor vscode -``` - -#### archgate plugin install - -Install the Archgate plugin for the specified editor on an already-initialized project. - -```bash -archgate plugin install [options] -``` - -| Option | Default | Description | -| ------------------- | -------- | ------------------------------------------------------- | -| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | - -Installation behavior varies by editor: - -- **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. -- **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. -- **Cursor:** Downloads and extracts the plugin bundle into `.cursor/`. -- **VS Code:** Adds the marketplace URL to VS Code user settings and installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. - -### Examples - -Get the plugin URL for manual configuration: - -```bash -archgate plugin url -``` - -Install the plugin for Claude Code: - -```bash -archgate plugin install -``` - -Install the plugin for Cursor: - -```bash -archgate plugin install --editor cursor -``` - ---- - -## archgate check - -Run all automated ADR compliance checks against the codebase. - -```bash -archgate check [options] [files...] -``` - -Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose `files` patterns match those files are executed. - -### Options - -| Option | Description | -| ------------ | --------------------------------------------------------- | -| `--staged` | Only check git-staged files (useful for pre-commit hooks) | -| `--json` | Machine-readable JSON output | -| `--ci` | GitHub Actions annotation format | -| `--adr <id>` | Only check rules from a specific ADR | -| `--verbose` | Show passing rules and timing info | - -### Arguments - -| Argument | Description | -| ------------ | --------------------------------------------------------------------------------------------------------------- | -| `[files...]` | Optional file paths to scope checks to. Only ADRs whose `files` patterns match will run. Supports stdin piping. | - -### Exit codes - -| Code | Meaning | -| ---- | -------------------------------------------------------------------- | -| 0 | All rules pass. No violations found. | -| 1 | One or more violations detected. | -| 2 | Rule execution error (e.g., malformed rule, security scanner block). | - -### Examples - -Check the entire project: - -```bash -archgate check -``` - -Check only staged files before committing: - -```bash -archgate check --staged -``` - -Check a single ADR: - -```bash -archgate check --adr ARCH-001 -``` - -Check specific files (only matching ADRs run): - -```bash -archgate check src/foo.ts src/bar.ts -``` - -Pipe from git (check only changed files): - -```bash -git diff --name-only | archgate check --json -``` - -Get JSON output for CI integration: - -```bash -archgate check --json -``` - -Get GitHub Actions annotations: - -```bash -archgate check --ci -``` - -### JSON output format - -When `--json` is used, the output is a single JSON object: - -```json -{ - "pass": false, - "total": 4, - "passed": 3, - "failed": 1, - "warnings": 0, - "errors": 1, - "infos": 0, - "ruleErrors": 0, - "truncated": false, - "results": [ - { - "adrId": "ARCH-001", - "ruleId": "register-function-export", - "description": "Command file must export a register*Command function", - "status": "fail", - "totalViolations": 1, - "shownViolations": 1, - "violations": [ - { - "message": "Command file must export a register*Command function", - "file": "src/commands/broken.ts", - "line": 1, - "endLine": 1, - "endColumn": 42, - "severity": "error" - } - ], - "durationMs": 12 - } - ], - "durationMs": 42 -} -``` - -#### Violation fields - -| Field | Type | Description | -| ----------- | ------- | ------------------------------------------------------ | -| `message` | string | What the violation is | -| `file` | string? | Relative file path | -| `line` | number? | Start line (1-based) | -| `endLine` | number? | End line (1-based) — for precise editor highlighting | -| `endColumn` | number? | End column (0-based) — for precise editor highlighting | -| `fix` | string? | Suggested fix (guidance only) | -| `severity` | string | `"error"`, `"warning"`, or `"info"` | - -#### Blocked rule files - -When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions). - ---- - -## archgate adr create - -Create a new ADR interactively or via flags. - -```bash -archgate adr create [options] -``` - -When run without `--title` and `--domain`, the command prompts interactively for the domain, title, and optional file patterns. When both `--title` and `--domain` are provided, it runs non-interactively. - -The ADR ID is auto-generated with the domain prefix and the next available sequence number (e.g., `ARCH-002`, `BE-001`). - -### Options - -| Option | Description | -| -------------------- | --------------------------------------------------------------------- | -| `--title <title>` | ADR title (skip interactive prompt) | -| `--domain <domain>` | ADR domain (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | File patterns, comma-separated | -| `--body <markdown>` | Full ADR body markdown (skip template) | -| `--rules` | Set `rules: true` in frontmatter | -| `--json` | Output as JSON | - -### Examples - -Interactive mode: - -```bash -archgate adr create -``` - -Non-interactive mode: - -```bash -archgate adr create \ - --title "API Response Envelope" \ - --domain backend \ - --files "src/api/**/*.ts" \ - --rules -``` - ---- - -## archgate adr list - -List all ADRs in the project. - -```bash -archgate adr list [options] -``` - -### Options - -| Option | Description | -| ------------------- | ---------------- | -| `--json` | Output as JSON | -| `--domain <domain>` | Filter by domain | - -### Examples - -List all ADRs in table format: - -```bash -archgate adr list -``` - -``` -ID Domain Rules Title -──────────────────────────────────────────────────────── -ARCH-001 architecture true Command Structure -ARCH-002 architecture true Error Handling -BE-001 backend true API Response Envelope -``` - -List ADRs as JSON: - -```bash -archgate adr list --json -``` - -Filter by domain: - -```bash -archgate adr list --domain backend -``` - ---- - -## archgate adr show - -Print a specific ADR by ID. - -```bash -archgate adr show <id> -``` - -Prints the full ADR content (frontmatter and body) to stdout. - -### Arguments - -| Argument | Description | -| -------- | ----------------------------------- | -| `<id>` | ADR ID (e.g., `ARCH-001`, `BE-003`) | - -### Example - -```bash -archgate adr show ARCH-001 -``` - ---- - -## archgate adr update - -Update an existing ADR by ID. - -```bash -archgate adr update --id <id> --body <markdown> [options] -``` - -Replaces the ADR body with the provided markdown. Frontmatter fields (`--title`, `--domain`, `--files`, `--rules`) are updated only when explicitly passed; otherwise the existing values are preserved. - -### Options - -| Option | Required | Description | -| -------------------- | -------- | --------------------------------------------------------------------- | -| `--id <id>` | Yes | ADR ID to update (e.g., `ARCH-001`) | -| `--body <markdown>` | Yes | Full replacement ADR body markdown | -| `--title <title>` | No | New ADR title (preserves existing if omitted) | -| `--domain <domain>` | No | New domain (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | No | New file patterns, comma-separated (preserves existing if omitted) | -| `--rules` | No | Set `rules: true` in frontmatter | -| `--json` | No | Output as JSON | - -### Example - -```bash -archgate adr update \ - --id ARCH-001 \ - --title "Updated Command Structure" \ - --body "## Context\n\nUpdated context..." -``` - ---- - -## archgate review-context - -Pre-compute review context with ADR briefings for changed files. Designed for CI and editor plugin integrations that need a summary of which ADRs apply to the files being changed. - -```bash -archgate review-context [options] -``` - -### Options - -| Option | Description | -| ------------------- | ------------------------------------ | -| `--staged` | Only include git-staged files | -| `--run-checks` | Include ADR compliance check results | -| `--domain <domain>` | Filter to a single domain | - -### Example - -```bash -archgate review-context --staged -``` - ---- - -## archgate session-context - -Read AI editor session transcripts for the project. Useful for auditing what an AI agent did during a coding session. - -```bash -archgate session-context <subcommand> [options] -``` - -### Subcommands - -#### archgate session-context claude-code - -Read the Claude Code session transcript for the project. - -```bash -archgate session-context claude-code [options] -``` - -| Option | Description | -| ------------------- | ---------------------------------------- | -| `--max-entries <n>` | Maximum entries to return (default: 200) | - -#### archgate session-context cursor - -Read the Cursor agent session transcript for the project. - -```bash -archgate session-context cursor [options] -``` - -| Option | Description | -| ------------------- | ---------------------------------------- | -| `--max-entries <n>` | Maximum entries to return (default: 200) | -| `--session-id <id>` | Specific session UUID to read | - -### Examples - -Read the latest Claude Code session: - -```bash -archgate session-context claude-code -``` - -Read a specific Cursor session: - -```bash -archgate session-context cursor --session-id abc123 -``` - ---- - -## archgate upgrade - -Upgrade Archgate to the latest version via npm. - -```bash -archgate upgrade -``` - -Checks the npm registry for the latest published version. If a newer version is available, runs `npm install -g archgate@latest` to upgrade. If already up-to-date, prints a message and exits. - -### Example - -```bash -archgate upgrade -``` - -``` -Checking for latest Archgate release... -Upgrading 0.3.0 -> 0.4.0... -Archgate upgraded to 0.4.0 successfully. -``` - ---- - -## archgate doctor - -Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports. - -```bash -archgate doctor [options] -``` - -### Options - -| Option | Description | -| -------- | ----------------------- | -| `--json` | Machine-readable output | - -### Output sections - -- **System** — OS, architecture, WSL detection, Bun and Node versions -- **Archgate** — CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status -- **Project** — Whether an `.archgate/` project exists, ADR count, domains -- **Editor CLIs** — Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH -- **Project Integrations** — Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) - -### Example - -```bash -archgate doctor -``` - -``` -System - OS: win32/x64 - Bun: 1.3.11 - Node: v24.3.0 - -Archgate - Version: 0.25.1 - Install: binary - Exec path: /home/user/.archgate/bin/archgate - Config dir: /home/user/.archgate OK - Telemetry: enabled - Logged in: yes - -Project - ADRs: 5 (3 with rules) - Domains: ARCH, GEN - -Editor CLIs - claude: OK - cursor: MISSING - code (vscode):OK - copilot: MISSING - git: OK - -Project Integrations - Claude: OK (.claude/settings.local.json) - Cursor: MISSING (.cursor/rules/archgate-governance.mdc) - VS Code: OK (.vscode/settings.json) - Copilot: MISSING (.github/copilot/instructions.md) -``` - ---- - -## archgate clean - -Remove the CLI cache directory. - -```bash -archgate clean -``` - -Removes `~/.archgate/`, which stores cached data such as update check timestamps. Safe to run at any time -- the directory is recreated automatically when needed. - -### Example - -```bash -archgate clean -``` - -``` -/home/user/.archgate cleaned up -``` diff --git a/docs/src/content/docs/reference/cli/adr.mdx b/docs/src/content/docs/reference/cli/adr.mdx new file mode 100644 index 00000000..9ca1c992 --- /dev/null +++ b/docs/src/content/docs/reference/cli/adr.mdx @@ -0,0 +1,147 @@ +--- +title: archgate adr +description: "Create, list, show, and update Architecture Decision Records." +--- + +## archgate adr create + +Create a new ADR interactively or via flags. + +```bash +archgate adr create [options] +``` + +When run without `--title` and `--domain`, the command prompts interactively for the domain, title, and optional file patterns. When both `--title` and `--domain` are provided, it runs non-interactively. + +The ADR ID is auto-generated with the domain prefix and the next available sequence number (e.g., `ARCH-002`, `BE-001`). + +### Options + +| Option | Description | +| -------------------- | --------------------------------------------------------------------- | +| `--title <title>` | ADR title (skip interactive prompt) | +| `--domain <domain>` | ADR domain (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | File patterns, comma-separated | +| `--body <markdown>` | Full ADR body markdown (skip template) | +| `--rules` | Set `rules: true` in frontmatter | +| `--json` | Output as JSON | + +### Examples + +Interactive mode: + +```bash +archgate adr create +``` + +Non-interactive mode: + +```bash +archgate adr create \ + --title "API Response Envelope" \ + --domain backend \ + --files "src/api/**/*.ts" \ + --rules +``` + +--- + +## archgate adr list + +List all ADRs in the project. + +```bash +archgate adr list [options] +``` + +### Options + +| Option | Description | +| ------------------- | ---------------- | +| `--json` | Output as JSON | +| `--domain <domain>` | Filter by domain | + +### Examples + +List all ADRs in table format: + +```bash +archgate adr list +``` + +``` +ID Domain Rules Title +──────────────────────────────────────────────────────── +ARCH-001 architecture true Command Structure +ARCH-002 architecture true Error Handling +BE-001 backend true API Response Envelope +``` + +List ADRs as JSON: + +```bash +archgate adr list --json +``` + +Filter by domain: + +```bash +archgate adr list --domain backend +``` + +--- + +## archgate adr show + +Print a specific ADR by ID. + +```bash +archgate adr show <id> +``` + +Prints the full ADR content (frontmatter and body) to stdout. + +### Arguments + +| Argument | Description | +| -------- | ----------------------------------- | +| `<id>` | ADR ID (e.g., `ARCH-001`, `BE-003`) | + +### Example + +```bash +archgate adr show ARCH-001 +``` + +--- + +## archgate adr update + +Update an existing ADR by ID. + +```bash +archgate adr update --id <id> --body <markdown> [options] +``` + +Replaces the ADR body with the provided markdown. Frontmatter fields (`--title`, `--domain`, `--files`, `--rules`) are updated only when explicitly passed; otherwise the existing values are preserved. + +### Options + +| Option | Required | Description | +| -------------------- | -------- | --------------------------------------------------------------------- | +| `--id <id>` | Yes | ADR ID to update (e.g., `ARCH-001`) | +| `--body <markdown>` | Yes | Full replacement ADR body markdown | +| `--title <title>` | No | New ADR title (preserves existing if omitted) | +| `--domain <domain>` | No | New domain (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | No | New file patterns, comma-separated (preserves existing if omitted) | +| `--rules` | No | Set `rules: true` in frontmatter | +| `--json` | No | Output as JSON | + +### Example + +```bash +archgate adr update \ + --id ARCH-001 \ + --title "Updated Command Structure" \ + --body "## Context\n\nUpdated context..." +``` diff --git a/docs/src/content/docs/reference/cli/check.mdx b/docs/src/content/docs/reference/cli/check.mdx new file mode 100644 index 00000000..b3c43b56 --- /dev/null +++ b/docs/src/content/docs/reference/cli/check.mdx @@ -0,0 +1,136 @@ +--- +title: archgate check +description: "Run all automated ADR compliance checks against the codebase." +--- + +Run all automated ADR compliance checks against the codebase. + +```bash +archgate check [options] [files...] +``` + +Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose `files` patterns match those files are executed. + +## Options + +| Option | Description | +| ------------ | --------------------------------------------------------- | +| `--staged` | Only check git-staged files (useful for pre-commit hooks) | +| `--json` | Machine-readable JSON output | +| `--ci` | GitHub Actions annotation format | +| `--adr <id>` | Only check rules from a specific ADR | +| `--verbose` | Show passing rules and timing info | + +## Arguments + +| Argument | Description | +| ------------ | --------------------------------------------------------------------------------------------------------------- | +| `[files...]` | Optional file paths to scope checks to. Only ADRs whose `files` patterns match will run. Supports stdin piping. | + +## Exit codes + +| Code | Meaning | +| ---- | -------------------------------------------------------------------- | +| 0 | All rules pass. No violations found. | +| 1 | One or more violations detected. | +| 2 | Rule execution error (e.g., malformed rule, security scanner block). | + +## Examples + +Check the entire project: + +```bash +archgate check +``` + +Check only staged files before committing: + +```bash +archgate check --staged +``` + +Check a single ADR: + +```bash +archgate check --adr ARCH-001 +``` + +Check specific files (only matching ADRs run): + +```bash +archgate check src/foo.ts src/bar.ts +``` + +Pipe from git (check only changed files): + +```bash +git diff --name-only | archgate check --json +``` + +Get JSON output for CI integration: + +```bash +archgate check --json +``` + +Get GitHub Actions annotations: + +```bash +archgate check --ci +``` + +## JSON output format + +When `--json` is used, the output is a single JSON object: + +```json +{ + "pass": false, + "total": 4, + "passed": 3, + "failed": 1, + "warnings": 0, + "errors": 1, + "infos": 0, + "ruleErrors": 0, + "truncated": false, + "results": [ + { + "adrId": "ARCH-001", + "ruleId": "register-function-export", + "description": "Command file must export a register*Command function", + "status": "fail", + "totalViolations": 1, + "shownViolations": 1, + "violations": [ + { + "message": "Command file must export a register*Command function", + "file": "src/commands/broken.ts", + "line": 1, + "endLine": 1, + "endColumn": 42, + "severity": "error" + } + ], + "durationMs": 12 + } + ], + "durationMs": 42 +} +``` + +### Violation fields + +| Field | Type | Description | +| ----------- | ------- | ------------------------------------------------------- | +| `message` | string | What the violation is | +| `file` | string? | Relative file path | +| `line` | number? | Start line (1-based) | +| `endLine` | number? | End line (1-based) -- for precise editor highlighting | +| `endColumn` | number? | End column (0-based) -- for precise editor highlighting | +| `fix` | string? | Suggested fix (guidance only) | +| `severity` | string | `"error"`, `"warning"`, or `"info"` | + +### Blocked rule files + +When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions). diff --git a/docs/src/content/docs/reference/cli/clean.mdx b/docs/src/content/docs/reference/cli/clean.mdx new file mode 100644 index 00000000..11b49dab --- /dev/null +++ b/docs/src/content/docs/reference/cli/clean.mdx @@ -0,0 +1,22 @@ +--- +title: archgate clean +description: "Remove the CLI cache directory." +--- + +Remove the CLI cache directory. + +```bash +archgate clean +``` + +Removes `~/.archgate/`, which stores cached data such as update check timestamps. Safe to run at any time -- the directory is recreated automatically when needed. + +## Example + +```bash +archgate clean +``` + +``` +/home/user/.archgate cleaned up +``` diff --git a/docs/src/content/docs/reference/cli/doctor.mdx b/docs/src/content/docs/reference/cli/doctor.mdx new file mode 100644 index 00000000..a9139c0c --- /dev/null +++ b/docs/src/content/docs/reference/cli/doctor.mdx @@ -0,0 +1,62 @@ +--- +title: archgate doctor +description: "Check the system environment, installation method, and editor integrations." +--- + +Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports. + +```bash +archgate doctor [options] +``` + +## Options + +| Option | Description | +| -------- | ----------------------- | +| `--json` | Machine-readable output | + +## Output sections + +- **System** -- OS, architecture, WSL detection, Bun and Node versions +- **Archgate** -- CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status +- **Project** -- Whether an `.archgate/` project exists, ADR count, domains +- **Editor CLIs** -- Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH +- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`) + +## Example + +```bash +archgate doctor +``` + +``` +System + OS: win32/x64 + Bun: 1.3.11 + Node: v24.3.0 + +Archgate + Version: 0.25.1 + Install: binary + Exec path: /home/user/.archgate/bin/archgate + Config dir: /home/user/.archgate OK + Telemetry: enabled + Logged in: yes + +Project + ADRs: 5 (3 with rules) + Domains: ARCH, GEN + +Editor CLIs + claude: OK + cursor: MISSING + code (vscode):OK + copilot: MISSING + git: OK + +Project Integrations + Claude: OK (.claude/settings.local.json) + Cursor: MISSING (.cursor/rules/archgate-governance.mdc) + VS Code: OK (.vscode/settings.json) + Copilot: MISSING (.github/copilot/instructions.md) +``` diff --git a/docs/src/content/docs/reference/cli/index.mdx b/docs/src/content/docs/reference/cli/index.mdx new file mode 100644 index 00000000..6149a8eb --- /dev/null +++ b/docs/src/content/docs/reference/cli/index.mdx @@ -0,0 +1,33 @@ +--- +title: CLI Commands +description: "Complete reference for all Archgate CLI commands: init, check, adr, login, plugin, review-context, session-context, upgrade, doctor, clean, and telemetry." +--- + +## Global options + +These options are available on all commands: + +| Option | Description | +| ----------------- | -------------------------- | +| `--version`, `-V` | Print the Archgate version | +| `--help`, `-h` | Show help for any command | + +```bash +archgate --version +archgate check --help +``` + +## Commands + +| Command | Description | +| ------------------------------------------------ | ----------------------------------------------------- | +| [`archgate login`](./login/) | Authenticate with GitHub | +| [`archgate init`](./init/) | Initialize Archgate governance | +| [`archgate plugin`](./plugin/) | Manage editor plugins | +| [`archgate check`](./check/) | Run ADR compliance checks | +| [`archgate adr`](./adr/) | Create, list, show, and update ADRs | +| [`archgate review-context`](./review-context/) | Pre-compute review context for CI/editor integrations | +| [`archgate session-context`](./session-context/) | Read AI editor session transcripts | +| [`archgate upgrade`](./upgrade/) | Upgrade Archgate to the latest version | +| [`archgate doctor`](./doctor/) | Check system environment and editor integrations | +| [`archgate clean`](./clean/) | Remove the CLI cache directory | diff --git a/docs/src/content/docs/reference/cli/init.mdx b/docs/src/content/docs/reference/cli/init.mdx new file mode 100644 index 00000000..822c82d1 --- /dev/null +++ b/docs/src/content/docs/reference/cli/init.mdx @@ -0,0 +1,51 @@ +--- +title: archgate init +description: "Initialize Archgate governance in the current project." +--- + +Initialize Archgate governance in the current project. + +```bash +archgate init [options] +``` + +Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin. + +## Options + +| Option | Default | Description | +| ------------------- | -------- | ------------------------------------------------------------------------- | +| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`) | +| `--install-plugin` | auto | Install the Archgate editor plugin (requires prior `archgate login`) | + +When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise. + +## Plugin installation behavior + +**Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead. + +**Cursor:** The plugin bundle is downloaded from `plugins.archgate.dev` and extracted into the `.cursor/` directory. + +## Output + +``` +Initialized Archgate governance in /path/to/project + adrs/ - architecture decision records + lint/ - linter-specific rules + .claude/ - Claude Code settings configured + +Archgate plugin installed for Claude Code. +``` + +When `--editor cursor` is used, the output shows `.cursor/` instead of `.claude/`. + +## Generated structure + +``` +.archgate/ + adrs/ + ARCH-001-example.md # Example ADR + ARCH-001-example.rules.ts # Example rules file + lint/ + archgate.config.ts # Archgate configuration +``` diff --git a/docs/src/content/docs/reference/cli/login.mdx b/docs/src/content/docs/reference/cli/login.mdx new file mode 100644 index 00000000..fcaef0e2 --- /dev/null +++ b/docs/src/content/docs/reference/cli/login.mdx @@ -0,0 +1,124 @@ +--- +title: archgate login +description: "Authenticate with GitHub to access Archgate editor plugins." +--- + +Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, Copilot CLI, or Cursor), and use case, then registers you before completing the login. + +```bash +archgate login +``` + +Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`. + +If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically. + +Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, etc.) works without login. + +:::tip[Plugin beta] +Editor plugins are currently in beta. Run `archgate login` to sign up and authenticate. +::: + +## Subcommands + +| Subcommand | Description | +| ------------------------ | ----------------------------------------- | +| `archgate login` | Authenticate (skips if already logged in) | +| `archgate login status` | Show current authentication status | +| `archgate login logout` | Remove stored credentials | +| `archgate login refresh` | Re-authenticate and claim a new token | + +## Examples + +Log in for the first time: + +```bash +archgate login +``` + +``` +Authenticating with GitHub... + +Open https://github.com/login/device in your browser +and enter the code: ABCD-1234 + +Waiting for authorization... +GitHub user: yourname + +Your GitHub account yourname is not yet registered. +Let's sign you up now. + +Email: you@example.com +Editor: Claude Code +Use case: Enforcing ADRs in our monorepo + +Submitting signup request... +Claiming archgate plugin token... + +Authenticated as yourname. Plugin access is now available. +Run `archgate init` to set up a project with the archgate plugin. +``` + +If the project already has `.archgate/adrs/`, the final line reads: + +``` +Run `archgate check` to validate your project against its ADRs. +``` + +## Troubleshooting + +### TLS/corporate proxy errors + +If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable. + +On macOS/Linux: + +```bash +export NODE_EXTRA_CA_CERTS=/path/to/your-corporate-ca.pem +archgate login +``` + +On Windows (PowerShell): + +```powershell +$env:NODE_EXTRA_CA_CERTS = "C:\path\to\your-corporate-ca.pem" +archgate login +``` + +On Windows (cmd): + +```cmd +set NODE_EXTRA_CA_CERTS=C:\path\to\your-corporate-ca.pem +archgate login +``` + +On Windows (Git Bash): + +```bash +export NODE_EXTRA_CA_CERTS=/c/path/to/your-corporate-ca.pem +archgate login +``` + +Ask your IT team for the correct certificate path if you are unsure. + +Check login status: + +```bash +archgate login status +``` + +``` +Logged in as yourname (since 2026-02-28) +``` + +Log out: + +```bash +archgate login logout +``` + +Re-authenticate: + +```bash +archgate login refresh +``` diff --git a/docs/src/content/docs/reference/cli/plugin.mdx b/docs/src/content/docs/reference/cli/plugin.mdx new file mode 100644 index 00000000..2ea2dcdc --- /dev/null +++ b/docs/src/content/docs/reference/cli/plugin.mdx @@ -0,0 +1,78 @@ +--- +title: archgate plugin +description: "Manage Archgate editor plugins independently of archgate init." +--- + +Manage Archgate editor plugins independently of `archgate init`. + +```bash +archgate plugin <subcommand> [options] +``` + +Use `archgate plugin` to install plugins or retrieve the authenticated repository URL on projects that have already been initialized. + +## Subcommands + +### archgate plugin url + +Print the plugin repository URL for manual tool configuration. + +```bash +archgate plugin url [options] +``` + +| Option | Default | Description | +| ------------------- | -------- | ------------------------------------------------------- | +| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | + +The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code: + +```bash +claude plugin marketplace add "$(archgate plugin url)" +claude plugin install archgate@archgate +``` + +For VS Code, the URL points to a separate plugin repository: + +```bash +archgate plugin url --editor vscode +``` + +### archgate plugin install + +Install the Archgate plugin for the specified editor on an already-initialized project. + +```bash +archgate plugin install [options] +``` + +| Option | Default | Description | +| ------------------- | -------- | ------------------------------------------------------- | +| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) | + +Installation behavior varies by editor: + +- **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. +- **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. +- **Cursor:** Downloads and extracts the plugin bundle into `.cursor/`. +- **VS Code:** Adds the marketplace URL to VS Code user settings and installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. + +## Examples + +Get the plugin URL for manual configuration: + +```bash +archgate plugin url +``` + +Install the plugin for Claude Code: + +```bash +archgate plugin install +``` + +Install the plugin for Cursor: + +```bash +archgate plugin install --editor cursor +``` diff --git a/docs/src/content/docs/reference/cli/review-context.mdx b/docs/src/content/docs/reference/cli/review-context.mdx new file mode 100644 index 00000000..348a6bcc --- /dev/null +++ b/docs/src/content/docs/reference/cli/review-context.mdx @@ -0,0 +1,24 @@ +--- +title: archgate review-context +description: "Pre-compute review context with ADR briefings for changed files." +--- + +Pre-compute review context with ADR briefings for changed files. Designed for CI and editor plugin integrations that need a summary of which ADRs apply to the files being changed. + +```bash +archgate review-context [options] +``` + +## Options + +| Option | Description | +| ------------------- | ------------------------------------ | +| `--staged` | Only include git-staged files | +| `--run-checks` | Include ADR compliance check results | +| `--domain <domain>` | Filter to a single domain | + +## Example + +```bash +archgate review-context --staged +``` diff --git a/docs/src/content/docs/reference/cli/session-context.mdx b/docs/src/content/docs/reference/cli/session-context.mdx new file mode 100644 index 00000000..cc33f658 --- /dev/null +++ b/docs/src/content/docs/reference/cli/session-context.mdx @@ -0,0 +1,51 @@ +--- +title: archgate session-context +description: "Read AI editor session transcripts for the project." +--- + +Read AI editor session transcripts for the project. Useful for auditing what an AI agent did during a coding session. + +```bash +archgate session-context <subcommand> [options] +``` + +## Subcommands + +### archgate session-context claude-code + +Read the Claude Code session transcript for the project. + +```bash +archgate session-context claude-code [options] +``` + +| Option | Description | +| ------------------- | ---------------------------------------- | +| `--max-entries <n>` | Maximum entries to return (default: 200) | + +### archgate session-context cursor + +Read the Cursor agent session transcript for the project. + +```bash +archgate session-context cursor [options] +``` + +| Option | Description | +| ------------------- | ---------------------------------------- | +| `--max-entries <n>` | Maximum entries to return (default: 200) | +| `--session-id <id>` | Specific session UUID to read | + +## Examples + +Read the latest Claude Code session: + +```bash +archgate session-context claude-code +``` + +Read a specific Cursor session: + +```bash +archgate session-context cursor --session-id abc123 +``` diff --git a/docs/src/content/docs/reference/cli/upgrade.mdx b/docs/src/content/docs/reference/cli/upgrade.mdx new file mode 100644 index 00000000..b9bcd1c0 --- /dev/null +++ b/docs/src/content/docs/reference/cli/upgrade.mdx @@ -0,0 +1,24 @@ +--- +title: archgate upgrade +description: "Upgrade Archgate to the latest version via npm." +--- + +Upgrade Archgate to the latest version via npm. + +```bash +archgate upgrade +``` + +Checks the npm registry for the latest published version. If a newer version is available, runs `npm install -g archgate@latest` to upgrade. If already up-to-date, prints a message and exits. + +## Example + +```bash +archgate upgrade +``` + +``` +Checking for latest Archgate release... +Upgrading 0.3.0 -> 0.4.0... +Archgate upgraded to 0.4.0 successfully. +``` diff --git a/src/commands/plugin/install.ts b/src/commands/plugin/install.ts index 3a63c86e..e1ee4486 100644 --- a/src/commands/plugin/install.ts +++ b/src/commands/plugin/install.ts @@ -140,6 +140,50 @@ export function registerPluginInstallCommand(plugin: Command) { `Failed to install plugin for ${label}.`, err instanceof Error ? err.message : String(err) ); + + // Show manual install commands so the user can retry themselves + switch (editor) { + case "claude": { + const url = buildMarketplaceUrl(); + logInfo("To install the plugin manually, run:"); + console.log( + ` ${styleText("bold", "claude plugin marketplace add")} ${url}` + ); + console.log( + ` ${styleText("bold", "claude plugin install")} archgate@archgate` + ); + break; + } + case "copilot": { + const url = buildVscodeMarketplaceUrl(); + logInfo("To install the plugin manually, run:"); + console.log( + ` ${styleText("bold", "copilot plugin marketplace add")} ${url}` + ); + console.log( + ` ${styleText("bold", "copilot plugin install")} archgate@archgate` + ); + break; + } + case "cursor": { + logInfo( + "To install the plugin manually, download it from the archgate dashboard." + ); + break; + } + case "vscode": { + logInfo("To install the extension manually, run:"); + console.log( + ` ${styleText("bold", "curl")} -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix` + ); + console.log( + ` ${styleText("bold", "code")} --install-extension archgate.vsix` + ); + console.log(` rm archgate.vsix`); + break; + } + } + process.exit(1); } }