feat(session-context)!: detect the AI editor and select it with --editor - #563
Conversation
`archgate session-context` required the caller to name its own harness as a subcommand, even though every supported harness announces itself through environment variables it injects into the processes it spawns. The command now resolves the editor from the environment. Where a harness also publishes its own session id, the exact session is pinned rather than guessed by recency: CLAUDECODE -> CLAUDE_CODE_SESSION_ID COPILOT_CLI -> COPILOT_AGENT_SESSION_ID CURSOR_AGENT -> CURSOR_CONVERSATION_ID OPENCODE -> (no session id; recency) A published id is probed against the project-scoped session list before use. Every reader hard-fails on an unknown sessionId rather than falling back, so a stale or unrelated id would otherwise turn a working command into an error; probing lets it degrade to recency instead. Ids are read through usableEnv so an empty value is not mistaken for a pin, and an id only ever pins the editor that published it. When several markers are present, harnesses publishing a session id outrank the one that does not, and every match is reported in `candidates`. The four editor modules collapse into a single `src/commands/session-context.ts`, which makes `session-context` a top-level command rather than a command group. ARCH-004 and ARCH-016 are amended: their prose cited those modules as examples, and ARCH-016 now states the orphan-heading exemption in terms of the condition the rule actually applies. BREAKING CHANGE: the per-editor subcommands are removed. Replace `archgate session-context <editor> [list|show]` with `archgate session-context [list|show] --editor <editor>`, or omit `--editor` to use the detected one. `--root` moves to `show` and is rejected for editors other than opencode instead of being silently ignored. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
…etection Adding an editor now also touches the runtime detection path, and the two detections answer different questions: whether an editor is installed, and whether it is the one running this process. Only a variable the editor injects into its subprocesses answers the second, so a config directory or a PATH probe must not stand in for it. ARCH-014 gains the value-normalization rule that makes such a variable safe to use as a lookup key: an empty string reads as "absent" at the far end, so defaulting to it hides a rejected value behind silently wrong behavior. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Cursor names its directory under ~/.cursor/projects/ by collapsing each non-alphanumeric run to a single dash and trimming the ends. Archgate mapped each separator to a dash and kept every one, so a path containing a dot-segment produced a doubled dash and resolved to a directory that does not exist: archgate looked for: E-archgate-cli--claude-worktrees-sweet-cohen cursor wrote: e-archgate-cli-claude-worktrees-sweet-cohen That covers every git worktree under .claude/worktrees/, where reading Cursor transcripts reported "No Cursor agent-transcripts directory found". The cursor branch now mirrors Cursor's slugify. The default branch is unchanged: Claude Code preserves repeated separators, and its encoding is verified against real directories under ~/.claude/projects/. The fixtures that reproduced the encoding by hand now derive it from encodeProjectPath, so a future change to either branch cannot leave a copy behind asserting the old shape. 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: |
56a5431
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1550119f.archgate-cli.pages.dev |
| Branch Preview URL: | https://claude-session-context-edito.archgate-cli.pages.dev |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe session-context CLI now uses automatic editor detection with direct 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 |
|
@coderabbitai review The previous review failed on a head-commit race: the |
|
|
Code Coverage
Full HTML report available in workflow artifacts. Per-directory breakdown
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 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 `@docs/public/llms-full.txt`:
- Line 4825: Update the command summary near the “current conversation”
description to document session selection: use the current session when a valid
session ID is available; otherwise select the most recent session, including
when the ID is invalid, stale, or empty.
In `@docs/src/content/docs/pt-br/guides/cursor-integration.mdx`:
- Around line 152-155: Na seção de integração do Cursor, substitua o termo
“flags” por “opções” na frase que introduz os parâmetros opcionais, mantendo o
restante do conteúdo inalterado.
In `@src/commands/session-context.ts`:
- Around line 135-142: Update the readAutoSessionById options in the show action
to resolve root through withGlobals("root", opts, command) instead of reading
opts.root directly, while leaving maxEntries, editor, and the remaining session
lookup behavior unchanged.
- Around line 17-27: Update the EDITORS declaration and import the
DetectedHarness type from the harness detection module, using a satisfies-based
assertion to require EDITORS to cover DetectedHarness values while preserving
the existing readonly tuple and command-line choices.
In `@tests/commands/session-context.test.ts`:
- Around line 45-50: Replace the loop in “no longer registers a subcommand per
editor” with a single whole-array assertion or remove the redundant test, since
the preceding exact subcommand-list test already covers this behavior. Do not
call expect() once per editor iteration.
In `@tests/helpers/session-context-auto.test.ts`:
- Around line 181-189: Update the “caps the transcript with maxEntries” test and
its beforeEach fixture: write multiple entries to the newer session file, then
assert the returned transcript length is exactly 1 when readAutoSession is
called with maxEntries: 1, rather than only checking that transcript exists.
🪄 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: 5913cdc1-ad4c-41dc-be6a-9cd029e87b29
📒 Files selected for processing (35)
.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-014-prefer-bun-env.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.tsCLAUDE.mddocs/public/llms-full.txtdocs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxsrc/cli.tssrc/commands/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/copilot.tssrc/commands/session-context/cursor.tssrc/commands/session-context/index.tssrc/commands/session-context/opencode.tssrc/helpers/harness-detect.tssrc/helpers/paths.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.tstests/commands/session-context.test.tstests/commands/session-context/claude-code.test.tstests/commands/session-context/copilot.test.tstests/commands/session-context/cursor.test.tstests/commands/session-context/opencode.test.tstests/helpers/harness-detect.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-cursor.test.tstests/helpers/session-context.test.ts
💤 Files with no reviewable changes (9)
- src/commands/session-context/claude-code.ts
- src/commands/session-context/cursor.ts
- src/commands/session-context/opencode.ts
- src/commands/session-context/index.ts
- tests/commands/session-context/copilot.test.ts
- tests/commands/session-context/claude-code.test.ts
- tests/commands/session-context/opencode.test.ts
- src/commands/session-context/copilot.ts
- tests/commands/session-context/cursor.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 (29)
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/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.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: Keep English content at the root and mirror every English MDX file in each locale directory (pt-brandnb) with the same relative path and filename; do not create orphan translations.
When English documentation is added or modified, update the corresponding locale files in the same pull request.
Translate user-facing prose, titles, descriptions, headings, list items, table text, admonitions, and Starlight component text props; keep code blocks, CLI commands, file paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX curly-brace escaping, component imports, structural MDX elements, and internal link paths; internal links must not include locale prefixes.
Do not use machine translation without human review for technical accuracy.
Files:
docs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.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/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/public/llms-full.txtdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-021-authored-text-integrity.md)
Markdown and MDX text content MUST NOT contain a backslash-escaped backtick. Use a longer code-span delimiter or restructure the sentence instead. The rule excludes YAML frontmatter, fenced code blocks, and
CHANGELOG.md.
Files:
docs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxCLAUDE.mddocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdx
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
bun run validatemust pass before a task is considered complete; it runs lint, typecheck, format check, tests, ADR checks, Knip, and the build check.
Files:
docs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxsrc/helpers/paths.tsdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxsrc/commands/session-context.tsdocs/public/llms-full.txtsrc/cli.tstests/helpers/session-context-auto.test.tsdocs/src/content/docs/pt-br/reference/cli/session-context.mdxtests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tsCLAUDE.mdtests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tsdocs/src/content/docs/reference/cli/session-context.mdxsrc/helpers/harness-detect.tsdocs/src/content/docs/nb/reference/cli/session-context.mdxsrc/helpers/session-context-auto.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:
docs/src/content/docs/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/claude-code-plugin.mdxsrc/helpers/paths.tsdocs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxsrc/commands/session-context.tsdocs/public/llms-full.txtsrc/cli.tstests/helpers/session-context-auto.test.tsdocs/src/content/docs/pt-br/reference/cli/session-context.mdxtests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tsCLAUDE.mdtests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tsdocs/src/content/docs/reference/cli/session-context.mdxsrc/helpers/harness-detect.tsdocs/src/content/docs/nb/reference/cli/session-context.mdxsrc/helpers/session-context-auto.ts
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Norwegian translations must use Bokmål rather than Nynorsk, use informal
du, and preserve correct characters such asæ,ø, andå.
Files:
docs/src/content/docs/nb/guides/claude-code-plugin.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdx
{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:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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.
**/*.{ts,tsx}: Use Bun rather than Node.js APIs; the project targets Bun with TypeScript strict mode, ESNext, and ES modules.
When adding an editor target, update every coordinated integration point: editor type/configuration and installation, detection, init and plugin command choices/branches, URL handling, exact-choice-list tests, and—when transcript support is needed—harness detection, session-context switches, and editor choices.
Files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-018-lazy-load-heavy-dependencies.md)
src/**/*.ts: Heavy runtime dependencies such asinquirer,posthog-node, and@sentry/*must be loaded with dynamicimport()at their point of use, never through top-level static value imports.
Type-only imports for heavy dependencies are allowed, but runtime values must be obtained through dynamicimport(); for example, useimport type { PostHog } from "posthog-node".
SDKs that require early initialization may use eager-start/lazy-await: begin initialization before command registration and await the result at first use, such as in apreActionhook.
src/**/*.ts: Everyinquirer.prompt(...)call must be wrapped inwithPromptFix(() => ...)imported fromsrc/helpers/prompt.ts; keep the wrapper adjacent to the prompt invocation so automated checks can detect it.
Do not callinquirer.prompt(...)directly or reimplement cursor/newline fixes at individual call sites; route all prompt behavior throughwithPromptFix().Every call to
Bun.Glob#scan()(glob.scan(...)) in source must pass{ dot: true }in its options object, including scans whose patterns do not explicitly target dot-directories. Do not usedot: false; intentionally excluded dotfiles must be filtered explicitly after scanning with a comment. Normalize scanned path separators withfile.replaceAll("\\", "/")when performing cross-platform path comparisons.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all colored CLI output; do not use raw ANSI escape codes or third-party color libraries such as chalk, kleur, or picocolors.
Commands producing structured results must support machine-readable output through--json, orcheck's canonical--output <format>selector.
UseformatJSON()fromsrc/helpers/output.tsfor command JSON serialization; passforcePretty: trueor its equivalent when pretty JSON is explicitly requested.
UseisAgentContext()for automatic JSON selection; only JSON may auto-upgrade in agent context, whilegithubandsarifremai...
Files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tssrc/helpers/session-context.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
**/*.{js,ts,tsx,mjs,cjs}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-003-tool-invocation-via-scripts.md)
Invoke linting, formatting, and validation through package scripts (
bun run lint,bun run format,bun run format:check, andbun run validate), rather than directly invoking tool binaries such asbunx prettier,bunx oxfmt,npx eslint, oroxlint.
Files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
src/**/!(platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
All platform detection in
src/must go throughsrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(), orgetPlatformInfo()); directprocess.platformaccess and duplicated detection logic are forbidden outsideplatform.ts.
Files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tssrc/helpers/session-context.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
src/helpers/paths.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-014-prefer-bun-env.md)
Normalize environment-variable values through
usableEnv()before using them as lookup keys, path segments, or identifiers; it converts both empty strings and the literal string"undefined"tonull.
Files:
src/helpers/paths.ts
src/helpers/{paths,init-project,plugin-install}.ts
📄 CodeRabbit inference engine (CLAUDE.md)
For user-scope editors, resolve paths using the editor's actual path helper rather than assuming Windows conventions; opencode uses
xdg-basedirand falls back to~/.configon every platform.
Files:
src/helpers/paths.ts
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Brazilian Portuguese translations must use correct diacritical marks, including characters such as
ã,ç,é,í,ó,ú,â,ê,ô, andà.
Files:
docs/src/content/docs/pt-br/guides/claude-code-plugin.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
.archgate/adrs/**/*.{md,ts}
📄 CodeRabbit inference engine (CLAUDE.md)
Read relevant self-governance ADRs and companion
.rules.tsfiles before architectural changes; ADRs use YAML frontmatter and companion files export a plain object satisfyingRuleSet.
Files:
.archgate/adrs/ARCH-014-prefer-bun-env.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md
.archgate/adrs/**/*.rules.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
.archgate/adrs/**/*.rules.ts: Comments in.archgate/adrs/**/*.rules.tsmust be concise, forward-only, and limited to current behavior; historical or relocation narration is prohibited.
Changes to narration or relocation detection patterns in companion.rules.tsfiles must be synchronized with.archgate/lint/oxlint.ts, and both enforcement layers must continue to report violations at error severity.
Files:
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts
.archgate/{lint,adrs}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/GEN-004-concise-forward-only-code-comments.md)
.archgate/{lint,adrs}/**/*.ts: A contiguous run of whole-line comments must contain at most five lines of narrative prose, including in lint and companion rule implementations.
Use the same synchronized structural-TSDoc exemption in Archgate TypeScript files; narrative must not be relabeled with prose-container tags to evade the limit.
Files:
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts
src/commands/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-011-consistent-project-root-resolution.md)
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: Each command module must export aregister*Command(program)function; each non-index.tscommand file must define exactly one command.
Command files must remain thin: parse arguments, call engine/helpers, 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 files must not call.parse(); argument parsing is handled by the CLI entry point.
Commands should use typed Commander registration APIs, such as@commander-js/extra-typings, within theirregister*Commandfunctions.
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()instead of.option().
Use.choices([... ] as const)for options accepting a fixed set of values, and use.default(... as const)when providing a default, preserving literal type inference.
Use.argParser((value) => ...)on anOptionfor type-converting options; do not pass parser functions such asparseIntas the third argument to...
Files:
src/commands/session-context.ts
src/commands/{*.ts,*/index.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Top-level command modules must follow the
src/commands/<name>.tsorsrc/commands/<name>/index.tsconvention. Nested subcommand files do not count as top-level commands.
Files:
src/commands/session-context.ts
src/cli.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-001-command-structure.md)
src/cli.ts: The CLI entry point must explicitly import and call every command'sregister*Commandfunction; command auto-discovery such asexecutableDir()is forbidden.
All asynchronous bootstrap logic must be inside an asyncmain()function invoked throughmain().catch(...); top-level await is forbidden.
Themain().catch(...)handler must silently exit with code 130 forExitPromptError, logUserErrorand exit with code 1 without Sentry, and capture unexpected errors in Sentry before exiting with code 2; all exits must useexitWith().Every top-level CLI command registered via an executable
register*Command(program)call insrc/cli.tsmust have a corresponding command module and English reference page.
src/cli.ts: Inmain().catch(), handleUserErroras an expected failure by callinglogError()and exiting with code 1 without Sentry capture; only other errors should use exit code 2 andcaptureException().
KeepinstallStreamErrorGuards()as the first pre-main guard after the Bun check so stream error listeners attach before any output is written.Keep the CLI entry point at
src/cli.tswith the shebang#!/usr/bin/env bun, and enforce the minimum user-facing Bun version there.
Files:
src/cli.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-025-idiomatic-bun-test-parametrization-and-matchers.md)
tests/**/*.test.ts: Usetest.each()ordescribe.each()for the same assertion logic against multiple independent inputs. Do not register tests or callexpect()once per case inside aforor.forEachloop.
Use array rows for positional destructuring and object rows for named fields when passing cases totest.each()ordescribe.each(). Choose descriptive title placeholders such as%s,%p,%d, or$field.
Assert derived facts with the most specific matcher available instead of passing a derived boolean to.toBe(true)or.toBe(false). Compare values directly with.toBe()or.toEqual().
Use specific matchers for common derived checks:.toContain()or.toMatch()for containment,.toBeInstanceOf()for type checks such asArray.isArray,.toHaveLength()for counts, and.find()with.toBeDefined()or.toBeUndefined()for predicate existence checks.
Do not precompute a boolean solely to assert it; assert the underlying values directly with matchers such as.toEqual()or.toBe().
When converting a loop totest.each()ordescribe.each(), preserve every assertion that ran per iteration; do not drop or merge assertions.
tests/**/*.test.ts: Every runnable test must contain anexpect()assertion; usetest.skiportest.todofor placeholders rather than assertion-less or silently skipped tests.
Test public interfaces with descriptive names rather than private implementation details.
Do not usemock.module()for first-party modules. Mock them withimport * as modplusspyOn(mod, "fn"), and restore mocks after each test.mock.module()may be used for approved external modules such asinquirerornode:readline.
For HTTP mocking, saveglobalThis.fetchbefore direct assignment and restore it inafterEach; do not usemock.module("node:fetch"), which does not intercept Bun's global fetch.
Wrap inlinespyOnormockImplementationlifecycles intry/finally, or manage them in hooks, somockRestore()runs wh...
Files:
tests/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.ts
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.ts: Use Bun's built-inbun:testrunner for all tests; do not importnode:test. Test files belong undertests/, mirrorsrc/, usetests/fixtures/for shared fixtures, and follow<module-name>.test.tsnaming.
Filesystem tests must use isolatedmkdtempdirectories and clean them up inafterEachorafterAll; do not touch real user-scope paths or leave temporary files behind.
Close external SDK instances, servers, clients, and transports in test hooks, such asawait server.close()inafterEachorafterAll.
Restore every captured environment variable withrestoreEnv(key, original); never restore with direct assignment such asBun.env.X = original, becauseundefinedbecomes the string"undefined".
Mockos.homedir()via an imported module namespace andspyOn; do not rely on overridingHOMEfor code usingos.homedir(), and keep filesystem writes inside temporary directories.
Shared test helpers, including non-test files undertests/, must restore every captured environment variable withrestoreEnv; isolation responsibilities apply across the entire shared Bun test process.Use
_resetAllCaches()fromsrc/helpers/platform.tsto simulate different platforms in tests rather than mockingprocess.platformdirectly.When adding an editor, update tests asserting exact choice lists in
tests/commands/plugin/install.test.ts,tests/commands/plugin/url.test.ts, andtests/helpers/editor-detect.test.ts; editor detection tests must preserve length and ID order.
Files:
tests/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.ts
docs/src/content/docs/pt-br/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Create a matching pt-br mirror for each English CLI reference page; internationalization parity is enforced separately by GEN-002.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.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/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 top-level CLI command must have exactly one corresponding English reference page atdocs/src/content/docs/reference/cli/<name>.mdx; every page exceptindex.mdxmust correspond to a command.
Document subcommands inline in their parent command page; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Command reference pages should follow the established MDX structure:titleanddescriptionfrontmatter, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
docs/src/content/docs/reference/cli/**/*.mdx: Every module-backed subcommand must be documented in the top-level parent.mdxpage with a case-insensitive heading containing its full command path, such asarchgate adr domain add.
Every heading representing a command whose parent chain consists entirely of command-group directories must correspond to an actual subcommand module.
Use the standard heading format containingarchgate <parent> <sub>; do not create separate.mdxfiles for subcommands.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
src/helpers/harness-detect.ts
📄 CodeRabbit inference engine (CLAUDE.md)
harness-detect.tsdetermines which editor is running the process; only an environment variable injected by the editor into subprocesses counts. Do not use config-directory or PATH probes in the runtime detection path.
Files:
src/helpers/harness-detect.ts
🧠 Learnings (20)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-07T13:43:43.898Z
Learning: Update the four plugin-repository `commands.md` skill-reference copies whenever website CLI documentation changes, keeping them identical and synchronized.
📚 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/session-context.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-08-04T19:58:05.877Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 543
File: src/helpers/copilot-user-settings.ts:0-0
Timestamp: 2026-08-04T19:58:05.877Z
Learning: In archgate/cli TypeScript code, use `Bun.file(path).exists()` only to check whether a file exists; it must not be used for directory existence checks. For helpers such as `isCopilotAvailable()` that need to detect a configuration directory, use an appropriate directory-aware check such as `existsSync` from `node:fs`.
Applied to files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-08-05T06:56:33.435Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 546
File: tests/integration/stream-guards.test.ts:3-9
Timestamp: 2026-08-05T06:56:33.435Z
Learning: When reviewing GEN-004 comment-block limits in the Archgate CLI repository, count only narrative prose lines within a block comment. Do not count a closing delimiter such as `*/` as a prose line; for example, in `tests/integration/stream-guards.test.ts`, Lines 4–8 contain five prose lines while Line 9 contains only the delimiter.
Applied to files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-08-06T21:09:28.014Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 561
File: src/helpers/binary-upgrade.ts:239-287
Timestamp: 2026-08-06T21:09:28.014Z
Learning: In archgate/cli TypeScript code, follow ARCH-007 for Bun subprocess stream capture; ARCH-017 does not govern subprocess pipe handling. When Bun.spawn() uses piped stdout or stderr, use a shared capture helper where practical, consume configured streams concurrently to avoid deadlocks, and verify the subprocess exit code before trusting captured output.
Applied to files:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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:
src/helpers/paths.tssrc/commands/session-context.tssrc/cli.tstests/helpers/session-context-auto.test.tstests/commands/session-context.test.tssrc/helpers/session-context.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-07-25T16:24:51.133Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-003-output-formatting.md:0-0
Timestamp: 2026-07-25T16:24:51.133Z
Learning: In Archgate ADRs (.archgate/adrs/*.md), omit quantitative claims (e.g., token savings, benchmarks, performance deltas) unless they are backed by a reproducible measurement and supported by a single cited reference. If you cannot satisfy both (reproducible measurement + exactly one cited reference), describe the benefit qualitatively and tie it to the relevant policy/requirements instead of using numeric estimates.
Applied to files:
.archgate/adrs/ARCH-014-prefer-bun-env.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md
📚 Learning: 2026-07-25T22:03:17.073Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 501
File: .archgate/adrs/ARCH-015-cli-command-documentation-coverage.md:17-18
Timestamp: 2026-07-25T22:03:17.073Z
Learning: When updating an ADR that documents rule discovery/enforcement behavior, ensure the ADR’s stated discovery contract matches the implementation in code. If the rule only discovers commands by scanning `src/commands/*.ts` and `src/commands/*/index.ts`, the ADR must not claim it also inspects command registration calls elsewhere (e.g., `src/cli.ts`). Any ADR language that changes the documented contract should be treated as a normative change to behavior and aligned with the corresponding implementation/issue, not as prose-only documentation compression.
Applied to files:
.archgate/adrs/ARCH-014-prefer-bun-env.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md
📚 Learning: 2026-07-26T13:09:49.888Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 533
File: .archgate/adrs/ARCH-020-glob-scan-include-dotfiles.md:0-0
Timestamp: 2026-07-26T13:09:49.888Z
Learning: In archgate/cli rule ADRs, `ctx.scopedFiles` is computed from the ADR frontmatter `files` glob patterns before the rule context is constructed. For ARCH-020-style rules, ensure the ADR `files` frontmatter correctly scopes the allowed paths (e.g., `files: ["src/**/*.ts"]`); then rule-specific `.ts`/file filters should assume the incoming file list is already restricted and avoid re-applying the same path-prefix restriction inside individual rules.
Applied to files:
.archgate/adrs/ARCH-014-prefer-bun-env.md.archgate/adrs/ARCH-004-no-barrel-files.md.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md
📚 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/session-context.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/session-context-auto.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.ts
📚 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/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.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/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.ts
📚 Learning: 2026-08-05T16:54:13.117Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/commands/adr/domain/remove.test.ts:21-24
Timestamp: 2026-08-05T16:54:13.117Z
Learning: In the Archgate CLI test suite, continue using `z.object` for JSON output schemas unless a repository-wide testing policy explicitly adopts `z.strictObject`. Do not introduce strict CLI-output schema enforcement as an isolated change in a coverage-focused pull request; require coordinated updates and policy agreement across affected tests.
Applied to files:
tests/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.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/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.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/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.ts
📚 Learning: 2026-08-05T16:54:50.574Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/helpers/plugin-install-cursor-hooks.test.ts:44-44
Timestamp: 2026-08-05T16:54:50.574Z
Learning: In this repository, every TypeScript module under `src/` must have a matching `<module-name>.test.ts` file under the mirrored `tests/` directory, as required by ARCH-005. Supplemental behavior-suffixed sibling test files are allowed only when the matching parent test file exists. Use such siblings to keep individual test files below the 500-line oxlint limit.
Applied to files:
tests/helpers/session-context-auto.test.tstests/commands/session-context.test.tstests/helpers/session-context.test.tstests/helpers/session-context-cursor.test.tstests/helpers/harness-detect.test.ts
📚 Learning: 2026-08-05T13:34:53.406Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 549
File: .archgate/adrs/ARCH-021-authored-text-integrity.md:0-0
Timestamp: 2026-08-05T13:34:53.406Z
Learning: For Markdown files in archgate/cli, rely on the mechanically enforced ARCH-021/no-escaped-backtick-in-markdown rule during archgate check rather than retaining formatter-specific review guidance. Apply the CommonMark rationale: backslash escapes have no meaning inside code spans, and a code span ends at the next backtick run of equal length. Encode enforceable invariants in repository rules instead of free-text agent memory.
Applied to files:
CLAUDE.md
🪛 LanguageTool
docs/src/content/docs/pt-br/guides/cursor-integration.mdx
[grammar] ~152-~152: Possível erro de concordância.
Context: ...so informar um editor. O comando aceita dois flags opcionais: - --max-entries <n> -- Nú...
(GENERAL_GENDER_AGREEMENT_ERRORS)
[uncategorized] ~154-~154: Pontuação duplicada
Context: ...flags opcionais: - --max-entries <n> -- Número máximo de entradas a retornar (p...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~155-~155: Pontuação duplicada
Context: ...das mais recentes). - --editor <name> -- Lê as transcrições de outro editor em v...
(DOUBLE_PUNCTUATION_XML)
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
[style] ~19-~19: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...e. Por padrão, o editor detectado. | | --max-entries ` | Número máximo de entradas a retorna...
(INTERNET_ABBREVIATIONS)
[uncategorized] ~24-~24: Pontuação duplicada
Context: ...rir qual editor está perguntando. Passe --editor para sobrepor o resultado ou par...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~35-~35: Pontuação duplicada
Context: ...só fixa o editor que o publicou. Passar --editor cursor de dentro do Claude Code ...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~54-~54: Pontuação duplicada
Context: ...e ambiente que identificou o editor, ou --editor quando você informou um. `sessio...
(DOUBLE_PUNCTUATION_XML)
[style] ~56-~56: “dentro de um” é uma expressão prolixa. É preferível dizer “num” ou “em um”.
Context: ...ecuta a partir de um shell comum, e não dentro de um editor de IA. O comando então encerra c...
(PT_WORDINESS_REPLACE_DENTRO_DE_UM)
[uncategorized] ~62-~62: Pontuação duplicada
Context: ...mais recente para a mais antiga. Aceita --editor. ```bash archgate session-conte...
(DOUBLE_PUNCTUATION_XML)
[misspelling] ~70-~70: Possível erro ortográfico.
Context: ...icado pelo ambiente. Aceita --editor, --max-entries e --root. ```bash archgate session-...
(PT_MULTITOKEN_SPELLING_HYPHEN)
[uncategorized] ~81-~81: Pontuação duplicada
Context: ...da podem ser lidas por ID com show, e --root resolve uma sessão-filha até seu a...
(DOUBLE_PUNCTUATION_XML)
🔇 Additional comments (31)
src/helpers/session-context.ts (1)
12-22: LGTM!Also applies to: 43-47
tests/helpers/session-context-cursor.test.ts (1)
23-23: LGTM!Also applies to: 40-46
tests/helpers/session-context.test.ts (1)
44-72: LGTM!Also applies to: 152-157
src/helpers/paths.ts (1)
38-38: LGTM!src/helpers/harness-detect.ts (1)
1-125: LGTM!src/helpers/session-context-auto.ts (1)
1-291: LGTM!tests/helpers/harness-detect.test.ts (1)
1-169: LGTM!tests/helpers/session-context-auto.test.ts (1)
1-179: LGTM!Also applies to: 192-335
src/commands/session-context.ts (1)
29-48: LGTM!Also applies to: 65-123
tests/commands/session-context.test.ts (1)
7-43: LGTM!Also applies to: 52-136
src/cli.ts (1)
20-20: 🗄️ Data Integrity & IntegrationNo change needed.
src/commands/session-context.tsis the only session-context command module, the oldsrc/commands/session-context/directory is absent, and there are no stale references to the directory form..archgate/adrs/ARCH-004-no-barrel-files.md (1)
44-44: LGTM!.archgate/adrs/ARCH-014-prefer-bun-env.md (1)
53-59: LGTM!.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md (1)
41-41: LGTM!Also applies to: 78-78
.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.rules.ts (1)
112-113: LGTM!CLAUDE.md (2)
109-109: LGTM!
107-107: 📐 Maintainability & Code QualityNo change needed.
The checklist symbols
DetectedHarness,SIGNALS,listFor/readFor, andEDITORSall exist in the referenced files.docs/src/content/docs/pt-br/guides/cursor-integration.mdx (1)
150-150: LGTM!Also applies to: 157-157
docs/src/content/docs/pt-br/reference/cli/session-context.mdx (1)
9-31: LGTM!Also applies to: 37-56, 58-113
docs/src/content/docs/reference/cli/session-context.mdx (3)
9-31: LGTM!Also applies to: 37-52, 56-113
33-54: 🗄️ Data Integrity & IntegrationConfirm the detection semantics before both reference pages ship. The English page and its pt-br mirror state the same two claims: a stale published session id falls back to recency, and multiple candidates resolve in the order Claude Code, Copilot, Cursor. Neither claim is provable from the supplied excerpts of
src/helpers/harness-detect.tsandsrc/helpers/session-context-auto.ts. One verification settles both pages.
docs/src/content/docs/reference/cli/session-context.mdx#L33-L54: correct the stale-id sentence and the precedence sentence if the implementation differs.docs/src/content/docs/pt-br/reference/cli/session-context.mdx#L33-L54: apply the same correction to the translated sentences so the locale mirror stays in parity.
33-33: 🗄️ Data Integrity & IntegrationNo change needed.
The stale published session id falls back to recency, and the documented
SIGNALSprecedence matches Claude Code, Copilot, and Cursor in that order.docs/public/llms-full.txt (3)
1429-1429: LGTM!
1727-1734: LGTM!
4822-4825: 🗄️ Data Integrity & IntegrationUpdate the four mirrored plugin references.
This public
session-contextreference no longer uses positional editor arguments. Sync the plugin-repositorycommands.mdcopies witharchgate session-context list,archgate session-context show <session-id>,--editor, and--root, and remove any stalesession-context claude-code/session-context cursorsyntax.docs/src/content/docs/guides/claude-code-plugin.mdx (1)
139-139: LGTM!docs/src/content/docs/nb/guides/claude-code-plugin.mdx (1)
139-139: LGTM!docs/src/content/docs/nb/guides/cursor-integration.mdx (1)
150-157: LGTM!docs/src/content/docs/nb/reference/cli/session-context.mdx (1)
9-56: LGTM!Also applies to: 60-81, 83-112
docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx (1)
139-139: LGTM!docs/src/content/docs/guides/cursor-integration.mdx (1)
150-157: 📐 Maintainability & Code QualityNo action needed.
The repository contains only documentation and tests for the new subcommand syntax; no
commands.mdskill-reference copies are present in this repository.
Commander hoists an option the parent also declares, so `show <id> --root` was parsed by `session-context` rather than by `show`, and the subcommand read `undefined`. The flag was accepted and then silently did nothing. `--root` now resolves through the same merge as `--max-entries` and `--editor`. Reaching it is what surfaces the guard: `show <id> --root` on a non-opencode editor is rejected rather than ignored. Dispatch moves from switch statements to Record<DetectedHarness, …> lookups. The record keys give the same exhaustiveness guarantee at compile time, so the `default:` arms that existed only to satisfy consistent-return — branches TypeScript proved unreachable — are gone rather than sitting uncovered. Action-handler coverage lands in tests/commands/session-context-actions.test.ts, a sibling of the wiring tests to stay under the 500-line cap. It is what caught the --root defect. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
… list DETECTED_HARNESSES becomes the single source of truth and DetectedHarness is derived from it, so the choices `--editor` offers cannot drift from what the detection layer recognizes. Adding an editor to that list is a compile error in the dispatch records until its reader exists. Detection signals stay a list, so an editor could still be added without a marker and silently never match; a test now asserts every entry is detectable. The transcript-cap test asserted only that a `transcript` field existed, against a single-entry fixture, so it passed whether or not maxEntries reached the reader. The fixture now holds several entries and the assertion is on the resulting length. Also replaces a per-iteration expect() with a whole-value assertion (ARCH-025), and aligns the guides on "options" with the reference pages across all three locales. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Both editors are detected from the environment and read like the others. Codex publishes CODEX_THREAD_ID, injected after its sandbox env policy runs so the marker survives filtering — unlike CODEX_SANDBOX, which exists only on macOS. The thread id is also the rollout filename, so it pins directly. Rollouts live under date shards and record their cwd in a session_meta line; those older than a week are zstd-compressed in place, so both .jsonl and .jsonl.zst are read. The CLI and the desktop app share the store. Pi publishes PI_CODING_AGENT on every child and PI_SESSION_ID to the commands its agent runs. Sessions sit in a directory encoding the working directory, and each file's header cwd is checked too, so a relocated session directory still resolves. Adding both to DETECTED_HARNESSES was a compile error until their readers existed, and the "every editor is detectable" test failed until their signals were registered — the guards behaved as intended. Rollouts and sessions are parsed with Bun.JSONL.parse, which drops a trailing partial line: the live session, the one a caller most often asks for, is being appended to while it is read. normalizePath moves to session-context.ts rather than gaining a third and fourth copy. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 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 `@docs/src/content/docs/guides/cursor-integration.mdx`:
- Line 152: Clarify the automatic Cursor selection statement in
docs/src/content/docs/guides/cursor-integration.mdx: explain that no editor is
needed only when Cursor is detected, and document --editor cursor for forcing
Cursor. Apply the same meaning in
docs/src/content/docs/nb/guides/cursor-integration.mdx and
docs/src/content/docs/pt-br/guides/cursor-integration.mdx, using each locale’s
language.
In `@src/helpers/session-context-codex.ts`:
- Around line 166-171: Update the rollout discovery flow around the Promise.all
files.map call to avoid reading and decompressing every rollout concurrently.
Process files sequentially or through a bounded-concurrency worker pool,
retaining only each file’s parsed metadata and preserving the existing { file,
meta } result shape.
In `@src/helpers/session-context-pi.ts`:
- Around line 115-155: Update readPiHeader to read only a bounded prefix using
Bun.file(file).slice(0, probeSize).text() instead of loading the full
transcript, and define a probe size safely larger than the maximum possible
session header length. Preserve the existing first-line extraction, schema
validation, and null-on-read-failure behavior.
In `@tests/commands/session-context-actions.test.ts`:
- Around line 42-49: Update the test setup and teardown around beforeEach to
capture the existing ARCHGATE_PROJECT_CEILING value before overwriting it, then
restore that value with restoreEnv during cleanup instead of deleting the
variable unconditionally. Import and reuse the existing restoreEnv helper
alongside safeRmSync, preserving the original environment across the shared Bun
test process.
- Around line 123-129: Update the “exits 1 when the reader reports a failure”
test to store the promise returned by run(), await its rejection, and drain the
rejection before inspecting exitSpy or errorText(). Ensure assertions occur only
after the asynchronous readAutoSession/listAutoSessions/readAutoSessionById and
exitWith operations complete.
🪄 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: 96117bc9-adbf-49f9-880f-24371586bea7
📒 Files selected for processing (22)
docs/public/llms-full.txtdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxsrc/commands/session-context.tssrc/helpers/harness-detect.tssrc/helpers/paths.tssrc/helpers/session-context-auto.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-copilot.tssrc/helpers/session-context-opencode.tssrc/helpers/session-context-pi.tssrc/helpers/session-context.tstests/commands/session-context-actions.test.tstests/commands/session-context.test.tstests/helpers/harness-detect.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.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 (26)
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/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.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: Keep English content at the root and mirror every English MDX file in each locale directory (pt-brandnb) with the same relative path and filename; do not create orphan translations.
When English documentation is added or modified, update the corresponding locale files in the same pull request.
Translate user-facing prose, titles, descriptions, headings, list items, table text, admonitions, and Starlight component text props; keep code blocks, CLI commands, file paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX curly-brace escaping, component imports, structural MDX elements, and internal link paths; internal links must not include locale prefixes.
Do not use machine translation without human review for technical accuracy.
Files:
docs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.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/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/public/llms-full.txtdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-021-authored-text-integrity.md)
Markdown and MDX text content MUST NOT contain a backslash-escaped backtick. Use a longer code-span delimiter or restructure the sentence instead. The rule excludes YAML frontmatter, fenced code blocks, and
CHANGELOG.md.
Files:
docs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdx
**
⚙️ 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:
docs/src/content/docs/guides/cursor-integration.mdxtests/commands/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tsdocs/src/content/docs/reference/cli/session-context.mdxdocs/public/llms-full.txtsrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tsdocs/src/content/docs/pt-br/reference/cli/session-context.mdxsrc/helpers/session-context-pi.tsdocs/src/content/docs/nb/guides/cursor-integration.mdxsrc/commands/session-context.tsdocs/src/content/docs/nb/reference/cli/session-context.mdxtests/helpers/harness-detect.test.tsdocs/src/content/docs/pt-br/guides/cursor-integration.mdxsrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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.Use TypeScript strict mode with ESNext and ES modules.
Files:
tests/commands/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
**/*.{js,ts,tsx,mjs,cjs}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-003-tool-invocation-via-scripts.md)
Invoke linting, formatting, and validation through package scripts (
bun run lint,bun run format,bun run format:check, andbun run validate), rather than directly invoking tool binaries such asbunx prettier,bunx oxfmt,npx eslint, oroxlint.
Files:
tests/commands/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-025-idiomatic-bun-test-parametrization-and-matchers.md)
tests/**/*.test.ts: Usetest.each()ordescribe.each()for the same assertion logic against multiple independent inputs. Do not register tests or callexpect()once per case inside aforor.forEachloop.
Use array rows for positional destructuring and object rows for named fields when passing cases totest.each()ordescribe.each(). Choose descriptive title placeholders such as%s,%p,%d, or$field.
Assert derived facts with the most specific matcher available instead of passing a derived boolean to.toBe(true)or.toBe(false). Compare values directly with.toBe()or.toEqual().
Use specific matchers for common derived checks:.toContain()or.toMatch()for containment,.toBeInstanceOf()for type checks such asArray.isArray,.toHaveLength()for counts, and.find()with.toBeDefined()or.toBeUndefined()for predicate existence checks.
Do not precompute a boolean solely to assert it; assert the underlying values directly with matchers such as.toEqual()or.toBe().
When converting a loop totest.each()ordescribe.each(), preserve every assertion that ran per iteration; do not drop or merge assertions.
tests/**/*.test.ts: Every runnable test must contain anexpect()assertion; usetest.skiportest.todofor placeholders rather than assertion-less or silently skipped tests.
Test public interfaces with descriptive names rather than private implementation details.
Do not usemock.module()for first-party modules. Mock them withimport * as modplusspyOn(mod, "fn"), and restore mocks after each test.mock.module()may be used for approved external modules such asinquirerornode:readline.
For HTTP mocking, saveglobalThis.fetchbefore direct assignment and restore it inafterEach; do not usemock.module("node:fetch"), which does not intercept Bun's global fetch.
Wrap inlinespyOnormockImplementationlifecycles intry/finally, or manage them in hooks, somockRestore()runs wh...
Files:
tests/commands/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.test.ts
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.ts: Use Bun's built-inbun:testrunner for all tests; do not importnode:test. Test files belong undertests/, mirrorsrc/, usetests/fixtures/for shared fixtures, and follow<module-name>.test.tsnaming.
Filesystem tests must use isolatedmkdtempdirectories and clean them up inafterEachorafterAll; do not touch real user-scope paths or leave temporary files behind.
Close external SDK instances, servers, clients, and transports in test hooks, such asawait server.close()inafterEachorafterAll.
Restore every captured environment variable withrestoreEnv(key, original); never restore with direct assignment such asBun.env.X = original, becauseundefinedbecomes the string"undefined".
Mockos.homedir()via an imported module namespace andspyOn; do not rely on overridingHOMEfor code usingos.homedir(), and keep filesystem writes inside temporary directories.
Shared test helpers, including non-test files undertests/, must restore every captured environment variable withrestoreEnv; isolation responsibilities apply across the entire shared Bun test process.Use
_resetAllCaches()fromsrc/helpers/platform.tsto simulate different platforms in tests rather than mockingprocess.platformdirectly.Tests mirror
src/; fixtures belong undertests/fixtures/. Update exact editor choice-list tests and editor-detection length/order assertions when adding an editor.
Files:
tests/commands/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.test.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-018-lazy-load-heavy-dependencies.md)
src/**/*.ts: Heavy runtime dependencies such asinquirer,posthog-node, and@sentry/*must be loaded with dynamicimport()at their point of use, never through top-level static value imports.
Type-only imports for heavy dependencies are allowed, but runtime values must be obtained through dynamicimport(); for example, useimport type { PostHog } from "posthog-node".
SDKs that require early initialization may use eager-start/lazy-await: begin initialization before command registration and await the result at first use, such as in apreActionhook.
src/**/*.ts: Everyinquirer.prompt(...)call must be wrapped inwithPromptFix(() => ...)imported fromsrc/helpers/prompt.ts; keep the wrapper adjacent to the prompt invocation so automated checks can detect it.
Do not callinquirer.prompt(...)directly or reimplement cursor/newline fixes at individual call sites; route all prompt behavior throughwithPromptFix().Every call to
Bun.Glob#scan()(glob.scan(...)) in source must pass{ dot: true }in its options object, including scans whose patterns do not explicitly target dot-directories. Do not usedot: false; intentionally excluded dotfiles must be filtered explicitly after scanning with a comment. Normalize scanned path separators withfile.replaceAll("\\", "/")when performing cross-platform path comparisons.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all colored CLI output; do not use raw ANSI escape codes or third-party color libraries such as chalk, kleur, or picocolors.
Commands producing structured results must support machine-readable output through--json, orcheck's canonical--output <format>selector.
UseformatJSON()fromsrc/helpers/output.tsfor command JSON serialization; passforcePretty: trueor its equivalent when pretty JSON is explicitly requested.
UseisAgentContext()for automatic JSON selection; only JSON may auto-upgrade in agent context, whilegithubandsarifremai...
Files:
src/helpers/session-context-copilot.tssrc/helpers/paths.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
src/**/!(platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
All platform detection in
src/must go throughsrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(), orgetPlatformInfo()); directprocess.platformaccess and duplicated detection logic are forbidden outsideplatform.ts.
Files:
src/helpers/session-context-copilot.tssrc/helpers/paths.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
src/helpers/paths.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-014-prefer-bun-env.md)
Normalize environment-variable values through
usableEnv()before using them as lookup keys, path segments, or identifiers; it maps empty strings and the literal string"undefined"tonull.For user-scope editors, mirror the editor's actual path resolution rather than assuming Windows conventions; opencode uses
xdg-basedirand falls back to~/.configon all platforms.
Files:
src/helpers/paths.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 top-level CLI command must have exactly one corresponding English reference page atdocs/src/content/docs/reference/cli/<name>.mdx; every page exceptindex.mdxmust correspond to a command.
Document subcommands inline in their parent command page; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Command reference pages should follow the established MDX structure:titleanddescriptionfrontmatter, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
{src/commands/**/*.ts,docs/src/content/docs/reference/cli/**/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every module-backed subcommand under
src/commands/<parent>/, at any nesting depth, must have a matching case-insensitive heading containing its full command path indocs/src/content/docs/reference/cli/<parent>.mdx; conversely, headings backed entirely by command-group directories must correspond to an actual subcommand module.
Files:
docs/src/content/docs/reference/cli/session-context.mdxsrc/commands/session-context.ts
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Document subcommands using the standard heading format containing the full command path, such as
## archgate <parent> <sub>, and do not create separate MDX files for subcommands.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
src/helpers/{init-project,plugin-install,editor-detect,harness-detect,session-context-auto}.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Keep editor installation detection separate from runtime harness detection: editor detection may use config directories or PATH, while harness detection must rely only on variables injected into subprocesses.
Files:
src/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
src/helpers/{harness-detect,session-context-auto}.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor whose transcripts need support, extend
DetectedHarness, theSIGNALStable, and thelistFor/readForswitches.
Files:
src/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
docs/src/content/docs/pt-br/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Create a matching pt-br mirror for each English CLI reference page; internationalization parity is enforced separately by GEN-002.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Brazilian Portuguese translations must use correct diacritical marks, including characters such as
ã,ç,é,í,ó,ú,â,ê,ô, andà.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdx
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Norwegian translations must use Bokmål rather than Nynorsk, use informal
du, and preserve correct characters such asæ,ø, andå.
Files:
docs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdx
src/commands/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-011-consistent-project-root-resolution.md)
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: Each command module must export aregister*Command(program)function; each non-index.tscommand file must define exactly one command.
Command files must remain thin: parse arguments, call engine/helpers, 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 files must not call.parse(); argument parsing is handled by the CLI entry point.
Commands should use typed Commander registration APIs, such as@commander-js/extra-typings, within theirregister*Commandfunctions.
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()instead of.option().
Use.choices([... ] as const)for options accepting a fixed set of values, and use.default(... as const)when providing a default, preserving literal type inference.
Use.argParser((value) => ...)on anOptionfor type-converting options; do not pass parser functions such asparseIntas the third argument to...
Files:
src/commands/session-context.ts
src/commands/{*.ts,*/index.ts}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Top-level command modules must follow the
src/commands/<name>.tsorsrc/commands/<name>/index.tsconvention. Nested subcommand files do not count as top-level commands.
Files:
src/commands/session-context.ts
src/commands/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Each command module must export a
register*Command(program)function, handle I/O only, and contain no business logic.
Files:
src/commands/session-context.ts
src/commands/{init.ts,session-context.ts}
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, update the relevant editor directory, signup-editor, choice-list, manual-instruction, and session-context editor lists.
Files:
src/commands/session-context.ts
🧠 Learnings (16)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T06:03:08.635Z
Learning: When website CLI documentation changes, manually update the four identical skill-reference `commands.md` copies in the separate `archgate/plugins` repository so they remain synchronized.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T06:03:08.635Z
Learning: Reviewers must verify that added subcommands receive a parent-page heading, removed subcommands have their heading deleted, and the external skill reference is updated in the same change.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T06:03:19.593Z
Learning: `bun run validate` must pass before any task is considered complete; it runs lint, typecheck, format check, tests, ADR checks, dead-export detection, and the build check.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T06:03:19.593Z
Learning: Read the relevant self-governance ADRs and companion `.rules.ts` files before making architectural changes.
📚 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/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.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/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
📚 Learning: 2026-08-04T19:58:05.877Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 543
File: src/helpers/copilot-user-settings.ts:0-0
Timestamp: 2026-08-04T19:58:05.877Z
Learning: In archgate/cli TypeScript code, use `Bun.file(path).exists()` only to check whether a file exists; it must not be used for directory existence checks. For helpers such as `isCopilotAvailable()` that need to detect a configuration directory, use an appropriate directory-aware check such as `existsSync` from `node:fs`.
Applied to files:
tests/commands/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
📚 Learning: 2026-08-05T06:56:33.435Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 546
File: tests/integration/stream-guards.test.ts:3-9
Timestamp: 2026-08-05T06:56:33.435Z
Learning: When reviewing GEN-004 comment-block limits in the Archgate CLI repository, count only narrative prose lines within a block comment. Do not count a closing delimiter such as `*/` as a prose line; for example, in `tests/integration/stream-guards.test.ts`, Lines 4–8 contain five prose lines while Line 9 contains only the delimiter.
Applied to files:
tests/commands/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.ts
📚 Learning: 2026-08-06T21:09:28.014Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 561
File: src/helpers/binary-upgrade.ts:239-287
Timestamp: 2026-08-06T21:09:28.014Z
Learning: In archgate/cli TypeScript code, follow ARCH-007 for Bun subprocess stream capture; ARCH-017 does not govern subprocess pipe handling. When Bun.spawn() uses piped stdout or stderr, use a shared capture helper where practical, consume configured streams concurrently to avoid deadlocks, and verify the subprocess exit code before trusting captured output.
Applied to files:
tests/commands/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.test.ts
📚 Learning: 2026-08-05T16:54:13.117Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/commands/adr/domain/remove.test.ts:21-24
Timestamp: 2026-08-05T16:54:13.117Z
Learning: In the Archgate CLI test suite, continue using `z.object` for JSON output schemas unless a repository-wide testing policy explicitly adopts `z.strictObject`. Do not introduce strict CLI-output schema enforcement as an isolated change in a coverage-focused pull request; require coordinated updates and policy agreement across affected tests.
Applied to files:
tests/commands/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.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/session-context.test.tssrc/helpers/session-context-copilot.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tssrc/helpers/session-context-pi.tssrc/commands/session-context.tstests/helpers/harness-detect.test.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.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/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.test.ts
📚 Learning: 2026-08-05T16:54:50.574Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/helpers/plugin-install-cursor-hooks.test.ts:44-44
Timestamp: 2026-08-05T16:54:50.574Z
Learning: In this repository, every TypeScript module under `src/` must have a matching `<module-name>.test.ts` file under the mirrored `tests/` directory, as required by ARCH-005. Supplemental behavior-suffixed sibling test files are allowed only when the matching parent test file exists. Use such siblings to keep individual test files below the 500-line oxlint limit.
Applied to files:
tests/commands/session-context.test.tstests/commands/session-context-actions.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.test.ts
📚 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/session-context-copilot.tssrc/helpers/paths.tssrc/helpers/session-context-opencode.tssrc/helpers/harness-detect.tssrc/helpers/session-context-pi.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-auto.tssrc/helpers/session-context.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/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.tstests/helpers/harness-detect.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/session-context.ts
🪛 LanguageTool
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
[style] ~19-~19: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...i. Por padrão, o editor detectado. | | --max-entries ` | Número máximo de entradas a retorna...
(INTERNET_ABBREVIATIONS)
[uncategorized] ~56-~56: Pontuação duplicada
Context: ...e ambiente que identificou o editor, ou --editor quando você informou um. `sessio...
(DOUBLE_PUNCTUATION_XML)
🪛 OpenGrep (1.26.0)
src/helpers/session-context-codex.ts
[ERROR] 146-146: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
🔇 Additional comments (19)
docs/public/llms-full.txt (2)
1429-1429: LGTM!Also applies to: 1727-1734
4822-4929: 📐 Maintainability & Code QualityUpdate the
archgate/pluginsskill-reference copies or defer merge until they are synchronized.The source page uses
archgate session-context list/show,--editor, and--root, with no obsolete positional-editor or--session-idforms. Keep the fourarchgate/pluginscommands reference copies in sync with this source before this CLI contract reaches release docs distribution.docs/src/content/docs/nb/reference/cli/session-context.mdx (1)
16-20: LGTM!Also applies to: 29-33, 56-56, 81-84
docs/src/content/docs/pt-br/reference/cli/session-context.mdx (1)
16-20: LGTM!Also applies to: 29-33, 56-56, 81-84
docs/src/content/docs/reference/cli/session-context.mdx (2)
29-33: LGTM!Also applies to: 56-56, 81-84
16-20: 📐 Maintainability & Code QualityVerify the external plugin command updates with CLI access.
The
archgate/pluginsreference may be no longer publicly accessible; check whether the matchingcommands.mdcopies still use the unifiedsession-context list/showsyntax with--editorinstead of editor-specific subcommands.src/helpers/harness-detect.ts (1)
13-27: LGTM!Also applies to: 71-78, 90-96
src/helpers/session-context-auto.ts (1)
21-21: LGTM!Also applies to: 30-30, 106-175
tests/helpers/session-context-auto.test.ts (1)
52-76: LGTM!Also applies to: 107-107, 200-221, 281-308
src/commands/session-context.ts (1)
7-7: LGTM!Also applies to: 21-29, 52-56, 65-71, 149-149
src/helpers/session-context.ts (1)
5-21: LGTM!src/helpers/session-context-opencode.ts (1)
14-14: LGTM!src/helpers/paths.ts (1)
96-135: LGTM!tests/helpers/harness-detect.test.ts (1)
15-40: LGTM!Also applies to: 68-84
src/helpers/session-context-codex.ts (1)
1-165: LGTM!Also applies to: 173-308
tests/helpers/session-context-codex.test.ts (1)
1-243: LGTM!tests/helpers/session-context-pi.test.ts (1)
1-236: LGTM!tests/commands/session-context.test.ts (1)
26-26: LGTM!Also applies to: 46-47
src/helpers/session-context-copilot.ts (1)
4-16: LGTM!
…heads Discovery inflated every compressed rollout at once, holding each inflated transcript in memory together — a sessions directory grows without bound, so one `list` scaled with the whole history rather than with the answer. Rollout discovery now runs through a bounded pool, and classification reads only the head of a rollout: the session_meta line sits at the top, so the transcript below it need never be read. Compressed rollouts still inflate whole, since a member cannot be read partially. Pi's header read is likewise a head slice rather than the entire session. Tests capture and restore ARCHGATE_PROJECT_CEILING instead of deleting it, and the exit-path tests drain the action promise before inspecting the spies rather than relying on microtask ordering. The Cursor guide claimed no editor need ever be named; that holds only when Cursor is the detected editor, so it now says so and points at --editor. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Coverage sat exactly on the 99.5% threshold, leaving roughly one line of headroom before an unrelated commit would fail the gate. Adds the paths that were carrying no test: listing against a missing store, the PI_CODING_AGENT_DIR override, the filename fallback each reader uses when a session records no id of its own, and dispatch to the Codex and Pi readers. The dispatch tests also pin CODEX_HOME and PI_CODING_AGENT_DIR into the temp home. Without them those two readers resolve the developer's real ~/.codex and ~/.pi, which exist on a machine that runs either tool. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
The Antigravity CLI (`agy`) marks its subprocesses with ANTIGRAVITY_AGENT and publishes ANTIGRAVITY_CONVERSATION_ID, which names the conversation directly. Turns come from the JSONL the CLI writes under brain/<id>/.system_generated/logs/, whose entries carry named types and plain text. A planner turn that only issued a tool call has empty content and is skipped rather than emitted as a blank assistant turn, and a user turn's text is taken from inside its <USER_REQUEST> wrapper — metadata follows the closing tag, so trimming the ends would leak it. The workspace a conversation belongs to comes from its own SQLite database: the shared summaries database indexes the IDE's conversations, not the CLI's. The URI is embedded in a protobuf blob, so the scan is bounded to URI-legal characters; a permissive one runs into the following tag bytes and matches no project at all. The Antigravity IDE is a separate store and stays unsupported: it encrypts conversations at rest through Electron safeStorage, so reading them would mean circumventing that rather than integrating with it. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
tests/helpers/session-context-auto.test.ts (1)
35-50: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winClear all harness environment variables in these tests.
HARNESS_VARSomitsANTIGRAVITY_AGENT,ANTIGRAVITY_CONVERSATION_ID,CODEX_THREAD_ID,PI_CODING_AGENT, andPI_SESSION_ID. An ambient marker can select an unintended editor and make detection tests depend on the runner environment. Add these variables to this array so the hooks clear and restore them.🤖 Prompt for 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. In `@tests/helpers/session-context-auto.test.ts` around lines 35 - 50, Add ANTIGRAVITY_AGENT, ANTIGRAVITY_CONVERSATION_ID, CODEX_THREAD_ID, PI_CODING_AGENT, and PI_SESSION_ID to the HARNESS_VARS array in session-context-auto tests, preserving the existing clear-and-restore behavior for all harness environment variables.Source: Coding guidelines
docs/public/llms-full.txt (1)
4916-4920: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winClarify the opencode selection mode.
Lines [4916-4920] describe
archgate session-context --editor opencodeas reading another editor’s current session. opencode has no published session ID and selects the most recent top-level session. Say “most recent opencode session” or use an editor with pinned-session support.Based on learnings,
docs/public/llms-full.txtis generated fromdocs/src/content/docs/**; update the source MDX and regenerate this artifact.🤖 Prompt for 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. In `@docs/public/llms-full.txt` around lines 4916 - 4920, Update the source MDX documentation for the archgate session-context example to describe opencode as selecting the most recent opencode session rather than another editor’s current session, then regenerate docs/public/llms-full.txt so the generated artifact reflects the corrected wording.Source: Learnings
🤖 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 `@docs/public/llms-full.txt`:
- Line 4870: Update the source MDX documentation that generates this passage so
the precedence rule says editors with a valid, non-empty session ID win, while
empty or invalid IDs fall back to recency; then regenerate
docs/public/llms-full.txt to reflect the source change.
---
Outside diff comments:
In `@docs/public/llms-full.txt`:
- Around line 4916-4920: Update the source MDX documentation for the archgate
session-context example to describe opencode as selecting the most recent
opencode session rather than another editor’s current session, then regenerate
docs/public/llms-full.txt so the generated artifact reflects the corrected
wording.
In `@tests/helpers/session-context-auto.test.ts`:
- Around line 35-50: Add ANTIGRAVITY_AGENT, ANTIGRAVITY_CONVERSATION_ID,
CODEX_THREAD_ID, PI_CODING_AGENT, and PI_SESSION_ID to the HARNESS_VARS array in
session-context-auto tests, preserving the existing clear-and-restore behavior
for all harness environment variables.
🪄 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: c3df7fa7-37a4-470a-849d-a301c9ff7568
📒 Files selected for processing (20)
docs/public/llms-full.txtdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxsrc/helpers/harness-detect.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-auto.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-pi.tstests/commands/session-context-actions.test.tstests/commands/session-context.test.tstests/helpers/harness-detect.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Smoke Test (Windows) / Windows
🧰 Additional context used
📓 Path-based instructions (22)
{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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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.Use TypeScript in strict mode with ESNext and ES modules; the project runs on Bun rather than Node.js.
Files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
**/*.{js,ts,tsx,mjs,cjs}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-003-tool-invocation-via-scripts.md)
Invoke linting, formatting, and validation through package scripts (
bun run lint,bun run format,bun run format:check, andbun run validate), rather than directly invoking tool binaries such asbunx prettier,bunx oxfmt,npx eslint, oroxlint.
Files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-025-idiomatic-bun-test-parametrization-and-matchers.md)
tests/**/*.test.ts: Usetest.each()ordescribe.each()for the same assertion logic against multiple independent inputs. Do not register tests or callexpect()once per case inside aforor.forEachloop.
Use array rows for positional destructuring and object rows for named fields when passing cases totest.each()ordescribe.each(). Choose descriptive title placeholders such as%s,%p,%d, or$field.
Assert derived facts with the most specific matcher available instead of passing a derived boolean to.toBe(true)or.toBe(false). Compare values directly with.toBe()or.toEqual().
Use specific matchers for common derived checks:.toContain()or.toMatch()for containment,.toBeInstanceOf()for type checks such asArray.isArray,.toHaveLength()for counts, and.find()with.toBeDefined()or.toBeUndefined()for predicate existence checks.
Do not precompute a boolean solely to assert it; assert the underlying values directly with matchers such as.toEqual()or.toBe().
When converting a loop totest.each()ordescribe.each(), preserve every assertion that ran per iteration; do not drop or merge assertions.
tests/**/*.test.ts: Every runnable test must contain anexpect()assertion; usetest.skiportest.todofor placeholders rather than assertion-less or silently skipped tests.
Test public interfaces with descriptive names rather than private implementation details.
Do not usemock.module()for first-party modules. Mock them withimport * as modplusspyOn(mod, "fn"), and restore mocks after each test.mock.module()may be used for approved external modules such asinquirerornode:readline.
For HTTP mocking, saveglobalThis.fetchbefore direct assignment and restore it inafterEach; do not usemock.module("node:fetch"), which does not intercept Bun's global fetch.
Wrap inlinespyOnormockImplementationlifecycles intry/finally, or manage them in hooks, somockRestore()runs wh...
Files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.test.ts
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.ts: Use Bun's built-inbun:testrunner for all tests; do not importnode:test. Test files belong undertests/, mirrorsrc/, usetests/fixtures/for shared fixtures, and follow<module-name>.test.tsnaming.
Filesystem tests must use isolatedmkdtempdirectories and clean them up inafterEachorafterAll; do not touch real user-scope paths or leave temporary files behind.
Close external SDK instances, servers, clients, and transports in test hooks, such asawait server.close()inafterEachorafterAll.
Restore every captured environment variable withrestoreEnv(key, original); never restore with direct assignment such asBun.env.X = original, becauseundefinedbecomes the string"undefined".
Mockos.homedir()via an imported module namespace andspyOn; do not rely on overridingHOMEfor code usingos.homedir(), and keep filesystem writes inside temporary directories.
Shared test helpers, including non-test files undertests/, must restore every captured environment variable withrestoreEnv; isolation responsibilities apply across the entire shared Bun test process.Use
_resetAllCaches()fromsrc/helpers/platform.tsto simulate different platforms in tests rather than mockingprocess.platformdirectly.Test files may use
process.envfor setup and teardown when test-harness compatibility requires it.
Files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.test.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Tests live under
tests/, mirrorsrc/, and use fixtures undertests/fixtures/; run the configured test command rather than barebun test.
Files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.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/helpers/harness-detect.test.tsdocs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxtests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tsdocs/src/content/docs/nb/guides/cursor-integration.mdxsrc/helpers/session-context-antigravity.tsdocs/public/llms-full.txtsrc/helpers/session-context-codex.tssrc/helpers/paths.tsdocs/src/content/docs/reference/cli/session-context.mdxtests/commands/session-context-actions.test.tsdocs/src/content/docs/nb/reference/cli/session-context.mdxsrc/helpers/harness-detect.tsdocs/src/content/docs/pt-br/reference/cli/session-context.mdxsrc/helpers/session-context-auto.ts
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/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.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: Keep English content at the root and mirror every English MDX file in each locale directory (pt-brandnb) with the same relative path and filename; do not create orphan translations.
When English documentation is added or modified, update the corresponding locale files in the same pull request.
Translate user-facing prose, titles, descriptions, headings, list items, table text, admonitions, and Starlight component text props; keep code blocks, CLI commands, file paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX curly-brace escaping, component imports, structural MDX elements, and internal link paths; internal links must not include locale prefixes.
Do not use machine translation without human review for technical accuracy.
Files:
docs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.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/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/public/llms-full.txtdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Brazilian Portuguese translations must use correct diacritical marks, including characters such as
ã,ç,é,í,ó,ú,â,ê,ô, andà.
Files:
docs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-021-authored-text-integrity.md)
Markdown and MDX text content MUST NOT contain a backslash-escaped backtick. Use a longer code-span delimiter or restructure the sentence instead. The rule excludes YAML frontmatter, fenced code blocks, and
CHANGELOG.md.
Files:
docs/src/content/docs/pt-br/guides/cursor-integration.mdxdocs/src/content/docs/guides/cursor-integration.mdxdocs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-018-lazy-load-heavy-dependencies.md)
src/**/*.ts: Heavy runtime dependencies such asinquirer,posthog-node, and@sentry/*must be loaded with dynamicimport()at their point of use, never through top-level static value imports.
Type-only imports for heavy dependencies are allowed, but runtime values must be obtained through dynamicimport(); for example, useimport type { PostHog } from "posthog-node".
SDKs that require early initialization may use eager-start/lazy-await: begin initialization before command registration and await the result at first use, such as in apreActionhook.
src/**/*.ts: Everyinquirer.prompt(...)call must be wrapped inwithPromptFix(() => ...)imported fromsrc/helpers/prompt.ts; keep the wrapper adjacent to the prompt invocation so automated checks can detect it.
Do not callinquirer.prompt(...)directly or reimplement cursor/newline fixes at individual call sites; route all prompt behavior throughwithPromptFix().Every call to
Bun.Glob#scan()(glob.scan(...)) in source must pass{ dot: true }in its options object, including scans whose patterns do not explicitly target dot-directories. Do not usedot: false; intentionally excluded dotfiles must be filtered explicitly after scanning with a comment. Normalize scanned path separators withfile.replaceAll("\\", "/")when performing cross-platform path comparisons.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all colored CLI output; do not use raw ANSI escape codes or third-party color libraries such as chalk, kleur, or picocolors.
Commands producing structured results must support machine-readable output through--json, orcheck's canonical--output <format>selector.
UseformatJSON()fromsrc/helpers/output.tsfor command JSON serialization; passforcePretty: trueor its equivalent when pretty JSON is explicitly requested.
UseisAgentContext()for automatic JSON selection; only JSON may auto-upgrade in agent context, whilegithubandsarifremai...
Files:
src/helpers/session-context-pi.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
src/**/!(platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
All platform detection in
src/must go throughsrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(), orgetPlatformInfo()); directprocess.platformaccess and duplicated detection logic are forbidden outsideplatform.ts.
Files:
src/helpers/session-context-pi.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Norwegian translations must use Bokmål rather than Nynorsk, use informal
du, and preserve correct characters such asæ,ø, andå.
Files:
docs/src/content/docs/nb/guides/cursor-integration.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdx
src/helpers/paths.ts
📄 CodeRabbit inference engine (CLAUDE.md)
User-scope editor paths must match the target editor's actual resolver; for opencode, use
xdg-basedirsemantics, which fall back to~/.configon every platform, including Windows.
Files:
src/helpers/paths.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 top-level CLI command must have exactly one corresponding English reference page atdocs/src/content/docs/reference/cli/<name>.mdx; every page exceptindex.mdxmust correspond to a command.
Document subcommands inline in their parent command page; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Command reference pages should follow the established MDX structure:titleanddescriptionfrontmatter, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
docs/src/content/docs/reference/cli/*.mdx: Subcommand documentation headings MUST use the standard full command format, such as## archgate <parent> <sub>or### archgate <parent> <nested-subcommand>.
Subcommands MUST be documented inside the top-level parent reference page; do not create separate.mdxfiles for subcommands.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
{src/commands/**/*.ts,docs/src/content/docs/reference/cli/**/*.mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
Every module-backed subcommand under
src/commands/<parent>/, at any nesting depth, MUST have a case-insensitive heading containing its full command path indocs/src/content/docs/reference/cli/<parent>.mdx; conversely, headings whose parent chain consists of command-group directories MUST correspond to an actual subcommand module.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
src/helpers/harness-detect.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Harness detection must represent the editor running the current process using only variables injected into subprocesses; never use PATH or config-directory probes for runtime harness detection.
Files:
src/helpers/harness-detect.ts
docs/src/content/docs/pt-br/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Create a matching pt-br mirror for each English CLI reference page; internationalization parity is enforced separately by GEN-002.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
src/helpers/session-context-auto.ts
📄 CodeRabbit inference engine (CLAUDE.md)
When adding an editor, update the
listForandreadForswitches so its transcripts can be read.
Files:
src/helpers/session-context-auto.ts
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T09:41:14.718Z
Learning: Add a new subcommand's heading to the parent `.mdx` page in the same PR, and remove the heading when the subcommand is removed.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T09:41:14.718Z
Learning: When website CLI documentation changes, manually update the corresponding `commands.md` files in the separate `archgate/plugins` repository so all four copies remain synchronized.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T09:41:14.718Z
Learning: Option and flag accuracy, as well as subcommands registered inside a single module, remain manual code-review responsibilities and are not covered by this file-layout-based check.
📚 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/harness-detect.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.ts
📚 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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-08-04T19:58:05.877Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 543
File: src/helpers/copilot-user-settings.ts:0-0
Timestamp: 2026-08-04T19:58:05.877Z
Learning: In archgate/cli TypeScript code, use `Bun.file(path).exists()` only to check whether a file exists; it must not be used for directory existence checks. For helpers such as `isCopilotAvailable()` that need to detect a configuration directory, use an appropriate directory-aware check such as `existsSync` from `node:fs`.
Applied to files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-08-05T06:56:33.435Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 546
File: tests/integration/stream-guards.test.ts:3-9
Timestamp: 2026-08-05T06:56:33.435Z
Learning: When reviewing GEN-004 comment-block limits in the Archgate CLI repository, count only narrative prose lines within a block comment. Do not count a closing delimiter such as `*/` as a prose line; for example, in `tests/integration/stream-guards.test.ts`, Lines 4–8 contain five prose lines while Line 9 contains only the delimiter.
Applied to files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
📚 Learning: 2026-08-06T21:09:28.014Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 561
File: src/helpers/binary-upgrade.ts:239-287
Timestamp: 2026-08-06T21:09:28.014Z
Learning: In archgate/cli TypeScript code, follow ARCH-007 for Bun subprocess stream capture; ARCH-017 does not govern subprocess pipe handling. When Bun.spawn() uses piped stdout or stderr, use a shared capture helper where practical, consume configured streams concurrently to avoid deadlocks, and verify the subprocess exit code before trusting captured output.
Applied to files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.test.ts
📚 Learning: 2026-08-05T16:54:13.117Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/commands/adr/domain/remove.test.ts:21-24
Timestamp: 2026-08-05T16:54:13.117Z
Learning: In the Archgate CLI test suite, continue using `z.object` for JSON output schemas unless a repository-wide testing policy explicitly adopts `z.strictObject`. Do not introduce strict CLI-output schema enforcement as an isolated change in a coverage-focused pull request; require coordinated updates and policy agreement across affected tests.
Applied to files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tstests/commands/session-context-actions.test.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.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/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.test.ts
📚 Learning: 2026-08-05T16:54:50.574Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/helpers/plugin-install-cursor-hooks.test.ts:44-44
Timestamp: 2026-08-05T16:54:50.574Z
Learning: In this repository, every TypeScript module under `src/` must have a matching `<module-name>.test.ts` file under the mirrored `tests/` directory, as required by ARCH-005. Supplemental behavior-suffixed sibling test files are allowed only when the matching parent test file exists. Use such siblings to keep individual test files below the 500-line oxlint limit.
Applied to files:
tests/helpers/harness-detect.test.tstests/commands/session-context.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/commands/session-context-actions.test.ts
📚 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/session-context-pi.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/paths.tssrc/helpers/harness-detect.tssrc/helpers/session-context-auto.ts
🪛 LanguageTool
docs/src/content/docs/pt-br/guides/cursor-integration.mdx
[uncategorized] ~152-~152: Pontuação duplicada
Context: ..., não é preciso informar um editor. Use --editor cursor para ler as transcrições ...
(DOUBLE_PUNCTUATION_XML)
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
[style] ~19-~19: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...i. Por padrão, o editor detectado. | | --max-entries ` | Número máximo de entradas a retorna...
(INTERNET_ABBREVIATIONS)
[uncategorized] ~24-~24: Pontuação duplicada
Context: ...rir qual editor está perguntando. Passe --editor para sobrepor o resultado ou par...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~57-~57: Pontuação duplicada
Context: ...e ambiente que identificou o editor, ou --editor quando você informou um. `sessio...
(DOUBLE_PUNCTUATION_XML)
🪛 OpenGrep (1.26.0)
src/helpers/session-context-antigravity.ts
[ERROR] 110-110: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
[ERROR] 246-246: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
🔇 Additional comments (23)
src/helpers/harness-detect.ts (1)
18-25: LGTM!Also applies to: 67-73
src/helpers/paths.ts (1)
96-109: LGTM!src/helpers/session-context-auto.ts (1)
21-24: LGTM!Also applies to: 126-126, 165-169
src/helpers/session-context-antigravity.ts (1)
1-269: LGTM!src/helpers/session-context-codex.ts (1)
79-141: LGTM!Also applies to: 212-218
src/helpers/session-context-pi.ts (1)
141-160: LGTM!tests/helpers/harness-detect.test.ts (1)
15-17: LGTM!Also applies to: 35-35, 90-95
tests/helpers/session-context-antigravity.test.ts (1)
1-272: LGTM!tests/helpers/session-context-auto.test.ts (1)
97-98: LGTM!Also applies to: 293-297, 307-311
tests/helpers/session-context-codex.test.ts (1)
202-228: LGTM!tests/helpers/session-context-pi.test.ts (1)
207-261: LGTM!tests/commands/session-context.test.ts (1)
26-34: LGTM!tests/commands/session-context-actions.test.ts (1)
21-28: LGTM!Also applies to: 49-49, 81-81, 97-111, 144-144, 154-157, 159-162, 208-211, 213-216, 262-262, 272-275, 277-280
docs/public/llms-full.txt (3)
1429-1429: LGTM!
1727-1734: LGTM!
4822-4868: LGTM!Also applies to: 4872-4915, 4921-4931
docs/src/content/docs/guides/cursor-integration.mdx (1)
152-157: LGTM!docs/src/content/docs/nb/guides/cursor-integration.mdx (1)
152-157: LGTM!docs/src/content/docs/nb/reference/cli/session-context.mdx (2)
16-20: 🗄️ Data Integrity & IntegrationVerify the separate CLI documentation mirrors before merge.
This change updates the
session-contextoption and subcommand contract. Update the matchingcommands.mdfiles in the separatearchgate/pluginsrepository, including all four copies, so they use--editor,list, andshow <session-id>consistently.Based on learnings, website CLI documentation changes require manual updates to the
archgate/pluginscommands.mdcopies so all four copies remain synchronized.Source: Learnings
22-59: LGTM!Also applies to: 63-87, 89-118
docs/src/content/docs/pt-br/guides/cursor-integration.mdx (1)
152-157: LGTM!docs/src/content/docs/pt-br/reference/cli/session-context.mdx (1)
16-20: LGTM!Also applies to: 22-59, 63-87, 89-118
docs/src/content/docs/reference/cli/session-context.mdx (1)
22-59: LGTM!Also applies to: 63-87, 89-118
The desktop app sets ANTIGRAVITY_AGENT just as the CLI does, so detection already fired for it — but the reader looked only in the CLI's tree and reported that no conversation existed, which was wrong twice over: the app keeps its own tree, and it writes the same plaintext JSONL there. The earlier conclusion that the app's transcripts were unreadable came from its conversations/*.pb files, which are encrypted. That is one representation. The turns are also written to brain/<id>/.system_generated/logs/, in the clear and in the same shape the CLI uses. Both trees are now searched, preferring the untruncated transcript where a conversation has one. Workspace comes from the CLI conversation's own database or, for the app, the shared summaries index. That index lags a live conversation, so the conversation the caller is running inside is admitted without a workspace match — it is theirs by definition. The app names it only inside ANTIGRAVITY_SOURCE_METADATA, so detection reads the id from there when the flat variable is unset, and pinning works for both distributions. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
The suite cleared only the markers that existed when it was written, so the editors added since — Antigravity, Codex, Pi — could leak in from the ambient environment and select an editor a test never asked for. Antigravity ranks first in precedence, so running the suite inside it would have decided every detection test. Their store locations leaked the same way: Antigravity and Copilot resolve theirs from the home directory, which the os.homedir() spy does not reach, so the suite read the developer's real ~/.gemini and ~/.copilot. Antigravity also joins the dispatch cases, which had covered every other editor. The precedence sentence read as though publishing a session id were weighed per invocation. The order is fixed and the id is read only after the winner is chosen, so it now says so: an unusable id changes which session is selected, never which editor. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
Both findings from the latest review are addressed in Test isolation — valid, and worse than reported. The suite cleared only the markers that existed when it was written. Beyond the five variables named, Precedence wording — reworded, but not as suggested; reasoning is on that thread. |
…nt shape The Codex CLI and the desktop app record conversations differently. The desktop app flattens a turn into `event_msg` with a `user_message` or `agent_message` payload; the CLI emits `item_completed` and nests the text in content blocks under `item`. The reader knew only the flat shape, so every CLI rollout came back with a transcript of zero entries while reporting its full line count — the failure looked like an empty conversation rather than an unread format. Both shapes live under `event_msg`, so one pass reads either without double-counting. `response_item` still stays unread: it repeats the same turns wrapped in injected environment and developer messages. Found by reading a real CLI rollout. The synthetic fixtures only ever exercised the desktop shape, so they agreed with the reader and proved nothing. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Reading a real Pi session surfaced two defects. A turn that only made a tool call or thought carries empty content, and the reader emitted it as a blank entry, so a transcript came back padded with roles that said nothing. Pi also branches a session in place rather than starting a new file, linking entries by id/parentId, so `/fork` and `/rewind` leave their abandoned turns in the same file. Reading linearly would interleave them with the live conversation; the chain is now walked back from the newest entry. Sessions predating the tree format carry no ids and are read whole, which is correct for a linear session. Repeated turns are not deduplicated: Pi replays a user message after an empty generation and a model switch, and both entries sit on the active branch, so the repetition is the conversation rather than an artifact. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/helpers/harness-detect.ts (1)
175-184: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winFix the guard so a nested-only signal is readable, and align the TSDoc.
Line 176 returns
nullwhensessionIdVaris undefined. The nested source is therefore consulted only whensessionIdVaris defined but holds an unusable value. The TSDoc at Lines 52-55 states the nested source is consulted whensessionIdVaris unset, which is the opposite condition. Any future signal that declares onlynestedSessionIdsilently yields no session ID.Reorder the guard to read the flat variable when it exists, then fall back to the nested source.
🐛 Proposed fix
function readSessionId(signal: HarnessSignal): string | null { - if (signal.sessionIdVar === undefined) return null; - const value = - usableEnv(Bun.env[signal.sessionIdVar]) ?? readNestedSessionId(signal); + const flat = + signal.sessionIdVar === undefined + ? null + : usableEnv(Bun.env[signal.sessionIdVar]); + const value = flat ?? readNestedSessionId(signal); if (value === null) return null;🤖 Prompt for 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. In `@src/helpers/harness-detect.ts` around lines 175 - 184, Update readSessionId so it does not return early when signal.sessionIdVar is undefined; instead, read the flat environment value only when that variable exists, then fall back to readNestedSessionId for unset or unusable flat values. Align the related TSDoc to state that the nested source is consulted when sessionIdVar is unset or unusable, preserving UUID validation afterward.
🤖 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 `@docs/src/content/docs/nb/reference/cli/session-context.mdx`:
- Line 81: Update the Antigravity documentation sentence containing “En samtale
kalleren kjører inne i” by adding the missing relative marker “som”, while
leaving the surrounding Norwegian wording unchanged.
In `@src/helpers/session-context-antigravity.ts`:
- Around line 280-288: Update the missing-conversations errors in the
surrounding session-context flow, including the occurrence near line 316, to
report the joined list returned by antigravityDataDirs() instead of
antigravityCliDir(). Keep the existing error behavior and path field structure
unchanged.
- Around line 252-258: Update the conversation scan around workspaceFor so the
summaries database is opened once per session-context listing rather than once
per conversation. Reuse a single database handle or preload and reuse all
summary rows while resolving workspace matches, preserving the existing
filtering and transcript-path behavior.
In `@tests/helpers/session-context-codex.test.ts`:
- Around line 123-124: Rewrite the comment near the session transcript parsing
logic to describe that the CLI and desktop app currently emit different event
shapes, without mentioning the previous reader, empty transcripts, or historical
defects.
---
Outside diff comments:
In `@src/helpers/harness-detect.ts`:
- Around line 175-184: Update readSessionId so it does not return early when
signal.sessionIdVar is undefined; instead, read the flat environment value only
when that variable exists, then fall back to readNestedSessionId for unset or
unusable flat values. Align the related TSDoc to state that the nested source is
consulted when sessionIdVar is unset or unusable, preserving UUID validation
afterward.
🪄 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: 99d8b526-265c-4cf7-b24a-f85b73eaeef8
📒 Files selected for processing (13)
docs/public/llms-full.txtdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdxdocs/src/content/docs/reference/cli/session-context.mdxsrc/helpers/harness-detect.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/session-context-codex.tssrc/helpers/session-context-pi.tstests/helpers/session-context-antigravity.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-codex.test.tstests/helpers/session-context-pi.test.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Smoke Test (Windows) / Windows
🧰 Additional context used
📓 Path-based instructions (21)
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/public/llms-full.txtdocs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
**
⚙️ 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:
docs/public/llms-full.txttests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tsdocs/src/content/docs/reference/cli/session-context.mdxtests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tsdocs/src/content/docs/nb/reference/cli/session-context.mdxsrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tsdocs/src/content/docs/pt-br/reference/cli/session-context.mdxsrc/helpers/session-context-codex.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.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.Use TypeScript strict mode with ESNext and ES modules.
Files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
**/*.{js,ts,tsx,mjs,cjs}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-003-tool-invocation-via-scripts.md)
Invoke linting, formatting, and validation through package scripts (
bun run lint,bun run format,bun run format:check, andbun run validate), rather than directly invoking tool binaries such asbunx prettier,bunx oxfmt,npx eslint, oroxlint.
Files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
tests/**/*.test.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-025-idiomatic-bun-test-parametrization-and-matchers.md)
tests/**/*.test.ts: Usetest.each()ordescribe.each()for the same assertion logic against multiple independent inputs. Do not register tests or callexpect()once per case inside aforor.forEachloop.
Use array rows for positional destructuring and object rows for named fields when passing cases totest.each()ordescribe.each(). Choose descriptive title placeholders such as%s,%p,%d, or$field.
Assert derived facts with the most specific matcher available instead of passing a derived boolean to.toBe(true)or.toBe(false). Compare values directly with.toBe()or.toEqual().
Use specific matchers for common derived checks:.toContain()or.toMatch()for containment,.toBeInstanceOf()for type checks such asArray.isArray,.toHaveLength()for counts, and.find()with.toBeDefined()or.toBeUndefined()for predicate existence checks.
Do not precompute a boolean solely to assert it; assert the underlying values directly with matchers such as.toEqual()or.toBe().
When converting a loop totest.each()ordescribe.each(), preserve every assertion that ran per iteration; do not drop or merge assertions.
tests/**/*.test.ts: Every runnable test must contain anexpect()assertion; usetest.skiportest.todofor placeholders rather than assertion-less or silently skipped tests.
Test public interfaces with descriptive names rather than private implementation details.
Do not usemock.module()for first-party modules. Mock them withimport * as modplusspyOn(mod, "fn"), and restore mocks after each test.mock.module()may be used for approved external modules such asinquirerornode:readline.
For HTTP mocking, saveglobalThis.fetchbefore direct assignment and restore it inafterEach; do not usemock.module("node:fetch"), which does not intercept Bun's global fetch.
Wrap inlinespyOnormockImplementationlifecycles intry/finally, or manage them in hooks, somockRestore()runs wh...
Files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.ts
tests/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)
tests/**/*.ts: Use Bun's built-inbun:testrunner for all tests; do not importnode:test. Test files belong undertests/, mirrorsrc/, usetests/fixtures/for shared fixtures, and follow<module-name>.test.tsnaming.
Filesystem tests must use isolatedmkdtempdirectories and clean them up inafterEachorafterAll; do not touch real user-scope paths or leave temporary files behind.
Close external SDK instances, servers, clients, and transports in test hooks, such asawait server.close()inafterEachorafterAll.
Restore every captured environment variable withrestoreEnv(key, original); never restore with direct assignment such asBun.env.X = original, becauseundefinedbecomes the string"undefined".
Mockos.homedir()via an imported module namespace andspyOn; do not rely on overridingHOMEfor code usingos.homedir(), and keep filesystem writes inside temporary directories.
Shared test helpers, including non-test files undertests/, must restore every captured environment variable withrestoreEnv; isolation responsibilities apply across the entire shared Bun test process.Use
_resetAllCaches()fromsrc/helpers/platform.tsto simulate different platforms in tests rather than mockingprocess.platformdirectly.Tests mirror the
src/layout, with fixtures stored undertests/fixtures/.
Files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.ts
src/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-018-lazy-load-heavy-dependencies.md)
src/**/*.ts: Heavy runtime dependencies such asinquirer,posthog-node, and@sentry/*must be loaded with dynamicimport()at their point of use, never through top-level static value imports.
Type-only imports for heavy dependencies are allowed, but runtime values must be obtained through dynamicimport(); for example, useimport type { PostHog } from "posthog-node".
SDKs that require early initialization may use eager-start/lazy-await: begin initialization before command registration and await the result at first use, such as in apreActionhook.
src/**/*.ts: Everyinquirer.prompt(...)call must be wrapped inwithPromptFix(() => ...)imported fromsrc/helpers/prompt.ts; keep the wrapper adjacent to the prompt invocation so automated checks can detect it.
Do not callinquirer.prompt(...)directly or reimplement cursor/newline fixes at individual call sites; route all prompt behavior throughwithPromptFix().Every call to
Bun.Glob#scan()(glob.scan(...)) in source must pass{ dot: true }in its options object, including scans whose patterns do not explicitly target dot-directories. Do not usedot: false; intentionally excluded dotfiles must be filtered explicitly after scanning with a comment. Normalize scanned path separators withfile.replaceAll("\\", "/")when performing cross-platform path comparisons.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all colored CLI output; do not use raw ANSI escape codes or third-party color libraries such as chalk, kleur, or picocolors.
Commands producing structured results must support machine-readable output through--json, orcheck's canonical--output <format>selector.
UseformatJSON()fromsrc/helpers/output.tsfor command JSON serialization; passforcePretty: trueor its equivalent when pretty JSON is explicitly requested.
UseisAgentContext()for automatic JSON selection; only JSON may auto-upgrade in agent context, whilegithubandsarifremai...
Files:
src/helpers/session-context-pi.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
src/**/!(platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
All platform detection in
src/must go throughsrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(), orgetPlatformInfo()); directprocess.platformaccess and duplicated detection logic are forbidden outsideplatform.ts.
Files:
src/helpers/session-context-pi.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/**/*.{ts,tsx}: All opencode-gated behavior must useisOpencodeAvailable(), notisOpencodeCliAvailable()alone.
When adding an editor, update theEditorTargetunion, labels, settings configuration, optional authenticated installation branch, detection aggregation, command choices and handlers, URL handling, and related tests.
Files:
src/helpers/session-context-pi.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
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/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.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: Keep English content at the root and mirror every English MDX file in each locale directory (pt-brandnb) with the same relative path and filename; do not create orphan translations.
When English documentation is added or modified, update the corresponding locale files in the same pull request.
Translate user-facing prose, titles, descriptions, headings, list items, table text, admonitions, and Starlight component text props; keep code blocks, CLI commands, file paths, identifiers, technical terms, imports, component names, and link/href/slug values in English.
Preserve MDX curly-brace escaping, component imports, structural MDX elements, and internal link paths; internal links must not include locale prefixes.
Do not use machine translation without human review for technical accuracy.
Files:
docs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
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 top-level CLI command must have exactly one corresponding English reference page atdocs/src/content/docs/reference/cli/<name>.mdx; every page exceptindex.mdxmust correspond to a command.
Document subcommands inline in their parent command page; do not create separate top-level pages such asadr-create.mdxorlogin-status.mdx.
Command reference pages should follow the established MDX structure:titleanddescriptionfrontmatter, a one-line introduction, applicable subcommand and options tables, examples, and troubleshooting guidance where relevant.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-021-authored-text-integrity.md)
Markdown and MDX text content MUST NOT contain a backslash-escaped backtick. Use a longer code-span delimiter or restructure the sentence instead. The rule excludes YAML frontmatter, fenced code blocks, and
CHANGELOG.md.
Files:
docs/src/content/docs/reference/cli/session-context.mdxdocs/src/content/docs/nb/reference/cli/session-context.mdxdocs/src/content/docs/pt-br/reference/cli/session-context.mdx
docs/src/content/docs/reference/cli/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-016-cli-subcommand-documentation-accuracy.md)
docs/src/content/docs/reference/cli/**/*.mdx: CLI subcommand headings must contain the full command path, such asarchgate adr domain add, case-insensitively; headings representing module-backed subcommands must correspond to actual command modules.
Do not create separate.mdxfiles for subcommands; document subcommands within the top-level parent command's reference page.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
src/helpers/paths.ts
📄 CodeRabbit inference engine (CLAUDE.md)
For user-scope editors, mirror the editor's actual path resolution; opencode uses
xdg-basedirand falls back to~/.configon all platforms, including Windows.
Files:
src/helpers/paths.ts
docs/src/content/docs/nb/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Norwegian translations must use Bokmål rather than Nynorsk, use informal
du, and preserve correct characters such asæ,ø, andå.
Files:
docs/src/content/docs/nb/reference/cli/session-context.mdx
src/helpers/harness-detect.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/helpers/harness-detect.ts: Harness detection must identify the editor running the process using only variables injected into subprocesses; never use config-directory or PATH probes.
When adding an editor, updateDetectedHarnessand theSIGNALStable, and update session-contextlistFor/readForswitches and editor choices.
Files:
src/helpers/harness-detect.ts
docs/src/content/docs/pt-br/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Create a matching pt-br mirror for each English CLI reference page; internationalization parity is enforced separately by GEN-002.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
docs/src/content/docs/pt-br/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Brazilian Portuguese translations must use correct diacritical marks, including characters such as
ã,ç,é,í,ó,ú,â,ê,ô, andà.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T10:42:49.651Z
Learning: Update the `commands.md` skill references in the separate `archgate/plugins` repository whenever website CLI documentation changes; keep all four copies synchronized with the website.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T10:42:58.605Z
Learning: `bun run validate` must pass before any task is considered complete; it runs lint, typecheck, format check, tests, ADR checks, dead-export detection, and the build check.
Learnt from: CR
Repo: archgate/cli
Timestamp: 2026-08-08T10:42:58.605Z
Learning: Read relevant ADRs and companion `.rules.ts` files before making architectural changes; governance belongs in ADRs, executable rules, tests, or diagnostics rather than agent memory when enforceable.
📚 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/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.ts
📚 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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
📚 Learning: 2026-08-04T19:58:05.877Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 543
File: src/helpers/copilot-user-settings.ts:0-0
Timestamp: 2026-08-04T19:58:05.877Z
Learning: In archgate/cli TypeScript code, use `Bun.file(path).exists()` only to check whether a file exists; it must not be used for directory existence checks. For helpers such as `isCopilotAvailable()` that need to detect a configuration directory, use an appropriate directory-aware check such as `existsSync` from `node:fs`.
Applied to files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
📚 Learning: 2026-08-05T06:56:33.435Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 546
File: tests/integration/stream-guards.test.ts:3-9
Timestamp: 2026-08-05T06:56:33.435Z
Learning: When reviewing GEN-004 comment-block limits in the Archgate CLI repository, count only narrative prose lines within a block comment. Do not count a closing delimiter such as `*/` as a prose line; for example, in `tests/integration/stream-guards.test.ts`, Lines 4–8 contain five prose lines while Line 9 contains only the delimiter.
Applied to files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
📚 Learning: 2026-08-06T21:09:28.014Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 561
File: src/helpers/binary-upgrade.ts:239-287
Timestamp: 2026-08-06T21:09:28.014Z
Learning: In archgate/cli TypeScript code, follow ARCH-007 for Bun subprocess stream capture; ARCH-017 does not govern subprocess pipe handling. When Bun.spawn() uses piped stdout or stderr, use a shared capture helper where practical, consume configured streams concurrently to avoid deadlocks, and verify the subprocess exit code before trusting captured output.
Applied to files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.ts
📚 Learning: 2026-08-05T16:54:13.117Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/commands/adr/domain/remove.test.ts:21-24
Timestamp: 2026-08-05T16:54:13.117Z
Learning: In the Archgate CLI test suite, continue using `z.object` for JSON output schemas unless a repository-wide testing policy explicitly adopts `z.strictObject`. Do not introduce strict CLI-output schema enforcement as an isolated change in a coverage-focused pull request; require coordinated updates and policy agreement across affected tests.
Applied to files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tssrc/helpers/session-context-pi.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.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/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.ts
📚 Learning: 2026-08-05T16:54:50.574Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 550
File: tests/helpers/plugin-install-cursor-hooks.test.ts:44-44
Timestamp: 2026-08-05T16:54:50.574Z
Learning: In this repository, every TypeScript module under `src/` must have a matching `<module-name>.test.ts` file under the mirrored `tests/` directory, as required by ARCH-005. Supplemental behavior-suffixed sibling test files are allowed only when the matching parent test file exists. Use such siblings to keep individual test files below the 500-line oxlint limit.
Applied to files:
tests/helpers/session-context-codex.test.tstests/helpers/session-context-auto.test.tstests/helpers/session-context-pi.test.tstests/helpers/session-context-antigravity.test.ts
📚 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/session-context-pi.tssrc/helpers/paths.tssrc/helpers/session-context-antigravity.tssrc/helpers/harness-detect.tssrc/helpers/session-context-codex.ts
🪛 LanguageTool
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
[uncategorized] ~57-~57: Pontuação duplicada
Context: ...e ambiente que identificou o editor, ou --editor quando você informou um. `sessio...
(DOUBLE_PUNCTUATION_XML)
[uncategorized] ~57-~57: Encontrada possível ausência de vírgula.
Context: ...e executa dentro de outro agente. Nesse caso o vencedor vem de uma ordem fixa — Anti...
(AI_PT_HYDRA_LEO_MISSING_COMMA)
🪛 OpenGrep (1.26.0)
src/helpers/session-context-antigravity.ts
[ERROR] 161-161: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
[ERROR] 195-195: Dynamic command passed to child_process.exec/execSync. Use child_process.execFile or spawn with an argument array instead.
(coderabbit.command-injection.exec-js)
🔇 Additional comments (24)
docs/public/llms-full.txt (3)
1429-1429: LGTM!
1727-1734: LGTM!
4822-4931: 📐 Maintainability & Code QualityVerify the external plugin documentation copies.
This change updates the public
session-contextinterface. Verify that all fourcommands.mdcopies in the separatearchgate/pluginsrepository use the same unified syntax, includinglist,show <session-id>,--editor, and removal of positional editor subcommands.If a correction is needed here, update the source MDX and regenerate this generated artifact.
Based on learnings, website CLI documentation changes require the
commands.mdskill references in the separatearchgate/pluginsrepository to remain synchronized.Source: Learnings
docs/src/content/docs/nb/reference/cli/session-context.mdx (1)
26-34: LGTM!Also applies to: 57-57, 82-87
docs/src/content/docs/reference/cli/session-context.mdx (2)
26-34: LGTM!Also applies to: 57-57, 81-87
63-77: 📐 Maintainability & Code QualityVerify the plugin command references.
This CLI reference changes the
session-contextinterface. Verify that all fourcommands.mdskill references in the separatearchgate/pluginsrepository use the same unified command syntax and options.Based on learnings, update the
commands.mdskill references in the separatearchgate/pluginsrepository whenever website CLI documentation changes; keep all four copies synchronized.Source: Learnings
docs/src/content/docs/pt-br/reference/cli/session-context.mdx (1)
26-34: LGTM!Also applies to: 57-57, 81-87
src/helpers/harness-detect.ts (3)
75-83: LGTM!
119-148: LGTM!
150-157: LGTM!src/helpers/paths.ts (1)
111-125: LGTM!src/helpers/session-context-antigravity.ts (5)
18-25: LGTM!Also applies to: 85-128
130-168: LGTM!
170-212: LGTM!
214-229: LGTM!
341-382: LGTM!src/helpers/session-context-codex.ts (2)
59-98: LGTM!Also applies to: 376-385
46-57: No change needed
.loose()is still available for Zod object schemas in this repository.src/helpers/session-context-pi.ts (2)
36-48: LGTM!Also applies to: 50-74
278-298: LGTM!tests/helpers/session-context-auto.test.ts (1)
35-62: LGTM!Also applies to: 111-112, 307-307, 322-322
tests/helpers/session-context-antigravity.test.ts (1)
18-23: LGTM!Also applies to: 72-137, 139-217, 318-360
tests/helpers/session-context-codex.test.ts (1)
35-49: LGTM!Also applies to: 142-174
tests/helpers/session-context-pi.test.ts (1)
169-216: LGTM!
readSessionId returned early when a signal declared no flat sessionIdVar, so the nested source was reached only when a flat variable existed but held an unusable value — the opposite of what its own documentation stated. A signal declaring only nestedSessionId would have yielded no session id at all. Antigravity discovery also opened the shared summaries index once per unmatched conversation. It is now read once for the whole scan, so the cost stays flat as the history grows. The missing-store error named only the CLI directory while both trees are searched, pointing a desktop-app user at a path their distribution never writes to; it now names both. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Copilot records a tool-only assistant turn as an `assistant.message` with empty content and the calls in `toolRequests`, which surfaced as a blank transcript entry. A live session read 4 relevant entries where 2 held prose. Matches how the Pi and Antigravity readers already treat prose-less turns. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Two defect classes stay invisible to fixtures: a tool-only turn read as a blank entry, and a CLI/desktop pair that write one conversation in different event shapes. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Validate a nested session id through a schema constant rather than a hand-rolled typeof narrowing, matching the object walk beside it. Rename `archgateHomeDir` to `userHomeDir`: nine of its ten call sites resolve `.gemini`, `.codex`, `.pi`, `.cursor`, `.copilot`, `.config` or `.local/share`. Share one failure value for a session file that is discovered and then unreadable, and resolve mtime with `throwIfNoEntry: false` instead of exception control flow. Cover the reader error paths with hostile fixtures: a corrupt zstd frame, a directory standing in for a file or a database, and a SQLite file missing the table it is queried for. Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
1 participant
What changed
archgate session-contextnow detects which AI editor is running it, from the environment variables that editor injects into the processes it spawns. The four per-editor subcommands are replaced by an--editorflag.Why
The caller is an AI agent running inside one of these editors, but it had to be told which one by a skill or prompt — and a wrong answer silently read a different editor's transcript.
There is a second payoff. Every reader picked "the current conversation" by recency, which the docs already warned about for opencode: "recency selection picks the most recently updated one — which may not be the conversation you are part of." Three of the four editors publish their own session id, which replaces that guess with an exact match.
Detection
Every signal is verified against a citable source or against real on-disk state — none is assumed.
CLAUDECODECLAUDE_CODE_SESSION_IDCOPILOT_CLICOPILOT_AGENT_SESSION_IDgithub/copilot-clichangelog: v0.0.421 setsCOPILOT_CLI=1for subprocesses; v1.0.29 delivers the session id to "shell commands and MCP servers"CURSOR_AGENTCURSOR_CONVERSATION_IDgetSafeConversationIdisencodeURIComponent→%→_→ truncate 200, i.e. the identity function for a UUIDOPENCODE,OPENCODE_CLIENTpackages/opencode/src/index.tsL75-77;OPENCODE_PIDis a process id and nothing on disk is keyed by itReviewer notes
Probe before pinning. Every reader hard-fails on an unknown
sessionIdrather than falling back, and Copilot and opencode scope by project before the id lookup. A published id is therefore checked against the project-scoped session list first and only passed on an exact match — so a stale or unrelated id degrades to recency instead of turning a working command into an error.Empty string is not "absent". All four readers treat
sessionId: ""exactly likeundefinedand silently fall back to recency. Ids are read throughusableEnv, so an unset variable stays distinguishable from a rejected one.A session id only pins the editor that published it.
--editor cursorfrom inside Claude Code reads Cursor by recency and ignoresCLAUDE_CODE_SESSION_ID.Precedence when several markers are present (an agent inside another agent): editors publishing a session id outrank the one that does not, then
claude-code>copilot>cursor. Every match is reported incandidates, so a wrong pick is visible rather than silent.--rootis now rejected for editors other than opencode instead of being silently ignored.Also fixed here
encodeProjectPath(root, "cursor")mapped each separator to a dash without collapsing runs, while Cursor's own slugify collapses and trims. Any path with a dot-segment resolved to a directory that does not exist:That covered every git worktree under
.claude/worktrees/, where reading Cursor transcripts reported "No Cursor agent-transcripts directory found". The cursor branch now mirrors Cursor's slugify; the default branch is unchanged because Claude Code genuinely preserves repeated separators. Both are verified against real directories under~/.cursor/projects/and~/.claude/projects/.Three test fixtures reproduced the encoding by hand; all now derive it from
encodeProjectPath, so neither branch can drift from its fixtures again.Governance
usableEnv()before using them as a lookup key; never default to""when the consumer distinguishes absent from supplied. The existing "no wrapper functions" Don't is clarified sousableEnvdoes not read as contradicting it.Verification
bun run validategreen — 2378 tests, ADR check 51/51 with zero warnings and zero advisories.Fire-tested in both directions: pinning on a live session, stale and empty ids degrading to recency, precedence with multiple markers, the
--rootguard, an invalid--editor, and exit 1 with actionable guidance from a plain shell.Docs updated in all three locales (en, pt-br, nb) with exact structural parity.
Follow-up required before release
The
archgate/pluginsrepo still instructs agents to runarchgate session-context claude-codein fiveSKILL.mdcopies. That sync needs to land near this release or those instructions will error. Being handled separately.BREAKING CHANGE
archgate session-context <editor> [list|show]→archgate session-context [list|show] --editor <editor>, or omit--editorto use the detected one.