diff --git a/.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md b/.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md new file mode 100644 index 00000000..e7a0c7fb --- /dev/null +++ b/.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md @@ -0,0 +1,99 @@ +--- +id: ARCH-016 +title: CLI Subcommand Documentation Accuracy +domain: architecture +rules: true +files: + - "src/commands/**/*.ts" + - "docs/src/content/docs/reference/cli/**/*.mdx" +--- + +## Context + +[ARCH-015](./ARCH-015-cli-command-documentation-coverage.md) guarantees that every top-level CLI command has a corresponding `.mdx` reference page. However, it does not check whether **subcommands** are documented inside that page. A top-level command group like `adr` can gain new subcommands (`import`, `sync`) without ARCH-015 flagging anything, because `adr.mdx` already exists. + +This gap caused real drift: `archgate adr import` and `archgate adr sync` shipped without being documented in `adr.mdx`, and the omission was only caught by manual audit. + +**Drift surfaces:** + +1. **Undocumented subcommands.** A new `src/commands//.ts` file lands without a matching heading in `.mdx`. +2. **Orphan subcommand docs.** A subcommand is removed but its heading lingers in the parent `.mdx`, advertising a command that no longer exists. + +**Alternatives considered:** + +- **Full option/flag cross-check via AST parsing.** Parsing Commander.js `.option()` chains from TypeScript files and comparing against documented options in `.mdx` files. This provides the deepest accuracy but requires a TypeScript parser, is brittle against Commander API changes, and adds significant complexity to the rule. Option-level accuracy is better enforced through code review. +- **Auto-generating docs from `--help` output.** Eliminates all drift but loses the hand-written prose, examples, and troubleshooting sections that make the reference pages useful. Already rejected in ARCH-015. +- **Extending ARCH-015 directly.** The existing ADR is well-scoped to top-level command-to-page parity. Adding subcommand checks would mix two different granularities of enforcement in one rule. A separate ADR keeps the responsibilities clear and each rule focused. + +**Cross-references:** + +- [ARCH-015 -- CLI Command Documentation Coverage](./ARCH-015-cli-command-documentation-coverage.md) handles the top-level command-to-page check that this ADR complements. +- [ARCH-001 -- Command Structure](./ARCH-001-command-structure.md) defines the `src/commands//.ts` convention the rule relies on. +- [GEN-001 -- Documentation Site](./GEN-001-documentation-site.md) establishes the docs site structure. + +## Decision + +Every subcommand file at `src/commands//.ts` (excluding `index.ts` files and nested command groups) MUST have a corresponding heading in the parent command's reference page at `docs/src/content/docs/reference/cli/.mdx`. The heading MUST contain the text `archgate ` (case-insensitive). + +Conversely, every heading in a `.mdx` file that matches the pattern `archgate ` MUST correspond to an actual subcommand file. + +**Scope:** + +- **Direct subcommands only.** Files at `src/commands//.ts` where `` is not `index.ts`. Nested command groups (`src/commands///index.ts`) are treated as subcommands of `` with the name ``. +- **Deeply nested subcommands are excluded.** Files like `src/commands/adr/domain/add.ts` are subcommands of `adr domain`, not `adr`. The rule checks one level of nesting only: `/.ts` and `//index.ts`. +- **EN docs only.** The pt-br mirror is enforced by GEN-002. +- **Website docs only.** The skill reference (`commands.md` in plugin directories) is in a separate repository and cannot be checked from this project. Its sync is a manual responsibility documented in the Do's section below. + +## Do's and Don'ts + +### Do + +- **DO** add a `## archgate ` heading to `.mdx` in the same PR that adds a new subcommand +- **DO** remove the heading from `.mdx` in the same PR that removes a subcommand +- **DO** update the skill reference `commands.md` (in the `archgate/plugins` repository) whenever you update the website docs -- the four copies across plugin directories must stay identical and in sync with the website +- **DO** document nested command groups (e.g. `adr domain`) as a heading within the parent page, with their sub-subcommands listed in a table underneath + +### Don't + +- **DON'T** create a separate `.mdx` file for subcommands (ARCH-015 already forbids this) +- **DON'T** use non-standard heading formats -- the rule matches `archgate ` in heading text +- **DON'T** assume the skill reference updates itself -- it lives in a separate repo (`archgate/plugins`) and requires manual sync after every website docs change + +## Consequences + +### Positive + +- **Subcommand discoverability guaranteed.** Every subcommand shipped in the CLI has documentation in the parent's reference page -- no more silent omissions like `adr import` and `adr sync`. +- **Orphan detection.** Documented subcommands that no longer exist in code are flagged automatically. +- **Composable with ARCH-015.** This ADR handles subcommand-level coverage; ARCH-015 handles page-level coverage. Together they guarantee every command at every level is documented. +- **Lightweight enforcement.** The rule reads directory listings and greps headings -- no AST parsing, no process spawning. + +### Negative + +- **Does not check option accuracy.** The rule verifies subcommand headings exist but not that the documented options/flags match the actual Commander definition. Option-level accuracy requires code review. +- **Does not enforce skill reference sync.** The `commands.md` files in the plugins repo are outside the rule's reach. Drift between the website docs and skill reference must be caught through review. + +### Risks + +- **Non-standard heading format bypasses the rule.** If a contributor documents a subcommand with a heading like `## Import ADRs` instead of `## archgate adr import`, the rule won't detect it. **Mitigation:** The Do's section specifies the required format, and the rule's fix suggestion includes the expected heading text. +- **Nested group misdetection.** A directory like `src/commands/adr/domain/` contains both `index.ts` (the group) and `add.ts`, `remove.ts`, `list.ts` (the sub-subcommands). The rule treats `domain` as a subcommand of `adr` (correctly) but does not recurse into `domain/`'s children. **Mitigation:** Deeply nested subcommands are rare and are covered by the parent group's documentation pattern (table inside the heading section). + +## Compliance and Enforcement + +### Automated Enforcement + +- **Archgate rule** `ARCH-016/subcommand-has-docs-heading`: For each subcommand file under `src/commands/`, verifies a matching heading exists in the parent's `.mdx` page. Also checks the reverse: headings in `.mdx` files that look like subcommand references must correspond to actual files. Severity: `error`. Runs as part of `bun run validate` via `archgate check`. + +### Manual Enforcement + +Code reviewers MUST verify: + +1. New subcommands come with a heading in the parent `.mdx` in the same PR +2. Removed subcommands have their heading deleted in the same PR +3. The skill reference `commands.md` (in `archgate/plugins`) is updated to match + +## References + +- [ARCH-015 -- CLI Command Documentation Coverage](./ARCH-015-cli-command-documentation-coverage.md) -- Top-level command-to-page check +- [ARCH-001 -- Command Structure](./ARCH-001-command-structure.md) -- Command file layout convention +- [GEN-001 -- Documentation Site](./GEN-001-documentation-site.md) -- Docs site structure and URL scheme diff --git a/.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts b/.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts new file mode 100644 index 00000000..e8b5778a --- /dev/null +++ b/.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts @@ -0,0 +1,148 @@ +/// + +const COMMANDS_DIR = "src/commands"; +const DOCS_DIR = "docs/src/content/docs/reference/cli"; + +export default { + rules: { + "subcommand-has-docs-heading": { + description: + "Every subcommand file (src/commands//.ts) must have a corresponding heading in the parent's .mdx reference page, and vice versa", + severity: "error", + async check(ctx) { + // ── 1. Discover subcommand names from src/commands/ ────────────── + // + // Top-level command groups live at src/commands//index.ts. + // Direct subcommands are either: + // src/commands//.ts (single-file subcommand) + // src/commands///index.ts (nested command group) + // + // We only look one level deep: /. Files like + // src/commands/adr/domain/add.ts are sub-subcommands of "adr domain" + // and are NOT checked by this rule (they are documented in the + // "adr domain" section as a table, not as separate headings). + + // Find all parent command groups (dirs with an index.ts). + const groupIndexFiles = await ctx.glob(`${COMMANDS_DIR}/*/index.ts`); + + // Extract parent names from index files. + const parentNames = groupIndexFiles.map((indexFile) => { + const rel = indexFile.slice(COMMANDS_DIR.length + 1); + return rel.split("/")[0]; + }); + + // Discover subcommands for all parents in parallel. + const subResults = await Promise.all( + parentNames.map(async (parentName) => { + const [subFiles, nestedGroupFiles] = await Promise.all([ + ctx.glob(`${COMMANDS_DIR}/${parentName}/*.ts`), + ctx.glob(`${COMMANDS_DIR}/${parentName}/*/index.ts`), + ]); + + const subs = new Set(); + + // Single-file subcommands + for (const sf of subFiles) { + const fileName = sf.slice( + `${COMMANDS_DIR}/${parentName}/`.length + ); + if (fileName === "index.ts") continue; + subs.add(fileName.slice(0, -".ts".length)); + } + + // Nested command groups + for (const ngf of nestedGroupFiles) { + const nestedRel = ngf.slice( + `${COMMANDS_DIR}/${parentName}/`.length + ); + subs.add(nestedRel.split("/")[0]); + } + + return { parentName, subs }; + }) + ); + + const subcommandsByParent = new Map>(); + for (const { parentName, subs } of subResults) { + subcommandsByParent.set(parentName, subs); + } + + // ── 2. Check docs for each subcommand (parallel reads) ────────── + + // Heading pattern: any markdown heading containing "archgate " + // We look for lines like: ## archgate adr create + // ### archgate adr domain + const headingPattern = /^#{1,4}\s+.*archgate\s+(\S+)\s+(\S+)/giu; + + // Read all docs files in parallel. + const docsResults = await Promise.all( + [...subcommandsByParent.entries()].map( + async ([parentName, subNames]) => { + const docsFile = `${DOCS_DIR}/${parentName}.mdx`; + let docsContent: string | null; + try { + docsContent = await ctx.readFile(docsFile); + } catch { + // ARCH-015 will report the missing page; skip subcommand checks + docsContent = null; + } + return { parentName, subNames, docsFile, docsContent }; + } + ) + ); + + // Report violations. + for (const { + parentName, + subNames, + docsFile, + docsContent, + } of docsResults) { + if (docsContent === null) continue; + + // Extract documented subcommand names from headings + const documentedSubs = new Set(); + let match; + headingPattern.lastIndex = 0; + for (const line of docsContent.split("\n")) { + headingPattern.lastIndex = 0; + match = headingPattern.exec(line); + if (match) { + const docParent = match[1].toLowerCase(); + const docSub = match[2].toLowerCase(); + if (docParent === parentName.toLowerCase()) { + documentedSubs.add(docSub); + } + } + } + + // Subcommand -> docs: missing headings. + for (const sub of [...subNames].sort()) { + if (!documentedSubs.has(sub.toLowerCase())) { + ctx.report.violation({ + message: `Subcommand "archgate ${parentName} ${sub}" has no heading in ${docsFile}`, + file: `${COMMANDS_DIR}/${parentName}/${sub}.ts`, + fix: `Add a "## archgate ${parentName} ${sub}" heading to ${docsFile} documenting the subcommand`, + }); + } + } + + // Docs -> subcommand: orphan headings. + for (const docSub of [...documentedSubs].sort()) { + if ( + ![...subNames].some( + (s) => s.toLowerCase() === docSub.toLowerCase() + ) + ) { + ctx.report.violation({ + message: `Heading "archgate ${parentName} ${docSub}" in ${docsFile} has no corresponding subcommand file`, + file: docsFile, + fix: `Either create ${COMMANDS_DIR}/${parentName}/${docSub}.ts to match, or remove the orphan heading`, + }); + } + } + } + }, + }, + }, +} satisfies RuleSet; diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 62a94ba1..3427a673 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -3414,6 +3414,117 @@ archgate adr domain remove security --- +## archgate adr import + +Import ADRs from the registry or a git repository. + +```bash +archgate adr import [options] +``` + +The command clones the source, reads ADR files, remaps IDs to fit the local project's sequence, and writes them to `.archgate/adrs/`. It tracks imports in `.archgate/imports.json` so they can later be checked for upstream updates via [`archgate adr sync`](#archgate-adr-sync). + +### Arguments + +| Argument | Description | +| ------------- | ------------------------------------------------ | +| `` | Registry path(s), `org/repo/path`, or git URL(s) | + +### Options + +| Option | Description | +| ----------- | ------------------------------- | +| `--yes` | Skip confirmation prompt | +| `--json` | Output as JSON | +| `--dry-run` | Preview changes without writing | +| `--list` | List previously imported ADRs | + +### Examples + +Import from the registry: + +```bash +archgate adr import archgate/packs/typescript +``` + +Import from a git repository: + +```bash +archgate adr import https://github.com/acme/adr-packs.git +``` + +Preview what would be imported without writing any files: + +```bash +archgate adr import archgate/packs/typescript --dry-run +``` + +Import non-interactively (skip confirmation): + +```bash +archgate adr import archgate/packs/typescript --yes +``` + +List previously imported ADRs: + +```bash +archgate adr import --list +``` + +--- + +## archgate adr sync + +Check for upstream updates to imported ADRs. + +```bash +archgate adr sync [source...] [options] +``` + +The command compares local imported ADRs against their upstream source and shows which sections changed. In interactive mode, it prompts for each changed ADR with three choices: keep local, take upstream, or skip. + +### Arguments + +| Argument | Description | +| ------------- | ------------------------------------------------------ | +| `[source...]` | Optional source filter(s) — sync only matching imports | + +### Options + +| Option | Description | +| --------- | ---------------------------------------- | +| `--check` | Exit 1 if upstream has updates (CI mode) | +| `--yes` | Skip confirmation prompts | +| `--json` | Output as JSON | + +### Examples + +Check all imported ADRs for upstream updates: + +```bash +archgate adr sync +``` + +Check only imports from a specific source: + +```bash +archgate adr sync archgate/packs/typescript +``` + +CI mode — fail the build if any imported ADR is outdated: + +```bash +archgate adr sync --check +``` + +Accept all upstream updates non-interactively: + +```bash +archgate adr sync --yes +``` + +--- + ## Reference: archgate check Source: https://cli.archgate.dev/reference/cli/check/ @@ -4138,13 +4249,26 @@ When the override is in effect, running `archgate telemetry enable` persists the Source: https://cli.archgate.dev/reference/cli/upgrade/ -Upgrade Archgate to the latest version via npm. +Upgrade Archgate to the latest version. ```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. +Checks GitHub Releases for the latest published version. If a newer version is available, the command auto-detects how Archgate was installed and runs the appropriate upgrade strategy. If already up-to-date, prints a message and exits. + +## Install method detection + +The upgrade command inspects the running binary path to determine the install method, then delegates to the matching strategy: + +| Install method | Detection | Upgrade action | +| --------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Binary install** (`~/.archgate/bin/`) | Binary lives inside `~/.archgate/bin/` | Downloads the latest binary from GitHub Releases and replaces the existing one | +| **Proto** | Binary lives inside `~/.proto/tools/archgate/` | Runs `proto install archgate latest --pin` | +| **Local dev dependency** | Binary lives inside `node_modules/` | Detects the package manager from the nearest lockfile (bun, pnpm, yarn, or npm) and runs the appropriate add command (e.g. `bun add -d archgate@latest`) | +| **Global package manager** | Binary lives in a global bin directory | Detects which package manager owns the global bin directory and runs its upgrade command (e.g. `npm install -g archgate@latest`) | + +If no specific method is detected, the command falls back to `npm install -g archgate@latest`. ## Example @@ -4154,8 +4278,8 @@ archgate upgrade ``` Checking for latest Archgate release... -Upgrading 0.3.0 -> 0.4.0... -Archgate upgraded to 0.4.0 successfully. +Upgrading 0.34.0 -> 0.35.0... +Archgate upgraded to 0.35.0 successfully. ``` --- diff --git a/docs/src/content/docs/pt-br/reference/cli/adr.mdx b/docs/src/content/docs/pt-br/reference/cli/adr.mdx index f4b94943..49d2e5c4 100644 --- a/docs/src/content/docs/pt-br/reference/cli/adr.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/adr.mdx @@ -208,3 +208,114 @@ Remover um domínio personalizado: ```bash archgate adr domain remove security ``` + +--- + +## archgate adr import + +Importa ADRs do registro ou de um repositório git. + +```bash +archgate adr import [options] +``` + +O comando clona a fonte, lê os arquivos ADR, remapeia os IDs para a sequência do projeto local e os grava em `.archgate/adrs/`. As importações são rastreadas em `.archgate/imports.json` para que possam ser verificadas posteriormente via [`archgate adr sync`](#archgate-adr-sync). + +### Argumentos + +| Argumento | Descrição | +| ------------- | ----------------------------------------------------- | +| `` | Caminho(s) do registro, `org/repo/path` ou URL(s) git | + +### Opções + +| Opção | Descrição | +| ----------- | ----------------------------------- | +| `--yes` | Pula o prompt de confirmação | +| `--json` | Saída como JSON | +| `--dry-run` | Visualiza alterações sem gravar | +| `--list` | Lista ADRs importados anteriormente | + +### Exemplos + +Importar do registro: + +```bash +archgate adr import archgate/packs/typescript +``` + +Importar de um repositório git: + +```bash +archgate adr import https://github.com/acme/adr-packs.git +``` + +Visualizar o que seria importado sem gravar arquivos: + +```bash +archgate adr import archgate/packs/typescript --dry-run +``` + +Importar de forma não interativa (pula confirmação): + +```bash +archgate adr import archgate/packs/typescript --yes +``` + +Listar ADRs importados anteriormente: + +```bash +archgate adr import --list +``` + +--- + +## archgate adr sync + +Verifica atualizações upstream para ADRs importados. + +```bash +archgate adr sync [source...] [options] +``` + +O comando compara os ADRs importados locais com a fonte upstream e mostra quais seções mudaram. No modo interativo, solicita para cada ADR alterado com três opções: manter local, aceitar upstream ou pular. + +### Argumentos + +| Argumento | Descrição | +| ------------- | ---------------------------------------------------------------------------- | +| `[source...]` | Filtro(s) de fonte opcionais — sincroniza apenas importações correspondentes | + +### Opções + +| Opção | Descrição | +| --------- | ------------------------------------------------- | +| `--check` | Sai com código 1 se houver atualizações (modo CI) | +| `--yes` | Pula prompts de confirmação | +| `--json` | Saída como JSON | + +### Exemplos + +Verificar todos os ADRs importados por atualizações upstream: + +```bash +archgate adr sync +``` + +Verificar apenas importações de uma fonte específica: + +```bash +archgate adr sync archgate/packs/typescript +``` + +Modo CI — falha o build se algum ADR importado estiver desatualizado: + +```bash +archgate adr sync --check +``` + +Aceitar todas as atualizações upstream de forma não interativa: + +```bash +archgate adr sync --yes +``` diff --git a/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx b/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx index 03fcc3ac..10654edc 100644 --- a/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx @@ -1,15 +1,28 @@ --- title: archgate upgrade -description: "Atualiza o Archgate para a versão mais recente via npm." +description: "Atualiza o Archgate para a versão mais recente." --- -Atualiza o Archgate para a versão mais recente via npm. +Atualiza o Archgate para a versão mais recente. ```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. +Verifica o GitHub Releases para a versão mais recente publicada. Se uma versão mais nova estiver disponível, o comando detecta automaticamente como o Archgate foi instalado e executa a estratégia de atualização apropriada. Se já estiver atualizado, exibe uma mensagem e encerra. + +## Detecção do método de instalação + +O comando de atualização inspeciona o caminho do binário em execução para determinar o método de instalação e delega para a estratégia correspondente: + +| Método de instalação | Detecção | Ação de atualização | +| ------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Instalação binária** (`~/.archgate/bin/`) | Binário está em `~/.archgate/bin/` | Baixa o binário mais recente do GitHub Releases e substitui o existente | +| **Proto** | Binário está em `~/.proto/tools/archgate/` | Executa `proto install archgate latest --pin` | +| **Dependência de dev local** | Binário está em `node_modules/` | Detecta o gerenciador de pacotes pelo lockfile mais próximo (bun, pnpm, yarn ou npm) e executa o comando de adição apropriado (ex.: `bun add -d archgate@latest`) | +| **Gerenciador de pacotes global** | Binário está em um diretório bin global | Detecta qual gerenciador de pacotes possui o diretório bin global e executa o comando de atualização (ex.: `npm install -g archgate@latest`) | + +Se nenhum método específico for detectado, o comando usa `npm install -g archgate@latest` como fallback. ## Exemplo @@ -19,6 +32,6 @@ archgate upgrade ``` Checking for latest Archgate release... -Upgrading 0.3.0 -> 0.4.0... -Archgate upgraded to 0.4.0 successfully. +Upgrading 0.34.0 -> 0.35.0... +Archgate upgraded to 0.35.0 successfully. ``` diff --git a/docs/src/content/docs/reference/cli/adr.mdx b/docs/src/content/docs/reference/cli/adr.mdx index c0e3e002..1979bba7 100644 --- a/docs/src/content/docs/reference/cli/adr.mdx +++ b/docs/src/content/docs/reference/cli/adr.mdx @@ -208,3 +208,114 @@ Remove a custom domain: ```bash archgate adr domain remove security ``` + +--- + +## archgate adr import + +Import ADRs from the registry or a git repository. + +```bash +archgate adr import [options] +``` + +The command clones the source, reads ADR files, remaps IDs to fit the local project's sequence, and writes them to `.archgate/adrs/`. It tracks imports in `.archgate/imports.json` so they can later be checked for upstream updates via [`archgate adr sync`](#archgate-adr-sync). + +### Arguments + +| Argument | Description | +| ------------- | ------------------------------------------------ | +| `` | Registry path(s), `org/repo/path`, or git URL(s) | + +### Options + +| Option | Description | +| ----------- | ------------------------------- | +| `--yes` | Skip confirmation prompt | +| `--json` | Output as JSON | +| `--dry-run` | Preview changes without writing | +| `--list` | List previously imported ADRs | + +### Examples + +Import from the registry: + +```bash +archgate adr import archgate/packs/typescript +``` + +Import from a git repository: + +```bash +archgate adr import https://github.com/acme/adr-packs.git +``` + +Preview what would be imported without writing any files: + +```bash +archgate adr import archgate/packs/typescript --dry-run +``` + +Import non-interactively (skip confirmation): + +```bash +archgate adr import archgate/packs/typescript --yes +``` + +List previously imported ADRs: + +```bash +archgate adr import --list +``` + +--- + +## archgate adr sync + +Check for upstream updates to imported ADRs. + +```bash +archgate adr sync [source...] [options] +``` + +The command compares local imported ADRs against their upstream source and shows which sections changed. In interactive mode, it prompts for each changed ADR with three choices: keep local, take upstream, or skip. + +### Arguments + +| Argument | Description | +| ------------- | ------------------------------------------------------ | +| `[source...]` | Optional source filter(s) — sync only matching imports | + +### Options + +| Option | Description | +| --------- | ---------------------------------------- | +| `--check` | Exit 1 if upstream has updates (CI mode) | +| `--yes` | Skip confirmation prompts | +| `--json` | Output as JSON | + +### Examples + +Check all imported ADRs for upstream updates: + +```bash +archgate adr sync +``` + +Check only imports from a specific source: + +```bash +archgate adr sync archgate/packs/typescript +``` + +CI mode — fail the build if any imported ADR is outdated: + +```bash +archgate adr sync --check +``` + +Accept all upstream updates non-interactively: + +```bash +archgate adr sync --yes +``` diff --git a/docs/src/content/docs/reference/cli/upgrade.mdx b/docs/src/content/docs/reference/cli/upgrade.mdx index b9bcd1c0..0f77bb88 100644 --- a/docs/src/content/docs/reference/cli/upgrade.mdx +++ b/docs/src/content/docs/reference/cli/upgrade.mdx @@ -1,15 +1,28 @@ --- title: archgate upgrade -description: "Upgrade Archgate to the latest version via npm." +description: "Upgrade Archgate to the latest version." --- -Upgrade Archgate to the latest version via npm. +Upgrade Archgate to the latest version. ```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. +Checks GitHub Releases for the latest published version. If a newer version is available, the command auto-detects how Archgate was installed and runs the appropriate upgrade strategy. If already up-to-date, prints a message and exits. + +## Install method detection + +The upgrade command inspects the running binary path to determine the install method, then delegates to the matching strategy: + +| Install method | Detection | Upgrade action | +| --------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Binary install** (`~/.archgate/bin/`) | Binary lives inside `~/.archgate/bin/` | Downloads the latest binary from GitHub Releases and replaces the existing one | +| **Proto** | Binary lives inside `~/.proto/tools/archgate/` | Runs `proto install archgate latest --pin` | +| **Local dev dependency** | Binary lives inside `node_modules/` | Detects the package manager from the nearest lockfile (bun, pnpm, yarn, or npm) and runs the appropriate add command (e.g. `bun add -d archgate@latest`) | +| **Global package manager** | Binary lives in a global bin directory | Detects which package manager owns the global bin directory and runs its upgrade command (e.g. `npm install -g archgate@latest`) | + +If no specific method is detected, the command falls back to `npm install -g archgate@latest`. ## Example @@ -19,6 +32,6 @@ archgate upgrade ``` Checking for latest Archgate release... -Upgrading 0.3.0 -> 0.4.0... -Archgate upgraded to 0.4.0 successfully. +Upgrading 0.34.0 -> 0.35.0... +Archgate upgraded to 0.35.0 successfully. ```