feat(plugin): install Copilot plugin declaratively, covering the desktop app - #543
Conversation
…top app The GitHub Copilot desktop app shares ~/.copilot/ with the copilot CLI but ships no CLI binary, so the PATH-only probe skipped it entirely. Copilot reads ~/.copilot/settings.json as its marketplace registry (extraKnownMarketplaces) and declarative auto-install list (enabledPlugins), so writing both entries installs the plugin without the CLI. - isCopilotAvailable(): CLI on PATH OR ~/.copilot exists (same shape as the opencode Desktop detection) - installCopilotPlugin() is declarative-first: always writes the settings.json declaration (overwriting a stale archgate marketplace URL, which 'copilot plugin marketplace add' never corrects), then runs 'copilot plugin install' when the CLI is present; desktop-only installs report a restart-the-app note - plugin url --editor copilot now prints the shared VS Code marketplace URL instead of the Claude one - EDITOR_LABELS.copilot renamed to 'GitHub Copilot'; docs (en/pt-br/nb) rewritten for both distributions; dead /reference/cli-commands/ landing link fixed Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Deploying archgate-cli with
|
| Latest commit: |
f421fa8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://8ccc8115.archgate-cli.pages.dev |
| Branch Preview URL: | https://rhuanbarreto-archgate-plugin.archgate-cli.pages.dev |
|
Warning Review limit reached
Next review available in: 29 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (17)
📝 WalkthroughWalkthroughGitHub Copilot plugin installation now supports both the CLI and desktop app. The implementation detects either distribution, configures shared user settings, preserves valid settings, replaces stale marketplace entries, and distinguishes immediate CLI installation from deferred declarative installation. Project initialization and command output now report installation state and fallback instructions. Tests cover settings, detection, installation modes, failures, and command behavior. English, Norwegian, and Brazilian Portuguese documentation now describes the updated workflow. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Code Coverage
Full HTML report available in workflow artifacts. Per-directory breakdown
|
Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/agent-memory/archgate-developer/MEMORY.md:
- Line 31: The MEMORY.md guidance incorrectly presents git reset origin/main as
safe and should be revised. Keep plain git fetch origin with --base origin/main
as the default worktree workflow; if recommending a reset, require an explicit
branch and backup procedure and accurately state its effects on branch history
and staged state, while retaining the --hard distinction without claiming
unqualified safety.
In `@docs/public/llms-full.txt`:
- Around line 1469-1472: Update the Copilot availability wording in both
documented locations to match isCopilotAvailable(): describe availability as
copilot being on PATH or an existing ~/.copilot/ directory, rather than claiming
the app is installed or not installed. Keep the CLI and desktop behavior
descriptions otherwise unchanged.
- Around line 1433-1439: Regenerate docs/public/llms-full.txt from the updated
documentation so the Copilot entries at the landing-page capability list and
guide index consistently use “GitHub Copilot” rather than the old CLI-only
label, while preserving the updated section describing both supported
distributions.
In `@docs/src/content/docs/reference/cli/plugin.mdx`:
- Line 56: Update the GitHub Copilot entry in the plugin documentation to
replace the unsupported “not installed at all” claim with wording that manual
commands are printed when no Copilot CLI on PATH or shared ~/.copilot/ settings
directory is detected; preserve the rest of the installation behavior
description.
In `@src/helpers/copilot-user-settings.ts`:
- Line 10: Replace the synchronous existsSync checks in
configureCopilotUserSettings with asynchronous existence handling, using await
Bun.file(settingsPath).exists() or handling only ENOENT from the existing async
read. Preserve the current behavior for existing and missing settings files
while avoiding synchronous filesystem access.
- Around line 69-85: Update configureCopilotUserSettings to create
copilotConfigDir() recursively before checking or accessing settings.json,
ensuring the initial configuration succeeds when .copilot does not exist.
Preserve the existing read, merge, and write behavior, and add a regression test
covering a missing Copilot configuration directory.
- Around line 24-29: The configureCopilotUserSettings flow must stop before
writing when Bun.JSONC.parse or schema validation fails, returning an actionable
error while preserving the existing settings file. Update enabledPlugins and
extraKnownMarketplaces validation to reject non-array/non-map values, and add
tests covering malformed JSONC and invalid plugin/marketplace maps; retain the
normal write behavior for valid settings.
In `@src/helpers/init-project.ts`:
- Around line 377-387: Preserve deferred installation in the
installCopilotPlugin result by adding an explicit configured or pending-restart
state to PluginResult and returning it when mode is "declarative"; only "cli"
should return immediate installation. Update registerInitCommand() to render and
record the deferred state as configured rather than installed, and adjust
tests/helpers/init-project-copilot.test.ts to assert the new contract.
In `@src/helpers/paths.ts`:
- Around line 68-70: Update copilotConfigDir() to return a nonempty
Bun.env.COPILOT_HOME value before falling back to archgateHomeDir()/.copilot,
preserving the existing default behavior when the variable is unset or empty.
Update the English, Norwegian, and Brazilian Portuguese Copilot guides to
describe ~/.copilot as the default configuration directory.
In `@src/helpers/plugin-install.ts`:
- Around line 13-17: Update copilotConfigDir() and the Copilot
detection/installation flow to honor Bun.env.COPILOT_HOME when resolving Copilot
user settings, while preserving the existing default when it is unset. Add a
regression test covering COPILOT_HOME set before detection and installation,
verifying settings are written to the overridden location.
- Around line 401-406: Update configureCopilotUserSettings to recursively create
copilotConfigDir() before writing settings.json, ensuring CLI-mode installation
succeeds when the directory is absent. Keep installCopilotPlugin unchanged and
update the Copilot tests to rely on configureCopilotUserSettings for directory
creation rather than pre-creating it.
In `@tests/helpers/plugin-install-copilot.test.ts`:
- Around line 190-196: Update the “throws when the CLI install fails” test
around installCopilotPlugin to await the rejection and assert that the resulting
UserError includes the failed process exit code and captured “boom” output, not
only the static error text. Keep the existing mocked spawn failure setup
unchanged.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 2714e123-b557-4e05-b26c-fb8dc997b72b
📒 Files selected for processing (34)
.claude/agent-memory/archgate-developer/MEMORY.mdCLAUDE.mddocs/astro.config.mjsdocs/public/llms-full.txtdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/src/content/docs/index.mdxdocs/src/content/docs/nb/guides/copilot-cli-plugin.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/nb/reference/cli/login.mdxdocs/src/content/docs/nb/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdxdocs/src/content/docs/pt-br/index.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdxdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxdocs/src/content/docs/reference/cli/plugin.mdxdocs/src/content/docs/reference/cli/upgrade.mdxsrc/commands/init.tssrc/commands/plugin/install.tssrc/commands/plugin/url.tssrc/helpers/copilot-user-settings.tssrc/helpers/editor-detect.tssrc/helpers/init-project.tssrc/helpers/paths.tssrc/helpers/plugin-install.tstests/commands/plugin/install.test.tstests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/init-project-copilot.test.tstests/helpers/init-project.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/plugin-install.test.ts
💤 Files with no reviewable changes (2)
- tests/helpers/init-project.test.ts
- tests/helpers/plugin-install.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Smoke Test (Windows) / Windows
- GitHub Check: Cloudflare Pages
🧰 Additional context used
📓 Path-based instructions (33)
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
In test files, use
_resetPlatformCache()to simulate different platforms instead of mocking or mutatingprocess.platformdirectly.
tests/**/*.ts: Use Bun's built-inbun testrunner for all tests; do not use Jest, Vitest, or custom assertions.
Mirror thesrc/directory structure intests/, and name test files<module-name>.test.ts.
Usemkdtempfor filesystem-test isolation, keep writes inside the temporary directory, and clean up temporary resources inafterEachorafterAll.
Test each module's public interface with descriptive names; do not test private internals.
Every runnable test must contain anexpect()assertion; usetest.skiportest.todofor placeholders and do not leave assertion-less or silently skipped tests.
Restore every captured environment variable withrestoreEnv(key, original)rather than assigning the captured value directly.
Mockos.homedir()via an imported module namespace andspyOn; do not overrideHOMEto control home-directory resolution. Environment overrides are valid only for code that readsBun.envat call time.
Mock first-party modules withimport * as modplusspyOn, restore them withmock.restore(), and never usemock.module()or an-implproduction split for first-party modules.
For HTTP mocking, saveglobalThis.fetchbefore replacing it and restore the direct assignment inafterEach; do not usemock.module("node:fetch").
Tests must not hit the network or touch real user-scope paths or other real state.
Wrap inlinespyOnormockImplementationlifecycles intry/finally, or manage them in hooks, somockRestore()always executes.
Close external SDK instances, servers, clients, and transports inafterEachorafterAll, not in test bodies.
Configuregit user.emailanduser.namelocally aftergit initand before committing in temporary repositories; never rely on global Git identity.
Inject small threshold values into threshold tests instead of generating thousands of file...
Files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tstests/commands/plugin/install.test.ts
{src,tests}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-001-spdx-license-headers.md)
{src,tests}/**/*.ts: Every TypeScript source file insrc/andtests/must begin with// SPDX-License-Identifier: Apache-2.0followed by// Copyright 2026 Archgate.
If a TypeScript file has a shebang line (for example#!/usr/bin/env buninsrc/cli.ts), the SPDX license header must appear immediately after the shebang.
Use single-line//comments for the SPDX header; do not use block comments (/* */) or alternate license identifiers.
Files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)
**/*.{ts,tsx}: Prefer Bun built-ins for file I/O, HTTP, globbing, testing, and subprocess execution; prefernode:built-in modules over npm alternatives when appropriate.
UseBun.spawnwith array-based arguments for all subprocess execution; do not useBun.$because it can hang on Windows.
Do not add npm packages for functionality already provided by Bun, such asglob,chalk, or utility libraries used for a single function.
Use Bun APIs such asBun.file()instead of Node.js-specific APIs such asfs.readFile()when Bun provides an equivalent.
Use relative imports with Bun's native module resolution; do not use TypeScript path aliases.
Files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
**/*.{rules.ts,ts}
📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-002-dependency-license-compatibility.md)
Newly encountered permissive licenses may be added to the LEGAL-002 allowlist in the rule implementation, with a comment explaining any override for packages whose package.json lacks a license field.
Files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-025-idiomatic-bun-test-parametrization-and-matchers.md)
tests/**/*.test.ts: Usetest.each()for the same assertion logic against multiple independent inputs, anddescribe.each()when each input requires a group of related tests. Do not register tests or run independent assertions insidefor/.forEachloops.
Use array rows for positionaltest.each()arguments and object rows for named fields, with descriptive title placeholders such as%s,%p,%d, or$field.
Assert derived facts with specific matchers rather than collapsing booleans into.toBe(true)or.toBe(false): compare values directly with.toBe()/.toEqual(), use.toContain()or.toMatch()for membership and substrings,.toBeInstanceOf(Array)for array checks,.toHaveLength()for counts, and.find()with.toBeDefined()/.toBeUndefined()for predicate existence checks.
Do not precompute a boolean solely for assertion; assert directly on the underlying values so failures expose the expected and received values.
When converting a loop totest.each()ordescribe.each(), preserve every assertion that ran per iteration; do not drop or merge assertions across cases.
Files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tstests/commands/plugin/install.test.ts
{src,tests,lint,scripts,shims}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
{src,tests,lint,scripts,shims}/**/*.ts: Project-authored TypeScript comments must be concise, describe current behavior only, and never narrate history, relocations, refactors, or how the code came to be.
A contiguous run of whole-line comments must contain at most five lines of narrative prose; longer rationale belongs in an ADR, agent-memory file, issue, or PR with a pointer. Tests and fixtures follow the same limit.
Use structural TSDoc tags such as@param,@returns,@throws,@example, and@seefor structured documentation; tagged sections are exempt from the five-line narrative bound, while@remarks,@description,@summary,@notes,@todo, and@fixmeremain counted as prose.
Files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
tests/{commands/plugin/install,commands/plugin/url,helpers/editor-detect}.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Update exact editor choice-list tests, including expected length and identifier order, when adding an editor.
Files:
tests/commands/plugin/url.test.tstests/commands/plugin/install.test.ts
**
⚙️ CodeRabbit configuration file
**: This project uses Archgate — an AI governance framework based on
Architecture Decision Records (ADRs). The ADRs in.archgate/adrs/
are the authoritative rules for this codebase. Each ADR has a companion
.rules.tsfile with automated checks that run viaarchgate check.When reviewing, you must:
- Treat ADR violations as blocking issues, not suggestions.
- Cite the specific ADR ID when flagging a violation (e.g., "Violates ARCH-006").
- Focus on semantic and contextual violations that automated rules cannot catch —
the.rules.tsfiles already cover syntactic/structural patterns.- If you are unsure whether something violates an ADR, flag it as a question
rather than approving it.
Files:
tests/commands/plugin/url.test.tsdocs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxCLAUDE.mddocs/astro.config.mjstests/helpers/copilot-user-settings.test.tssrc/commands/init.tsdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/upgrade.mdxtests/helpers/plugin-install-copilot.test.tsdocs/src/content/docs/index.mdxdocs/src/content/docs/pt-br/index.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/nb/reference/cli/plugin.mdxtests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tsdocs/src/content/docs/nb/reference/cli/login.mdxsrc/helpers/editor-detect.tsdocs/src/content/docs/reference/cli/plugin.mdxsrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tsdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/public/llms-full.txtdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdxsrc/helpers/init-project.tsdocs/src/content/docs/nb/guides/copilot-cli-plugin.mdxsrc/helpers/copilot-user-settings.ts
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
docs/src/content/docs/reference/cli/**/*.mdx: Every.mdxfile underdocs/src/content/docs/reference/cli/, exceptindex.mdx, must correspond to a top-level CLI command, and removed commands must have their orphaned pages deleted.
Document subcommands inline within the parent command's.mdxpage; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Each top-level CLI reference page should follow the established structure: frontmatter withtitleanddescription, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxdocs/src/content/docs/reference/cli/plugin.mdx
{src/commands/*/!(index).ts,src/commands/*/*/index.ts,docs/src/content/docs/reference/cli/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every direct subcommand represented by
src/commands/<parent>/<sub>.tsorsrc/commands/<parent>/<sub>/index.tsmust have a corresponding heading indocs/src/content/docs/reference/cli/<parent>.mdx, and every heading matchingarchgate <parent> <sub>must correspond to an actual subcommand file. Matching is case-insensitive.
Files:
docs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxsrc/commands/plugin/url.tsdocs/src/content/docs/reference/cli/plugin.mdxsrc/commands/plugin/install.ts
docs/src/content/docs/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Document subcommands using a heading containing the exact command text
archgate <parent> <sub>; do not use non-standard heading formats.
Files:
docs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxdocs/src/content/docs/reference/cli/plugin.mdx
docs/**/*.{mdx,astro,ts,mjs,json}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
The documentation site must be an Astro 5/Starlight project under
docs/, separate from the CLI project with its own package manifest, TypeScript configuration, lockfile, and build pipeline.
Files:
docs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxdocs/astro.config.mjsdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/upgrade.mdxdocs/src/content/docs/index.mdxdocs/src/content/docs/pt-br/index.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/nb/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/login.mdxdocs/src/content/docs/reference/cli/plugin.mdxdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdxdocs/src/content/docs/nb/guides/copilot-cli-plugin.mdx
docs/src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/src/content/docs/**/*.mdx: Use MDX format for all documentation content pages underdocs/src/content/docs/.
Organize content under the five category prefixes:getting-started/,concepts/,guides/,reference/, andexamples/.
Every content page must includetitleanddescriptionfrontmatter.
Escape literal curly braces in MDX, such asadr://\{id\}; do not use bare{}in prose or code labels.
Keep reference pages accurate to the CLI source code and update them in the same change that modifies a corresponding CLI API.
docs/src/content/docs/**/*.mdx: Maintain 1:1 parity between root MDX pages and each configured locale: every root file must have a translation at the same relative path, and locale files must not be orphaned.
When English documentation is added or modified, update the corresponding Portuguese and Norwegian locale files in the same pull request.
Translate user-facing prose, headings, titles, descriptions, table text, admonitions, and Starlight component text props; keep code blocks, commands, paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX structure, component imports, curly-brace escaping, and internal link paths; internal links must not contain locale prefixes such as/pt-br/.
Do not restructure the root content directory for translations; locale files must mirror the root content directory's relative paths.
Keep code blocks, CLI commands, file paths, and technical identifiers in English during translation.
Files:
docs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/upgrade.mdxdocs/src/content/docs/index.mdxdocs/src/content/docs/pt-br/index.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/nb/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/login.mdxdocs/src/content/docs/reference/cli/plugin.mdxdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdxdocs/src/content/docs/nb/guides/copilot-cli-plugin.mdx
docs/**/*
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
docs/**/*: Do not include the docs build in the CLIvalidatepipeline; docs build failures must not block CLI development or CI.
Do not create content files outsidedocs/src/content/docs/, becausedocsLoader()expects that directory structure.
Install documentation dependencies from withindocs/usingcd docs && bun installor the docs convenience scripts, not from the repository root.
Files:
docs/src/content/docs/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/reference/cli/login.mdxdocs/astro.config.mjsdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/upgrade.mdxdocs/src/content/docs/index.mdxdocs/src/content/docs/pt-br/index.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/nb/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/login.mdxdocs/src/content/docs/reference/cli/plugin.mdxdocs/src/content/docs/guides/copilot-cli-plugin.mdxdocs/public/llms-full.txtdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdxdocs/src/content/docs/nb/guides/copilot-cli-plugin.mdx
docs/src/content/docs/pt-br/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Every English top-level CLI reference page must have a matching pt-br mirror at
docs/src/content/docs/pt-br/reference/cli/<name>.mdx.
Files:
docs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Brazilian Portuguese translations with correct diacritical marks, including characters such as ã, ç, é, í, ó, ú, â, ê, ô, and à; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/pt-br/reference/cli/upgrade.mdxdocs/src/content/docs/pt-br/reference/cli/plugin.mdxdocs/src/content/docs/pt-br/index.mdxdocs/src/content/docs/pt-br/reference/cli/login.mdxdocs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx
*
📄 CodeRabbit inference engine (.archgate/adrs/GEN-005-repository-root-contents-allowlist.md)
*: Any newly added root-level file must be added to the allowlist in the same change, with the applicable Decision criterion documented in the PR description or commit message.
Place one-off scripts, scratch files, and exploratory helpers inscripts/or a gitignored scratch directory, never directly in the repository root.
Use;or an EXITtrapfor temporary-file cleanup that must run regardless of command failure; do not chain the script and cleanup with&&.
Prefer explicit paths withgit addinstead of habitually usinggit add -Aorgit add .when throwaway files may exist.
Rungit status, or otherwise inspect staged paths explicitly, before committing when scratch files may exist nearby.
Files:
CLAUDE.md
docs/astro.config.mjs
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-013-version-synchronization.md)
Keep
softwareVersionindocs/astro.config.mjssynchronized withpackage.jsonversion; do not edit it manually because the release hook updates it.Configure the five-category sidebar and add every documentation page to the sidebar.
docs/astro.config.mjs: Configure Starlight i18n withdefaultLocale: "root"and localesroot,pt-br, andnb; preserve the English root URL structure.
Do not create locale-specific sidebar configurations; use one sidebar configuration because Starlight resolves sidebar slugs per locale.
Files:
docs/astro.config.mjs
docs/**/*.{mjs,json}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
Run Astro commands under Bun using
bunx --bun astrofor development, build, and preview; use the rootdocs:dev,docs:build, anddocs:previewconvenience scripts when applicable.
Files:
docs/astro.config.mjs
src/**/!(*platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
src/**/!(*platform).ts: Insrc/TypeScript source files, do not readprocess.platformdirectly; usesrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(),getPlatformInfo()) for all platform detection.
Use the centralized platform helper instead of duplicating OS/WSL detection logic inline anywhere insrc/TypeScript source.
When behavior differs between Linux and Windows, account for WSL by usingisWSL()rather than assuming `
Files:
src/commands/init.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-010-prefer-bun-built-in-json-parsing.md)
src/**/*.ts: Useawait Bun.file(path).json()when reading JSON files in Bun TypeScript source code; do not useJSON.parse(await Bun.file(path).text())orJSON.parse(fs.readFileSync(path, "utf-8"))for file reads.
UseBun.JSONC.parse()when reading files that may contain comments, such astsconfig.json, instead of plainJSON.parse()on file contents.
ReserveJSON.parse()for parsing JSON strings from non-file sources such as API responses or string variables; do not use it as the default for reading JSON files.
src/**/*.ts: Use exit codes 0 for success, 1 for expected failures, 2 for internal errors, and 130 for user cancellation; do not use other exit codes.
UselogError()fromsrc/helpers/log.tsfor user-facing errors; write errors to stderr, not stdout, and avoid directconsole.error()calls.
Provide actionable suggestions in user-facing error messages whenever possible.
Do not show stack traces for user-triggered errors; unexpected errors may include stack traces only whenDEBUGorTRACEis set.
Do not catch and swallow unexpected errors; caught errors must be logged or re-thrown.
Do not exit with code 0 when an operation fails; expected failures must use exit code 1.
Fall back toprocess.cwd()whenfindProjectRoot()returns null in commands that do not require.archgate/.
Handle Inquirer'sExitPromptErrorat the top-level error boundary as user cancellation: exit with code 130, do not log an error, and do not send it to Sentry.
Do not sendUserErroror user-cancellationExitPromptErrorinstances to Sentry from any error handler, includingbeforeSend.
UseexitWith()rather than bareprocess.exit()when terminating after command execution so telemetry and Sentry data are flushed.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all colored CLI output; do not use raw ANSI escape codes or third-party color libraries.
Commands producing structured results must support--json; JSON output must contain ...
Files:
src/commands/init.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
src/commands/!(index).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
Each top-level command module under
src/commands/must define exactly one command and export aregister*Command(program)function.
Files:
src/commands/init.ts
src/commands/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
src/commands/**/*.ts: Command files must remain thin: parse arguments, call engine or helper functions, and format output; business logic must reside insrc/engine/,src/helpers/, orsrc/formats/.
Commands must execute in-process and must not spawn child processes for subcommand execution.
Command modules must not call.parse(); command parsing is handled by the CLI entry point.
src/commands/**/*.ts: In Commander.js command files, options requiring type narrowing beyond plain strings MUST usenew Option()from@commander-js/extra-typingsand register it with.addOption(), rather than using.option().
Use.choices([... ] as const)for options accepting a fixed set of values, and do not add manual validation or unsafe casts for those choices.
Use.argParser((value) => ...)on anOptionfor options requiring type conversion; do not pass parser functions such asparseIntas the third argument to.option().
Useas constfor.choices()arrays and.default()values to preserve literal types.
Reuse existing type definitions for type-level usage, access narrowed options directly, and avoid casts such asopts.editor as SomeType.
src/commands/**/*.ts: All commands that operate on.archgate/project resources must use the sharedfindProjectRoot()fromsrc/helpers/paths.ts; directprocess.cwd()project-root resolution is prohibited except ininit.
Commands that require a project must userequireProjectRoot()fromsrc/helpers/paths.tsinstead of implementing their own missing-project guard. Commands that can operate without a project may usefindProjectRoot()and handlenullthemselves.
When usingfindProjectRoot()directly, check for anullresult and provide a helpful error before exiting.
Pass the resolvedprojectRoottoprojectPaths()when constructing derived project paths.
Do not define localfindProjectRoot()variants; use the shared implementation fromsrc/helpers/paths.ts.
src/commands/**/*.ts: Ev...
Files:
src/commands/init.tssrc/commands/plugin/url.tssrc/commands/plugin/install.ts
src/commands/init.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, extend
EDITOR_DIRS,SIGNUP_EDITORS, the typed--editorchoices, andprintManualInstructions.
Files:
src/commands/init.ts
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Write Norwegian Bokmål translations, not Nynorsk, using informal
duand correct characters such as æ, ø, and å; do not remove accents or use unreviewed machine translation.
Files:
docs/src/content/docs/nb/reference/cli/upgrade.mdxdocs/src/content/docs/nb/index.mdxdocs/src/content/docs/nb/reference/cli/plugin.mdxdocs/src/content/docs/nb/reference/cli/login.mdxdocs/src/content/docs/nb/guides/copilot-cli-plugin.mdx
src/helpers/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
In helper files, use
logInfo()orlogWarn()instead of directconsole.log(),console.warn(), orconsole.info()calls.
Files:
src/helpers/paths.tssrc/helpers/editor-detect.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
src/commands/plugin/url.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, extend the typed editor choices and add its URL branch before the URL ternary.
Files:
src/commands/plugin/url.ts
src/helpers/editor-detect.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, append its detection promise and returned result in
editor-detect.ts.
Files:
src/helpers/editor-detect.ts
src/{helpers/editor-detect,helpers/init-project,commands/plugin/install}.ts
📄 CodeRabbit inference engine (CLAUDE.md)
All opencode-gated behavior must use
isOpencodeAvailable(), which detects either the CLI or the shared config directory; do not useisOpencodeCliAvailable()alone.
Files:
src/helpers/editor-detect.tssrc/commands/plugin/install.tssrc/helpers/init-project.ts
src/commands/plugin/install.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, extend the typed editor choices and add handling to
installForEditorand the manual-instructions catch path.
Files:
src/commands/plugin/install.ts
src/helpers/plugin-install.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, add the corresponding availability and installation helpers. Use
installEditorPluginBundle()for tarball-based editors; for GUI/Desktop editors without a CLI, availability must include a shared-state fallback.
Files:
src/helpers/plugin-install.ts
src/helpers/init-project.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, extend the
EditorTargetunion,EDITOR_LABELS, theconfigureEditorSettingsswitch, and, when applicable, thetryInstallPluginbranch.
Files:
src/helpers/init-project.ts
src/helpers/copilot-user-settings.ts
📄 CodeRabbit inference engine (CLAUDE.md)
installCopilotPlugin()must declaratively write or overwrite the Archgate marketplace and plugin declarations in~/.copilot/settings.json, then additionally run the CLI install when the Copilot CLI is available.
Files:
src/helpers/copilot-user-settings.ts
🧠 Learnings (13)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-04T19:29:13.635Z
Learning: `bun run validate` must pass before any task is considered complete.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-04T19:29:13.635Z
Learning: Anything enforceable by a static rule, executable test, ADR companion rule, or built-in `CheckResult` diagnostic should be placed in that enforcement layer rather than agent memory.
📚 Learning: 2026-07-15T22:56:35.415Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/commands/clean.test.ts:61-62
Timestamp: 2026-07-15T22:56:35.415Z
Learning: When reviewing tests that rely on src/helpers/paths.ts `internalPath()`, note that `internalPath()` intentionally reads `Bun.env.HOME ?? Bun.env.USERPROFILE` at call time and only uses `os.homedir()` if neither env var is set. Therefore, don’t suggest changing tests to `spyOn(os, "homedir")` for this behavior; instead, use per-test `Bun.env.HOME` / `Bun.env.USERPROFILE` overrides (as applicable) so the tests control `internalPath()`’s inputs.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tstests/commands/plugin/install.test.ts
📚 Learning: 2026-07-25T00:05:58.884Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: tests/helpers/auth.test.ts:38-46
Timestamp: 2026-07-25T00:05:58.884Z
Learning: When reviewing the Archgate CLI repository’s GEN-004 “concise forward-only narration” comments, don’t rely only on the automated phrase-based narration checks. Those checks can pass even when the comment wording describes historical/transfer semantics rather than current behavior (e.g., saying a prior restore “leaked” a value or a later subprocess “inherited it”). Manually verify that the comment describes the code’s current, forward behavior; flag or adjust comments that imply past/historical state transfer even if GEN-004 enforcement passes.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
📚 Learning: 2026-07-25T00:05:59.109Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: src/cli.ts:0-0
Timestamp: 2026-07-25T00:05:59.109Z
Learning: Code comments may include a concise issue/PR reference (per GEN-004) when it’s used to point readers to fuller rationale instead of inlining that rationale. During review, flag surrounding comment prose that reads like historical context or narrates refactors/relocations; a bare GEN-004-style reference is allowed and should not be flagged by itself.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
📚 Learning: 2026-07-25T15:44:40.668Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-005-testing-standards.md:0-0
Timestamp: 2026-07-25T15:44:40.668Z
Learning: In Archgate CLI test code governed by ARCH-007, only allow `Bun.$` in test suites that are explicitly restricted to a single platform. Any cross-platform test that runs on Linux, macOS, and Windows must avoid `Bun.$` and instead use array-based `Bun.spawn`. For shared git setup used by tests, import and use the `git()` helper from `tests/test-utils.ts` rather than duplicating git setup logic.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tstests/commands/plugin/install.test.ts
📚 Learning: 2026-07-25T22:03:14.216Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-002-error-handling.md:0-0
Timestamp: 2026-07-25T22:03:14.216Z
Learning: In Archgate boundary-wrapped CLI command actions (the handlers that rely on `handleCommandError()` for user-facing error output), expected-failure guards should signal user errors by throwing `new UserError(<message/details>)` rather than directly calling `logError()` followed by `exitWith(1)`. This keeps user-facing logging and the exit path centralized in `handleCommandError()`. For normal/computed command outcomes (e.g., `const exitCode = getExitCode(await runChecks(...))`), use `await exitWith(exitCode)` instead of calling `process.exit(exitCode)` so telemetry/Sentry flushing and outcome tagging still run.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tssrc/commands/init.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tssrc/helpers/paths.tssrc/commands/plugin/url.tssrc/helpers/editor-detect.tssrc/commands/plugin/install.tstests/commands/plugin/install.test.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
📚 Learning: 2026-07-25T23:21:49.190Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 512
File: tests/engine/git-files.test.ts:98-100
Timestamp: 2026-07-25T23:21:49.190Z
Learning: When reviewing archgate/cli for ARCH-006 (per its ADR frontmatter), only enforce the production-dependency policy scoped to package.json. Do not treat test-only refactors or relocated `node:fs` fixture writes as an ARCH-006 violation (since ARCH-006 does not govern test-file I/O API selection). If there’s a broader/test-wide refactor that would migrate fixture writing to `Bun.write()`, evaluate it separately under the appropriate in-scope rule.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tstests/commands/plugin/install.test.ts
📚 Learning: 2026-07-27T16:05:38.683Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 536
File: tests/commands/adr/sync-strict.test.ts:173-173
Timestamp: 2026-07-27T16:05:38.683Z
Learning: In this Bun + TypeScript repo, for rejected-promise assertions use the unawaited form: `expect(promise).rejects.toThrow(...)`. Do NOT add `await` to `expect(promise).rejects.toThrow(...)` (Bun’s types model this as `void`), because it will violate the type-aware oxlint rules `typescript(await-thenable)` and `typescript(no-confusing-void-expression)`. Only request an `await` if the repo adopts a typed, lint-compliant assertion helper or Bun’s typings change.
Applied to files:
tests/commands/plugin/url.test.tstests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.tstests/commands/plugin/install.test.ts
📚 Learning: 2026-07-15T22:55:51.978Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 476
File: tests/helpers/telemetry-config.test.ts:24-28
Timestamp: 2026-07-15T22:55:51.978Z
Learning: In this Bun/TypeScript codebase, when a unit under test spawns subprocesses via Bun.spawn (e.g., running `git credential ...`), prefer overriding relevant env vars (such as `HOME`, `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_NOSYSTEM`) using `process.env` in the test and restoring them with the test utility (e.g., `restoreEnv` from `tests/test-utils.ts`). Avoid relying on `spyOn(os, 'homedir')` for this purpose, because it only affects in-process calls and does not change the environment inherited by subprocesses; env-var overrides should be used for subprocess-level isolation and must be applied at call time.
Applied to files:
tests/helpers/copilot-user-settings.test.tstests/helpers/plugin-install-copilot.test.tstests/helpers/init-project-copilot.test.ts
📚 Learning: 2026-07-25T22:03:22.236Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md:64-67
Timestamp: 2026-07-25T22:03:22.236Z
Learning: When reviewing CLI subcommand documentation, don’t rely solely on the companion ARCH-016 enforcement rule’s limited path coverage (it only checks `src/commands/<parent>/*.ts` and `src/commands/<parent>/*/index.ts`). Manually verify that subcommands documented by convention in deeper paths (e.g., `src/commands/<parent>/**/add.ts` or `src/commands/adr/domain/add.ts`) have the required documentation, since future nested subcommands can drift without automated detection (tracked by ARCH-015 / GitHub `#503`).
Applied to files:
src/commands/init.tssrc/commands/plugin/url.tssrc/commands/plugin/install.ts
📚 Learning: 2026-06-11T12:50:28.661Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 406
File: .claude/agent-memory/archgate-developer/feedback_prefer_tests_over_adr_rules.md:8-18
Timestamp: 2026-06-11T12:50:28.661Z
Learning: In `archgate/cli`, for markdown files under `.claude/agent-memory/`, follow the established convention: use YAML frontmatter (with a `name:` field used as the document title) and do not require a top-level `#` (H1) heading. During code review, do not flag missing first-line/first-top-level H1 headings (e.g., MD041) for these agent-memory files since markdownlint is not part of the repo’s `bun run validate` lint pipeline (oxlint/oxfmt only).
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md
📚 Learning: 2026-07-25T00:05:20.592Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 496
File: .claude/agent-memory/archgate-developer/project_test_isolation_gotchas.md:10-10
Timestamp: 2026-07-25T00:05:20.592Z
Learning: When reviewing documentation/agent-memory entries under `.claude/agent-memory/**`, do not enforce GEN-004’s “forward-only” comment/narrative requirement. These entries are allowed to keep historical/past-tense incident narratives and dated markers (e.g., `Found YYYY-MM-DD`) because the context is intended to help future agents evaluate edge cases. Outside this scope, GEN-004’s forward-only rule should still apply.
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md
📚 Learning: 2026-07-02T16:03:33.031Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 446
File: src/helpers/session-context-opencode.ts:81-100
Timestamp: 2026-07-02T16:03:33.031Z
Learning: For synchronous helper functions that use Bun’s sqlite sync API (i.e., they must remain synchronous), it’s acceptable to use `existsSync` from `node:fs` to check whether the SQLite database file exists. Avoid using `Bun.file(path).exists()` for this purpose because it’s async and would force the helper to become async (no equivalent synchronous Bun alternative). If the DB file is missing, throw/return a clear, actionable "No database found" error (per ARCH-006) rather than letting the sqlite open fail with a generic DB-open error.
Applied to files:
src/helpers/paths.tssrc/helpers/editor-detect.tssrc/helpers/plugin-install.tssrc/helpers/init-project.tssrc/helpers/copilot-user-settings.ts
🪛 LanguageTool
docs/src/content/docs/pt-br/reference/cli/upgrade.mdx
[uncategorized] ~42-~42: Encontrada possível ausência de vírgula.
Context: ...stalados (Claude Code, Cursor, VS Code, GitHub Copilot, opencode) e executa a instalaç...
(AI_PT_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~42-~42: Pontuação duplicada
Context: ...tadas, mas não afetam o código de saída -- a atualização do CLI em si já está comp...
(DOUBLE_PUNCTUATION_XML)
CLAUDE.md
[uncategorized] ~114-~114: The official name of this software platform is spelled with a capital “H”.
Context: ...copilot-settings.ts is project-scope (.github/copilot/).
(GITHUB)
docs/src/content/docs/pt-br/reference/cli/login.mdx
[uncategorized] ~6-~6: Pontuação duplicada
Context: ...a CLI cuida do registro automaticamente -- solicita seu email, preferência de edit...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~6-~6: Encontrada possível ausência de vírgula.
Context: ...rência de editor (Claude Code, VS Code, GitHub Copilot ou Cursor) e caso de uso, e ent...
(AI_PT_HYDRA_LEO_MISSING_COMMA)
docs/src/content/docs/guides/copilot-cli-plugin.mdx
[uncategorized] ~12-~12: The official name of this software platform is spelled with a capital “H”.
Context: ...e used by the VS Code extension, in the .github/plugin/ manifest format Copilot recogn...
(GITHUB)
[uncategorized] ~59-~59: The official name of this software platform is spelled with a capital “H”.
Context: ...enerated files The command creates the .github/copilot/ directory for project-level c...
(GITHUB)
docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx
[uncategorized] ~6-~6: Pontuação duplicada
Context: ... e capturam novos padrões para a equipe -- o mesmo fluxo disponível no [plugin par...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~12-~12: Pontuação duplicada
Context: ...ugins.archgate.dev/archgate/vscode.git` -- o mesmo marketplace usado pela extensão...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~18-~18: Pontuação duplicada
Context: ...amente, sem reiniciar. ## Instalação :::note[Acesso beta necessário] O plugin pa...
(DOUBLE_PUNCTUATION_XML)
[style] ~74-~74: Três frases seguidas começam com a mesma palavra. Considere reformular a frase ou use um dicionário para encontrar um sinônimo.
Context: ...e skills baseadas em papéis ao Copilot. O agente orquestra o fluxo de guardrails,...
(PORTUGUESE_WORD_REPEAT_BEGINNING_RULE)
[style] ~81-~81: “em conformidade com” é uma expressão prolixa. É preferível dizer “conforme”, “segundo” ou “consoante”.
Context: ...ento somente leitura que projeta planos em conformidade com ADRs | O agente archgate:developer é...
(PT_WORDINESS_REPLACE_EM_CONFORMIDADE_COM)
[grammar] ~104-~104: Esta palavra é hifenizada.
Context: ...ras skills cuidam do desenvolvimento no dia a dia. ## Como funciona na prática O plugin...
(PT_COMPOUNDS_PRE_REFORM_DIA_A_DIA)
[style] ~116-~116: “em conformidade com” é uma expressão prolixa. É preferível dizer “conforme”, “segundo” ou “consoante”.
Context: ...ições dos ADRs O agente escreve código em conformidade com as restrições dos ADRs. As seções Do's ...
(PT_WORDINESS_REPLACE_EM_CONFORMIDADE_COM)
🔇 Additional comments (33)
CLAUDE.md (1)
114-114: LGTM!docs/astro.config.mjs (1)
232-235: LGTM!docs/public/llms-full.txt (5)
1443-1449: LGTM!
1503-1521: LGTM!
1551-1563: LGTM!
4534-4534: LGTM!Also applies to: 5075-5075
1488-1499: 🔒 Security & PrivacySensitive Data Exposure (CWE-200): Exposure of Sensitive Information to an Unauthorized Actor
Verify that the manual command does not expose the plugin token.
Line 1495 passes
archgate plugin url --editor copilotdirectly tocopilot plugin marketplace add. The init fallback already returnsbuildVscodeMarketplaceUrl()fromsrc/helpers/init-project.ts:407-411; if that value contains credentials, the token enters process arguments and may be written to~/.copilot/settings.json. The statement at Line 1499 that Git credential manager provides credentials is then misleading. Confirm the returned URL and use a credential-manager-only flow, or warn users not to log, share, or persist the URL.#!/bin/bash set -euo pipefail rg -n -A12 -B4 \ 'buildVscodeMarketplaceUrl|plugin url' \ src/helpers/plugin-install.ts \ src/commands/plugin/url.ts \ src/helpers/init-project.ts rg -n -A20 -B4 \ 'extraKnownMarketplaces|enabledPlugins|settings.json' \ src/helpers/copilot-user-settings.ts \ tests/helpers/copilot-user-settings.test.ts \ tests/helpers/plugin-install-copilot.test.tsdocs/src/content/docs/pt-br/reference/cli/upgrade.mdx (1)
42-42: LGTM!docs/src/content/docs/reference/cli/login.mdx (1)
6-6: LGTM!docs/src/content/docs/reference/cli/upgrade.mdx (1)
42-42: LGTM!docs/src/content/docs/index.mdx (1)
94-96: LGTM!Also applies to: 125-125
docs/src/content/docs/nb/index.mdx (1)
94-96: LGTM!Also applies to: 125-125
docs/src/content/docs/nb/reference/cli/login.mdx (1)
6-6: LGTM!docs/src/content/docs/nb/reference/cli/plugin.mdx (1)
56-56: LGTM!docs/src/content/docs/nb/reference/cli/upgrade.mdx (1)
42-42: LGTM!docs/src/content/docs/pt-br/index.mdx (1)
95-97: LGTM!Also applies to: 126-126
docs/src/content/docs/pt-br/reference/cli/login.mdx (1)
6-6: LGTM!docs/src/content/docs/pt-br/reference/cli/plugin.mdx (1)
56-56: LGTM!tests/helpers/copilot-user-settings.test.ts (1)
1-73: LGTM!Also applies to: 88-139
tests/commands/plugin/install.test.ts (1)
24-31: LGTM!Also applies to: 46-46, 126-126, 135-139, 245-284
docs/src/content/docs/guides/copilot-cli-plugin.mdx (1)
2-3: LGTM!Also applies to: 6-6, 12-12, 18-19, 61-92, 122-134
docs/src/content/docs/nb/guides/copilot-cli-plugin.mdx (1)
2-3: LGTM!Also applies to: 6-6, 12-12, 18-19, 61-134
docs/src/content/docs/pt-br/guides/copilot-cli-plugin.mdx (1)
2-3: LGTM!Also applies to: 6-6, 12-12, 18-19, 61-134
src/helpers/plugin-install.ts (2)
10-17: LGTM!Also applies to: 61-61, 358-358, 418-424
371-406: 🎯 Functional CorrectnessDesktop-only plugin install is valid.
GitHub Copilot documentation documents
enabledPluginsandextraKnownMarketplacesin user-levelsettings.jsonfor declarative automatic plugin installation, sodeclarativeis an appropriate desktop-only install mode.src/helpers/editor-detect.ts (1)
15-15: LGTM!Also applies to: 34-34
tests/helpers/plugin-install-copilot.test.ts (1)
1-106: LGTM!Also applies to: 118-125, 159-188
src/helpers/init-project.ts (1)
37-37: LGTM!Also applies to: 359-363, 368-375, 388-393
src/commands/init.ts (1)
315-337: LGTM!src/commands/plugin/install.ts (1)
26-26: LGTM!Also applies to: 71-91
src/commands/plugin/url.ts (1)
50-57: LGTM!tests/commands/plugin/url.test.ts (1)
128-135: LGTM!tests/helpers/init-project-copilot.test.ts (1)
1-61: LGTM!Also applies to: 87-132
Review follow-ups: - copilotConfigDir() honors Copilot's COPILOT_HOME override (default ~/.copilot), with a regression test covering detection and the settings write - PluginResult gains a deferred flag; init prints 'configured' (not 'installed') for desktop-only installs that take effect on next launch - plugin.mdx wording states the actual detection condition; guides call ~/.copilot the default (en/pt-br/nb) - llms.txt index entries use the GitHub Copilot label; llms-full.txt regenerated - CLI-failure test asserts exit code and captured stderr; cli-mode test runs without a pre-existing ~/.copilot (Bun.write creates it) - invalid-shape settings test shows field-level .catch preserves all other keys Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
…CH-006 Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
# archgate ## [0.52.0](v0.51.0...v0.52.0) (2026-08-06) ### ⚠ BREAKING CHANGES * add --strict and --output <format> (SARIF), remove --json/--ci/--max-warnings from check (#536) ### Features * add --strict and --output <format> (SARIF), remove --json/--ci/--max-warnings from check ([#536](#536)) ([70b1ede](70b1ede)) * **dist:** distribute archgate via winget ([#552](#552)) ([93cb3a8](93cb3a8)), references [#544](#544) * **lint:** migrate to TypeScript 7 and adopt oxlint type-aware linting ([#534](#534)) ([29daad8](29daad8)), references [#529](#529) * **plugin:** install Copilot plugin declaratively, covering the desktop app ([#543](#543)) ([ae2b988](ae2b988)) ### Bug Fixes * bound scan loop, narrow install-method types, and extend ARCH-021 to markdown code spans ([#548](#548)) ([3793d80](3793d80)), closes [#541](#541) [#540](#540) [#515](#515), references [#541](#541) [#540](#540) [#515](#515) * **cli:** exit 0 quietly when the output pipe closes (EPIPE) ([#546](#546)) ([e7bfa19](e7bfa19)) * **hooks:** invoke hooks through package scripts instead of a shell ([#557](#557)) ([3b9e411](3b9e411)), references [#442](#442) [#441](#441) [#442](#442) --- This PR was generated with [simple-release](https://github.com/TrigenSoftware/simple-release). <details> <summary>📄 Cheatsheet</summary> <br> You can configure the bot's behavior through a pull request comment using the `!simple-release/set-options` command. ### Command Format ````md !simple-release/set-options ```json { "bump": {}, "publish": {} } ``` ```` ### Useful Parameters #### Bump | Parameter | Type | Description | |-----------|------|-------------| | `version` | `string` | Force set specific version | | `as` | `'major' \| 'minor' \| 'patch' \| 'prerelease'` | Release type | | `prerelease` | `string` | Pre-release identifier (e.g., "alpha", "beta") | | `firstRelease` | `boolean` | Whether this is the first release | | `skip` | `boolean` | Skip version bump | | `byProject` | `Record<string, object>` | Per-project bump options for monorepos | #### Publish | Parameter | Type | Description | |-----------|------|-------------| | `skip` | `boolean` | Skip publishing | | `access` | `'public' \| 'restricted'` | Package access level | | `tag` | `string` | Tag for npm publication | ### Usage Examples #### Force specific version ````md !simple-release/set-options ```json { "bump": { "version": "2.0.0" } } ``` ```` #### Force major bump ````md !simple-release/set-options ```json { "bump": { "as": "major" } } ``` ```` #### Create alpha pre-release ````md !simple-release/set-options ```json { "bump": { "prerelease": "alpha" } } ``` ```` #### Publish with specific access and tag ````md !simple-release/set-options ```json { "bump": { "prerelease": "beta" }, "publish": { "access": "public", "tag": "beta" } } ``` ```` ### Custom Changelog Preamble You can add custom markdown to the top of the changelog (right after the version header) using the `!simple-release/set-preamble` command. The markdown after the command line becomes the preamble. ```md !simple-release/set-preamble ## What's new? - The website was completely redesigned - The new API gives you awesome possibilities ``` In a monorepo, pass the full package name after the command to target a single package's changelog. Wrap the name in backticks so GitHub keeps it as text instead of a mention: ```md !simple-release/set-preamble `@your-org/core` ## Core changes - New plugin system ``` Use one comment per package, plus one without a name for the whole release. ### Access Restrictions The commands can only be used by users with permissions: - repository owner - organization member - collaborator ### Notes - The last comment with `!simple-release/set-options` command takes priority - The last `!simple-release/set-preamble` comment per package takes priority - JSON must be valid, otherwise the `set-options` command will be ignored - Parameters apply only to the current release execution - The commands can be updated by editing the comment or adding a new one </details> <!-- Please do not edit this comment. simple-release-pull-request: true simple-release-branch-from: release simple-release-branch-to: main --> Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 participant
What
archgate plugin install --editor copilot(andarchgate init --install-plugin) now works for the GitHub Copilot desktop app, not just thecopilotCLI.isCopilotAvailable(): CLI on PATH or~/.copilot/exists — the desktop app ships no CLI binary but shares that directory (same shape as the existing opencode Desktop detection).installCopilotPlugin()is declarative-first: it always writes the marketplace + plugin declaration into~/.copilot/settings.json(extraKnownMarketplaces+enabledPlugins), which Copilot reads on startup as its marketplace registry and auto-install list. When the CLI is on PATH it additionally runscopilot plugin install archgate@archgatefor immediate effect; desktop-only installs print a "restart the Copilot app" note.archgatemarketplace entry is overwritten, correcting stale/dead URLs —copilot plugin marketplace addtreats "already registered" as success and never fixes them, which silently breaks both declarative auto-install andcopilot plugin update.plugin url --editor copilotprinting the Claude marketplace URL instead of the shared VS Code marketplace URL.EDITOR_LABELS.copilotrenamed to "GitHub Copilot" (it now covers both distributions).Why
Desktop-only users previously fell through to manual instructions and had to add the marketplace by hand in the app UI. Both distributions fully share
~/.copilot/state (settings.jsonregistry,config.jsoninstall state,installed-plugins/cache), so a settings-level declaration installs for both.Docs
guides/copilot-cli-plugin.mdxretitled "GitHub Copilot Plugin" and rewritten for both distributions (declarative flow, correct marketplace URL, current agents/skills tables) in en, pt-br, and nb; reference pages, landing cards, and sidebar label updated in all three locales./reference/cli-commands/link on the landing pages (correct target:/reference/cli/).Reviewer notes
settings.jsonis JSONC; the merge reads withBun.JSONC.parseand writes plain JSON (comments dropped — same documented trade-off as the VS Code settings merge).installCopilotPlugin()no longer runscopilot plugin marketplace add— the settings.json declaration is the registry, verified viacopilot plugin marketplace list.copilot plugin listshows the plugin, andcopilot plugin update archgate(previously 404ing) succeeds.tests/helpers/init-project-copilot.test.tsandplugin-install-copilot.test.tsare max-lines-cap siblings of their parent suites.