feat(session-context)!: per-editor list/show subcommands; remove --skip and its false premise#446
Conversation
…and docs The --skip help text on claude-code/cursor/copilot claimed the flag is "useful when running as a sub-agent" — built on the false premise that skills/sub-agents create their own project session. Verified on real data for Claude Code: skills run inline (the current conversation IS the most recent session file, so --skip 1 reads an unrelated previous conversation), and Agent-tool sub-agents do not write session files into ~/.claude/projects/ at all. The plain command (skip 0) is correct in every agent context. - Reword the --skip option help on claude-code, cursor, and copilot - Rewrite the shared ReadSessionOptions.skip JSDoc - Fix the docs option rows and replace the "read the parent session" example with an accurate one (en/nb/pt-br), regenerate llms-full.txt - Update the session-context agent memory: claude-code/cursor/copilot guidance resolved; document the concurrent-conversations caveat Companion: the distributed lessons-learned skill's canonical source drops --skip 1 in favor of the plain command. Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj 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: |
19d7e0e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://59c20c7e.archgate-cli.pages.dev |
| Branch Preview URL: | https://fix-session-context-skip-hel.archgate-cli.pages.dev |
|
Warning Review limit reached
Next review available in: 43 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (11)
📝 WalkthroughWalkthroughThis PR restructures the Changes
Sequence Diagram(s)sequenceDiagram
participant CLI
participant listFunction
participant readFunction
participant sessionFile/DB
CLI->>listFunction: archgate session-context claude-code list
listFunction->>sessionFile/DB: enumerate project sessions
listFunction-->>CLI: JSON {sessions: [{id, updatedAt}, ...]}
CLI->>readFunction: archgate session-context claude-code show SESSION_ID
readFunction->>sessionFile/DB: query for session SESSION_ID
readFunction-->>CLI: JSON {transcript, ...}
CLI->>readFunction: archgate session-context opencode show CHILD_ID --root
readFunction->>sessionFile/DB: resolve parent_id chain to root
readFunction-->>CLI: JSON {rootId, transcript, ...}
Estimated code review effort: High Related issues: None referenced Related PRs: None referenced Suggested labels: enhancement, documentation Suggested reviewers: None specified Poem:
🚥 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 |
Code Coverage
Full HTML report available in workflow artifacts. Per-directory breakdown
|
Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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`:
- Around line 4356-4359: The bundled docs artifact is out of date; regenerate
the checked-in llms-full bundle from the source docs. Re-run bun run
docs/scripts/generate-llms-full.ts and commit the updated output in
docs/public/llms-full.txt so the generated content stays in sync. Use the
llms-full generator script as the source of truth rather than editing the
bundled file manually.
🪄 Autofix (Beta)
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: b9bd9708-929b-40ed-9321-b74507854371
📒 Files selected for processing (10)
.claude/agent-memory/archgate-developer/MEMORY.md.claude/agent-memory/archgate-developer/project_session_context_skip_root_fix.mddocs/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/commands/session-context/claude-code.tssrc/commands/session-context/copilot.tssrc/commands/session-context/cursor.tssrc/helpers/session-context.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Cloudflare Pages
⚠️ CI failures not shown inline (12)
GitHub Actions: DCO / 0_DCO Sign-off Check.txt: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run base="29b13f49fce76a5f7afdc9d6c5264ebe4e3c120c"
�[36;1mbase="29b13f49fce76a5f7afdc9d6c5264ebe4e3c120c"�[0m
�[36;1mhead="7b87dbc5ce9856195bb8a56381f3c3f9977de4c7"�[0m
�[36;1mfailed=0�[0m
�[36;1m�[0m
�[36;1mfor sha in $(git rev-list --no-merges "$base".."$head"); do�[0m
�[36;1m if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then�[0m
�[36;1m echo "::error::Commit $sha is missing a DCO Signed-off-by line."�[0m
GitHub Actions: DCO / DCO Sign-off Check: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run base="29b13f49fce76a5f7afdc9d6c5264ebe4e3c120c"
�[36;1mbase="29b13f49fce76a5f7afdc9d6c5264ebe4e3c120c"�[0m
�[36;1mhead="7b87dbc5ce9856195bb8a56381f3c3f9977de4c7"�[0m
�[36;1mfailed=0�[0m
�[36;1m�[0m
�[36;1mfor sha in $(git rev-list --no-merges "$base".."$head"); do�[0m
�[36;1m if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then�[0m
�[36;1m echo "::error::Commit $sha is missing a DCO Signed-off-by line."�[0m
GitHub Actions: Validate / Coverage Report: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run COVERAGE="90.0"
�[36;1mCOVERAGE="90.0"�[0m
�[36;1mMIN_COVERAGE=90�[0m
�[36;1mBELOW=$(awk "BEGIN{print ($COVERAGE < $MIN_COVERAGE) ? 1 : 0}")�[0m
�[36;1mif [ "$BELOW" = "1" ]; then�[0m
�[36;1m echo "::error::Code coverage is ${COVERAGE}%, which is below the minimum threshold of ${MIN_COVERAGE}%."�[0m
GitHub Actions: Validate / 0_Validate Code.txt: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run # shim-tests is skipped when no shim files changed — treat skipped as success.
�[36;1m# shim-tests is skipped when no shim files changed — treat skipped as success.�[0m
�[36;1mSHIM_OK="skipped"�[0m
�[36;1mif [[ "$SHIM_OK" == "skipped" ]]; then SHIM_OK="success"; fi�[0m
�[36;1m�[0m
�[36;1mif [[ "success" != "success" ]] || \�[0m
�[36;1m [[ "$SHIM_OK" != "success" ]] || \�[0m
�[36;1m [[ "success" != "success" ]] || \�[0m
�[36;1m [[ "success" != "success" ]] || \�[0m
�[36;1m [[ "success" != "success" ]]; then�[0m
�[36;1m echo "::error::One or more jobs failed:"�[0m
GitHub Actions: Validate / Lint, Test & Check: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run bun run docs/scripts/generate-llms-full.ts
�[36;1mbun run docs/scripts/generate-llms-full.ts�[0m
�[36;1mgit diff --exit-code docs/public/llms-full.txt || {�[0m
�[36;1m echo "::error::docs/public/llms-full.txt is out of date. Run 'bun run docs/scripts/generate-llms-full.ts' and commit the result."�[0m
GitHub Actions: Validate / Smoke Test (Linux) _ Linux: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run if [ -z "$ARCHGATE_VERSION" ]; then
�[36;1mif [ -z "$ARCHGATE_VERSION" ]; then�[0m
�[36;1m # Find the newest release that already has the Linux asset uploaded.�[0m
�[36;1m # On release-commit pushes the Validate and Release workflows start�[0m
�[36;1m # concurrently, so the latest tag may exist before its binaries are�[0m
�[36;1m # uploaded by release-binaries.yml — hitting a 404.�[0m
�[36;1m asset="archgate-linux-x64.tar.gz"�[0m
�[36;1m tags="$(gh release list --limit 5 --json tagName --jq '.[].tagName' 2>/dev/null || true)"�[0m
�[36;1m if [ -z "$tags" ]; then�[0m
�[36;1m echo "::warning::No releases found, skipping install.sh smoke test"�[0m
�[36;1m exit 0�[0m
�[36;1m fi�[0m
�[36;1m found=""�[0m
�[36;1m for tag in $tags; do�[0m
�[36;1m assets="$(gh release view "$tag" --json assets --jq '.assets[].name' 2>/dev/null || true)"�[0m
�[36;1m if echo "$assets" | grep -qF "$asset"; then�[0m
�[36;1m ARCHGATE_VERSION="$tag"�[0m
�[36;1m found=1�[0m
�[36;1m break�[0m
�[36;1m fi�[0m
�[36;1m done�[0m
�[36;1m if [ -z "$found" ]; then�[0m
�[36;1m echo "::warning::No release with $asset found, skipping install.sh smoke test"�[0m
�[36;1m exit 0�[0m
�[36;1m fi�[0m
�[36;1m export ARCHGATE_VERSION�[0m
�[36;1mfi�[0m
�[36;1mecho "Testing install.sh with version $ARCHGATE_VERSION"�[0m
�[36;1m�[0m
�[36;1mexport ARCHGATE_INSTALL_DIR="$(mktemp -d)"�[0m
�[36;1m�[0m
�[36;1msh install.sh�[0m
�[36;1m�[0m
�[36;1mif [ ! -f "$ARCHGATE_INSTALL_DIR/archgate" ]; then�[0m
�[36;1m echo "::error::archgate binary not found at $ARCHGATE_INSTALL_DIR/archgate after install"�[0m
GitHub Actions: Validate / Validate Code: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run # shim-tests is skipped when no shim files changed — treat skipped as success.
�[36;1m# shim-tests is skipped when no shim files changed — treat skipped as success.�[0m
�[36;1mSHIM_OK="skipped"�[0m
�[36;1mif [[ "$SHIM_OK" == "skipped" ]]; then SHIM_OK="success"; fi�[0m
�[36;1m�[0m
�[36;1mif [[ "success" != "success" ]] || \�[0m
�[36;1m [[ "$SHIM_OK" != "success" ]] || \�[0m
�[36;1m [[ "success" != "success" ]] || \�[0m
�[36;1m [[ "success" != "success" ]] || \�[0m
�[36;1m [[ "success" != "success" ]]; then�[0m
�[36;1m echo "::error::One or more jobs failed:"�[0m
GitHub Actions: Validate / 1_Coverage Report.txt: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run COVERAGE="90.0"
�[36;1mCOVERAGE="90.0"�[0m
�[36;1mMIN_COVERAGE=90�[0m
�[36;1mBELOW=$(awk "BEGIN{print ($COVERAGE < $MIN_COVERAGE) ? 1 : 0}")�[0m
�[36;1mif [ "$BELOW" = "1" ]; then�[0m
�[36;1m echo "::error::Code coverage is ${COVERAGE}%, which is below the minimum threshold of ${MIN_COVERAGE}%."�[0m
GitHub Actions: Validate / 4_Lint, Test & Check.txt: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run bun run docs/scripts/generate-llms-full.ts
�[36;1mbun run docs/scripts/generate-llms-full.ts�[0m
�[36;1mgit diff --exit-code docs/public/llms-full.txt || {�[0m
�[36;1m echo "::error::docs/public/llms-full.txt is out of date. Run 'bun run docs/scripts/generate-llms-full.ts' and commit the result."�[0m
GitHub Actions: Validate / 5_Smoke Test (Linux) _ Linux.txt: fix(session-context): correct false sub-agent premise in --skip help and docs
Conclusion: failure
##[group]Run if [ -z "$ARCHGATE_VERSION" ]; then
�[36;1mif [ -z "$ARCHGATE_VERSION" ]; then�[0m
�[36;1m # Find the newest release that already has the Linux asset uploaded.�[0m
�[36;1m # On release-commit pushes the Validate and Release workflows start�[0m
�[36;1m # concurrently, so the latest tag may exist before its binaries are�[0m
�[36;1m # uploaded by release-binaries.yml — hitting a 404.�[0m
�[36;1m asset="archgate-linux-x64.tar.gz"�[0m
�[36;1m tags="$(gh release list --limit 5 --json tagName --jq '.[].tagName' 2>/dev/null || true)"�[0m
�[36;1m if [ -z "$tags" ]; then�[0m
�[36;1m echo "::warning::No releases found, skipping install.sh smoke test"�[0m
�[36;1m exit 0�[0m
�[36;1m fi�[0m
�[36;1m found=""�[0m
�[36;1m for tag in $tags; do�[0m
�[36;1m assets="$(gh release view "$tag" --json assets --jq '.assets[].name' 2>/dev/null || true)"�[0m
�[36;1m if echo "$assets" | grep -qF "$asset"; then�[0m
�[36;1m ARCHGATE_VERSION="$tag"�[0m
�[36;1m found=1�[0m
�[36;1m break�[0m
�[36;1m fi�[0m
�[36;1m done�[0m
�[36;1m if [ -z "$found" ]; then�[0m
�[36;1m echo "::warning::No release with $asset found, skipping install.sh smoke test"�[0m
�[36;1m exit 0�[0m
�[36;1m fi�[0m
�[36;1m export ARCHGATE_VERSION�[0m
�[36;1mfi�[0m
�[36;1mecho "Testing install.sh with version $ARCHGATE_VERSION"�[0m
�[36;1m�[0m
�[36;1mexport ARCHGATE_INSTALL_DIR="$(mktemp -d)"�[0m
�[36;1m�[0m
�[36;1msh install.sh�[0m
�[36;1m�[0m
�[36;1mif [ ! -f "$ARCHGATE_INSTALL_DIR/archgate" ]; then�[0m
�[36;1m echo "::error::archgate binary not found at $ARCHGATE_INSTALL_DIR/archgate after install"�[0m
GitHub Actions: Code Quality: PR #446 / Analyze (go): Code Quality: PR #446
Conclusion: failure
,"bundleSupportsIncludeLogs":true,"bundleSupportsOverlay":true,"databaseInterpretResultsSupportsSarifRunProperty":true,"featuresInVersionResult":true,"indirectTracingSupportsStaticBinaries":false,"informsAboutUnsupportedPathFilters":true,"supportsPython312":true,"mrvaPackCreate":true,"threatModelOption":true,"traceCommandUseBuildMode":true,"v2ramSizing":true,"mrvaPackCreateMultipleQueries":true,"setsCodeqlRunnerEnvVar":true,"sarifMergeRunsFromEqualCategory":true,"forceOverwrite":true,"generateSummarySymbolMap":true,"pythonDefaultIsToNotExtractStdlib":true,"queryServerRunQueries":true,"queryServerTrimCacheWithMode":true,"builtinExtractorsSpecifyDefaultQueries":true,"bqrsDiffResultSets":true,"bundleSupportsIncludeOption":true,"suppressesMissingFileBaselineWarning":true}}}
CODEQL_ACTION_GO_BINARY: /home/runner/work/_temp/codeql-action-go-tracing/bin/go
CODEQL_RAM: 14575
CODEQL_THREADS: 4
CODEQL_PROXY_HOST:
CODEQL_PROXY_PORT:
CODEQL_PROXY_CA_CERTIFICATE:
CODEQL_PROXY_URLS:
##[endgroup]
##[group]Attempting to automatically build go code
[command]/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/codeql database trace-command --use-build-mode --working-dir /home/runner/work/cli/cli /home/runner/work/_temp/codeql_databases/go
Picked up JAVA_TOOL_OPTIONS: -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false
Running command in /home/runner/work/cli/cli: [/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/go/tools/autobuild.sh]
[] [build-stderr] 2026/07/02 08:57:38 Autobuilder was built with go1.26.0, environment has go1.24.13
[] [build-stderr] 2026/07/02 08:57:38 LGTM_SRC is /home/runner/work/cli/cli
[] [build-stderr] 2026/07/02 08:57:38 Found no go.work files in the workspace; looking for go.mod files...
[] [build-stderr] 2026/07/02 08:57:38 Found 1 go.mod files in: shims/go/go.mod.
[] [build-stderr] 2026/07/02 08:57:38 Found 1 go.mod file(s).
[] [build-stderr] 2026/07/02 08:57:38 Import path is 'github.com/archgate/cli'
[] [build-stderr] 2026/07/...
GitHub Actions: Code Quality: PR #446 / 2_Analyze (go).txt: Code Quality: PR #446
Conclusion: failure
47 Extracting types for package crypto/aes.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/aes.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/des.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/des.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/des.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/internal/fips140/nistec/fiat.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/internal/fips140/nistec/fiat.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/internal/fips140/nistec/fiat.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/internal/fips140/nistec.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/internal/fips140/nistec.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/internal/fips140/nistec.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/internal/fips140/ecdh.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/internal/fips140/ecdh.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/internal/fips140/ecdh.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/internal/fips140/edwards25519/field.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/internal/fips140/edwards25519/field.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/internal/fips140/edwards25519/field.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/ecdh.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/ecdh.
[] [build-stderr] 2026/07/02 08:57:47 Done extracting types for package crypto/ecdh.
[] [build-stderr] 2026/07/02 08:57:47 Processing package crypto/elliptic.
[] [build-stderr] 2026/07/02 08:57:47 Extracting types for package crypto/elliptic.
[] [build...
🧰 Additional context used
📓 Path-based instructions (19)
src/commands/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
src/commands/**/*.ts: Commands must exportregister*Command(program)function that handles I/O only, with no business logic
UsestyleText()fromnode:utilfor output formatting; support--jsonflag for machine-readable output and auto-compact JSON in non-TTY/non-CI contexts
Exit with code 0 for success, 1 for violations, 2 for internal errors, and 130 for user cancellation (SIGINT)
src/commands/**/*.ts: Each command module undersrc/commands/must export aregister*Command(program)function, with one command per file (or one command group viaindex.ts).
Command files must be thin: they should only parse arguments, call engine/helpers, and format output; business logic must live insrc/engine/,src/helpers/, orsrc/formats/.
Command modules must not useexecutableDir()for command discovery, must not call.parse()themselves, and must not spawn child processes for subcommand execution.
Subcommand groups should live in nested directories with anindex.tsthat composes child commands (for example,src/commands/adr/index.ts).
src/commands/**/*.ts: In command files undersrc/commands/**/*.ts, options that need type narrowing beyond plain strings MUST usenew Option()with.addOption()instead of plain.option().
Insrc/commands/**/*.ts, importOptionfrom@commander-js/extra-typingsalongsideCommandso typed options get full type inference.
Insrc/commands/**/*.ts, enum-like options with a fixed set of allowed values must use.choices()on anOptionto provide runtime validation and compile-time type narrowing.
Insrc/commands/**/*.ts, options that require type conversion must use.argParser()on anOptionobject, not a parser function passed as the third argument to.option().
Insrc/commands/**/*.ts, register typed options with.addOption()rather than.option().
Insrc/commands/**/*.ts, pass both the choices array and default values withas constwhen using.choices()and.default()to pr...
Files:
src/commands/session-context/copilot.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Use TypeScript strict mode, ESNext target, and ES modules throughout
UsesafeParse()when validating with Zod schemas
Use minimal dependencies; prefer Bun built-ins per ARCH-006
Files:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.ts
**/*.{ts,tsx,json}
📄 CodeRabbit inference engine (CLAUDE.md)
Runtime must use Bun (>=1.2.21), not Node.js compatible
Files:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.ts
src/**/*.ts
📄 CodeRabbit inference engine (CLAUDE.md)
AI features must be delivered as a Claude Code plugin (
../plugins/claude-code), not via direct API calls
src/**/*.ts: UselogError()fromsrc/helpers/log.tsfor user-facing errors instead of printing errors directly.
Exit with code1for expected failures such as missing config, invalid input, or validation violations.
Let unexpected errors crash naturally so they are treated as internal errors with exit code2.
Include actionable suggestions in user-facing error messages whenever possible.
Write user-facing errors to stderr vialogError(); do not send them to stdout.
WhenfindProjectRoot()returnsnullfor commands that do not require.archgate/, fall back toprocess.cwd()as the path key or working directory.
CatchExitPromptErrorfrom Inquirer in the top-level error boundary and treat it as user cancellation: exit with code130without logging an error or sending it to Sentry.
Do not useconsole.error()directly; uselogError()for consistent formatting.
Do not exit with codes other than0,1,2, or130.
Do not send user-cancellation errors such as InquirerExitPromptErrorto Sentry; filter them inbeforeSend.
src/**/*.ts: UsestyleText(format, text)fromnode:utilfor all terminal colors and formatting in CLI source files; do not use raw ANSI escape codes or third-party color libraries.
Commands that produce structured results and support--jsonmust emit machine-readable JSON to stdout with no colors or decorative formatting.
When a command supports--json, useformatJSON()fromsrc/helpers/output.tsfor JSON serialization, and passforcePretty: truewhen the user explicitly provided--json.
UseisAgentContext()fromsrc/helpers/output.tsto enable auto-JSON behavior for commands that support both human-readable and JSON output modes.
CLI output must not include emoji; use text symbols and colors instead.
Send normal command output to stdout withconsole.log(), and send errors, warnings, and de...
Files:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.ts
**/*.{ts,tsx,js,jsx,mjs,cjs}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)
**/*.{ts,tsx,js,jsx,mjs,cjs}: Use Bun built-ins for file I/O (Bun.file,Bun.write), HTTP, subprocess execution (Bun.spawn), globbing (Bun.Glob), and testing (bun:test).
Do not use Node.js-specific APIs when Bun alternatives exist; for example, useBun.file()instead offs.readFile()for simple reads.
Prefernode:built-in modules such asnode:util,node:path, andnode:fsover npm alternatives.
Do not use utility libraries for single functions, such as importing lodash for one helper likepick.
Do not use path aliases (tsconfig paths); use relative imports with Bun's native module resolution.
Do not install packages globally during development; usebunxfor one-off tools.
Files:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.ts
src/**/!(*platform).ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)
src/**/!(*platform).ts: Insrc/TypeScript source files, do not readprocess.platformdirectly; usesrc/helpers/platform.ts(isWindows(),isMacOS(),isLinux(),isWSL(),getPlatformInfo()) for all platform detection.
Use the centralized platform helper instead of duplicating OS/WSL detection logic inline anywhere insrc/TypeScript source.
When behavior differs between Linux and Windows, account for WSL by usingisWSL()rather than assuming `
Files:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.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:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.ts
**
⚙️ CodeRabbit configuration file
**: # CLAUDE.mdArchgate is a CLI tool for AI governance via Architecture Decision Records (ADRs) — combining human-readable docs with machine-checkable rules. The CLI dogfoods itself via ADRs in
.archgate/adrs/. AI features are delivered as a Claude Code plugin (../plugins/claude-code), not via direct API calls.Technology Stack
- Runtime: Bun (>=1.2.21) — not Node.js compatible
- Language: TypeScript (strict mode, ESNext, ES modules)
- CLI framework: Commander.js (
@commander-js/extra-typings)- Linter: Oxlint | Formatter: Oxfmt | Dead exports: Knip | Commits: Conventional Commits
Commands
bun run src/cli.ts <command> # run CLI locally bun run lint # oxlint bun run typecheck # tsc --build bun run format # oxfmt --write bun run format:check # oxfmt --check bun run test # all tests (not bare `bun test` — picks up --timeout; see GEN-003) bun run knip # dead export detection bun run validate # MANDATORY: lint + typecheck + format + test + ADR check + knip + build check bun run build:check # verify build compiles (CI builds binaries via release workflow) bun run commit # conventional commit wizardValidation Gate
bun run validatemust pass before any task is considered complete. Fail-fast pipeline: lint → typecheck → format → test → ADR check → knip → build check. Mirrors CI in.github/workflows/code-pull-request.yml.Git Hooks (Git 2.54+)
Config-based hooks in
.githooksrun validation locally before commits and pushes:
- pre-commit: lint + typecheck + format:check (~15s)
- pre-push: full
bun run validate(~60s, mirrors CI)Activate once per clone:
git config --local include.path ../.githooksOpt out of a specific hook:
git config --local hook.<name>.enabled false. Skip all hooks for a single commit:git commit --no-verify.GitHub Act...
Files:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.tsdocs/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.mdxdocs/public/llms-full.txt
⚙️ 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:
src/commands/session-context/copilot.tssrc/helpers/session-context.tssrc/commands/session-context/claude-code.tssrc/commands/session-context/cursor.tsdocs/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.mdxdocs/public/llms-full.txt
src/{helpers,engine}/**/*.ts
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)
Do not use
console.log(),console.warn(), orconsole.info()directly in helper or engine files; uselogInfo()orlogWarn()instead. Command files are exempt because they are the I/O layer.
Files:
src/helpers/session-context.ts
docs/src/content/docs/reference/cli/!(index).mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Every top-level CLI command must have a corresponding reference page at
docs/src/content/docs/reference/cli/<name>.mdx, and every non-index.mdxpage in that directory must correspond to exactly one top-level command.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
docs/src/content/docs/reference/cli/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
Do not create separate reference pages for subcommands; subcommand documentation must stay inline within the parent command’s
.mdxpage.Every parent CLI reference page in
docs/src/content/docs/reference/cli/must contain headings for its direct subcommands using the exactarchgate <parent> <sub>format, and must not keep headings for subcommands that no longer exist.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
{src/commands/{*.ts,*/index.ts},docs/src/content/docs/reference/cli/!(index).mdx}
📄 CodeRabbit inference engine (.archgate/adrs/ARCH-015-cli-command-documentation-coverage.md)
{src/commands/{*.ts,*/index.ts},docs/src/content/docs/reference/cli/!(index).mdx}: When a top-level command is added, its docs page must be added in the same change; when a top-level command is removed, its matching docs page must be deleted in the same change.
Keep command and documentation stems aligned when renaming a top-level command file; renamingsrc/commands/<name>.tsorsrc/commands/<name>/index.tsmust be paired with renamingdocs/src/content/docs/reference/cli/<name>.mdx.
Files:
docs/src/content/docs/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 (.mdx) for all content pages underdocs/src/content/docs/.
Escape literal curly braces in MDX when showing template syntax; do not use bare{}in prose or code-fence labels.
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,docs/astro.config.mjs}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
When adding a new documentation page, create the MDX file in
docs/src/content/docs/<category>/<slug>.mdxand add the page todocs/astro.config.mjssidebar configuration.
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/**/*.mdx
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
Keep reference pages accurate to the CLI source code; when CLI APIs change, update the corresponding reference docs in the same PR.
Files:
docs/src/content/docs/reference/cli/session-context.mdx
docs/src/content/docs/**
📄 CodeRabbit inference engine (.archgate/adrs/GEN-001-documentation-site.md)
Do not create documentation content files outside
docs/src/content/docs/; Starlight content must live in that exact directory structure.
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,md}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
docs/src/content/docs/**/*.{mdx,md}: For every English docs page underdocs/src/content/docs/, create a translated file in each locale directory with the exact same relative path and filename, and ensure every locale file corresponds to an existing root file (no orphan translations).
When adding or modifying English documentation content, update the corresponding locale files in the same pull request.
Translate all user-facing prose in docs pages, including titles, descriptions, headings, paragraphs, list items, table text, and admonition content.
Translate user-visible text props in Starlight components such as<Card title="...">and<LinkCard description="...">.
Keep code blocks, CLI commands, file paths, TypeScript identifiers, technical terms, import statements, component names, andlink/href/slugattribute values in English.
Keep internal links unchanged and do not add locale prefixes (for example, use/guides/...rather than/pt-br/guides/...).
Preserve MDX curly-brace escaping (\{\}) in translated content.
Preserve Starlight component import statements identically in translated files.
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/nb/**/*.{mdx,md}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Use Norwegian Bokmål (not Nynorsk) for Norwegian translations, with the informal
duform and correct Norwegian characters (æ,ø,å).
Files:
docs/src/content/docs/nb/reference/cli/session-context.mdx
docs/src/content/docs/pt-br/**/*.{mdx,md}
📄 CodeRabbit inference engine (.archgate/adrs/GEN-002-docs-i18n.md)
Use correct Portuguese diacritical marks in Brazilian Portuguese translations; never write unaccented Portuguese.
Files:
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
🧠 Learnings (1)
📚 Learning: 2026-06-11T12:50:28.661Z
Learnt from: rhuanbarreto
Repo: archgate/cli PR: 406
File: .claude/agent-memory/archgate-developer/feedback_prefer_tests_over_adr_rules.md:8-18
Timestamp: 2026-06-11T12:50:28.661Z
Learning: In `archgate/cli`, for markdown files under `.claude/agent-memory/`, follow the established convention: use YAML frontmatter (with a `name:` field used as the document title) and do not require a top-level `#` (H1) heading. During code review, do not flag missing first-line/first-top-level H1 headings (e.g., MD041) for these agent-memory files since markdownlint is not part of the repo’s `bun run validate` lint pipeline (oxlint/oxfmt only).
Applied to files:
.claude/agent-memory/archgate-developer/MEMORY.md.claude/agent-memory/archgate-developer/project_session_context_skip_root_fix.md
🪛 GitHub Actions: Validate / 4_Lint, Test & Check.txt
docs/public/llms-full.txt
[error] 1-1: CI check failed: docs/public/llms-full.txt is out of date. Run 'bun run docs/scripts/generate-llms-full.ts' and commit the result.
🪛 GitHub Actions: Validate / Lint, Test & Check
docs/public/llms-full.txt
[error] 1-1: docs/public/llms-full.txt is out of date. Run 'bun run docs/scripts/generate-llms-full.ts' and commit the result.
🪛 LanguageTool
docs/src/content/docs/pt-br/reference/cli/session-context.mdx
[style] ~24-~24: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...----------------------------------- | | --max-entries <n> | Máximo de entradas a retornar (padr...
(INTERNET_ABBREVIATIONS)
[style] ~25-~25: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...r (padrão: 200) | | --skip <n> | Pular as N sessões mais rece...
(INTERNET_ABBREVIATIONS)
[style] ~37-~37: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...----------------------------------- | | --max-entries <n> | Máximo de entradas a retornar (padr...
(INTERNET_ABBREVIATIONS)
[style] ~38-~38: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...r (padrão: 200) | | --skip <n> | Pular as N sessões mais rece...
(INTERNET_ABBREVIATIONS)
[style] ~51-~51: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...----------------------------------- | | --max-entries <n> | Máximo de entradas a retornar (padr...
(INTERNET_ABBREVIATIONS)
[style] ~52-~52: Evite abreviações de internet. Considere escrever “não” por extenso. Se quis dizer “n”, coloque entre aspas.
Context: ...r (padrão: 200) | | --skip <n> | Pular as N sessões mais rece...
(INTERNET_ABBREVIATIONS)
🔇 Additional comments (9)
src/helpers/session-context.ts (1)
114-121: LGTM!src/commands/session-context/claude-code.ts (1)
19-19: LGTM!docs/src/content/docs/nb/reference/cli/session-context.mdx (1)
22-25: LGTM!Also applies to: 35-39, 49-53, 98-98
docs/src/content/docs/pt-br/reference/cli/session-context.mdx (1)
22-25: LGTM!Also applies to: 35-39, 49-53, 98-98
.claude/agent-memory/archgate-developer/MEMORY.md (1)
47-47: LGTM!src/commands/session-context/copilot.ts (1)
17-22: LGTM!src/commands/session-context/cursor.ts (1)
17-22: LGTM!docs/src/content/docs/reference/cli/session-context.mdx (1)
22-25: LGTM!Also applies to: 35-39, 49-53, 98-98
.claude/agent-memory/archgate-developer/project_session_context_skip_root_fix.md (1)
2-3: LGTM!Also applies to: 14-16
…erywhere The session-context command's purpose is reading the current conversation's context; --skip existed solely for the false "skip the sub-agent's own session" premise removed in the previous commit, and recency arithmetic can never reliably address a specific earlier conversation anyway. Replace positional guessing with explicit selection: - Remove --skip from claude-code, cursor, copilot, and opencode - Add --session-id to claude-code (previously the only subcommand without one; ids are the JSONL file basenames) - Add --list to all four subcommands: prints the project's sessions as JSON (id + updatedAt; opencode also includes title and lists top-level sessions only). --list conflicts with --session-id. - opencode: reader is called without await (it is synchronous) - Docs (en/nb/pt-br) tables and examples updated; llms-full.txt regenerated; agent memory updated with the final API decision BREAKING CHANGE: `archgate session-context <editor> --skip <n>` is no longer accepted. Use plain invocation for the current conversation, `--list` to discover earlier sessions, and `--session-id <id>` to read one. Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
rhuanbarreto
changed the title
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
…ow subcommands Listing and reading-a-specific-session are distinct operations from reading the current conversation — give each its own verb instead of mode flags on every editor subcommand: - `session-context list [--editor <e>]` — sessions as JSON; without --editor aggregates all four editors (absent stores fold their error into the aggregate instead of failing the command) - `session-context show <session-id> --editor <e> [--max-entries] [--root]` — read a specific session; positional id mirrors `adr show <id>`; --editor is required (UUIDs can collide across editor stores); --root is opencode-only, validated - Editor subcommands are now pure current-conversation readers with only --max-entries: --list and --session-id removed, and opencode's read loses --root (it was a no-op alias without a session id; its real semantics live in show) Tests: list/show behavior tests run the real CLI as a subprocess with HOME/USERPROFILE/XDG_DATA_HOME redirected — Bun's mock.module state is process-global across test files, and the sibling command tests' helper mocks leak into same-process imports (list.ts also no longer captures helper references in a module-level map, so live bindings are honored). Docs rewritten in en/nb/pt-br with the new subcommand sections (ARCH-016 headings) and examples; llms-full.txt regenerated; agent memory updated with the final API. BREAKING CHANGE: `--list` and `--session-id` are no longer accepted on the editor subcommands (both introduced earlier on this unreleased branch; `--session-id` previously shipped on copilot/cursor/opencode), and `--root` moved from `opencode` to `show`. Use `session-context list` and `session-context show <id> --editor <e>`. Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
rhuanbarreto
changed the title
Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Per review: the editor is already in the command path, so a top-level --editor flag was redundant. Each editor subcommand is now a command group: - `session-context <editor>` — read the current conversation (default action; --max-entries only) - `session-context <editor> list` — list that editor's sessions for the project (top-level only for opencode) - `session-context <editor> show <session-id> [--max-entries]` — read a specific session; `--root` exists only on `opencode show` The standalone `session-context list`/`show` subcommands (added earlier on this unreleased branch) are removed, along with the cross-editor aggregate and the --editor flag. Sub-subcommands are documented as #### blocks inside each editor's docs section (same pattern as `adr domain`), matching ARCH-016's one-level rule scope. BREAKING CHANGE: `session-context list --editor <e>` and `session-context show <id> --editor <e>` (both unreleased) are replaced by `session-context <editor> list` and `session-context <editor> show <session-id>`. Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
rhuanbarreto
changed the title
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
src/commands/session-context/copilot.ts (1)
21-90: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDuplicated error-handling/output boilerplate across base,
list, andshowactions.The try/catch →
result.okcheck →logError/exitWith(1)→formatJSONpattern is repeated identically three times. Consider extracting a small helper (e.g.runSessionAction(fn)) to reduce duplication and keep future changes (e.g., error formatting tweaks) in one place.♻️ Proposed refactor sketch
async function emitResult( result: { ok: true; data: unknown } | { ok: false; error: string } ) { if (!result.ok) { logError(result.error); await exitWith(1); return; } console.log(formatJSON(result.data)); }Each action body then reduces to:
- if (!result.ok) { - logError(result.error); - await exitWith(1); - return; - } - - console.log(formatJSON(result.data)); + await emitResult(result);🤖 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/commands/session-context/copilot.ts` around lines 21 - 90, The copilot session context commands repeat the same try/catch, result.ok check, logging, exit, and JSON output logic in the base command, list, and show handlers. Extract that shared flow into a small helper in or near registerCopilotSessionContextCommand, and have each action call it with the specific operation (readCopilotSession or listCopilotSessions) so error handling and output formatting stay centralized and easy to update.src/helpers/session-context.ts (1)
274-289: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winSort Cursor sessions by transcript mtime, not directory mtime.
Directory mtimes usually change when entries are created/removed, not when the nested JSONL transcript is appended. This can make the default read select an older session and make
listreport staleupdatedAtvalues. Statjoin(transcriptsDir, name, \${name}.jsonl`)` instead.🤖 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/session-context.ts` around lines 274 - 289, The session ordering in enumerateCursorSessionDirs currently uses the directory mtime, which can be stale for appended transcript updates. Update the logic to stat the nested transcript file at join(transcriptsDir, name, `${name}.jsonl`) and use that mtime for sorting, while keeping the existing directory/file existence handling and fallback behavior intact.tests/commands/session-context.test.ts (1)
64-75: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winAssert the exact option set.
These tests say "only --max-entries", but they would still pass if a new accidental option were added. Use an exact assertion for the base editor commands.
Proposed fix
- expect(opts).toContain("--max-entries"); - expect(opts).not.toContain("--session-id"); - expect(opts).not.toContain("--list"); - expect(opts).not.toContain("--skip"); + expect(opts).toEqual(["--max-entries"]);Also applies to: 78-89, 92-103, 145-157
🤖 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/commands/session-context.test.ts` around lines 64 - 75, The session-context command tests are only checking for presence/absence of a few options, so they would miss accidental extra flags. Update the affected assertions in registerSessionContextCommand-related tests (including the claude-code and base editor command cases) to verify the exact option list for each command rather than using partial contains/not-contains checks. Use the command objects from Command, parent.commands, and sub.options to compare the full set of option names against the expected set.src/helpers/session-context-copilot.ts (1)
71-84: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winUse
events.jsonlfor the recency sort.The current sort key uses the session directory mtime, which does not move when new events are appended. That can leave the active session below an older one; sort by
events.jsonlmtime instead.🤖 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/session-context-copilot.ts` around lines 71 - 84, The recency ordering in session-context-copilot currently sorts by each session directory’s mtime, which can stay stale when new events arrive. Update the sorting logic in the session directory scan to use the mtime of each session’s events.jsonl file instead, adjusting the readdirSync/statSync flow so the newest session is determined from that file’s timestamp rather than the directory timestamp.Sources: Coding guidelines, Path instructions
src/commands/session-context/claude-code.ts (1)
21-90: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsider extracting the repeated result-handling block.
The
if (!result.ok) { logError; exitWith(1); return; } console.log(formatJSON(result.data));pattern is duplicated across the base command,list, andshowactions. A small shared helper would reduce duplication and keep the three actions consistent as they evolve.async function emitResult(result: { ok: boolean; error?: string; data?: unknown }) { if (!result.ok) { logError(result.error ?? "Unknown error"); await exitWith(1); return; } console.log(formatJSON(result.data)); }🤖 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/commands/session-context/claude-code.ts` around lines 21 - 90, The result-handling logic is duplicated in the `registerClaudeCodeSessionContextCommand` actions for the base `claude-code`, `list`, and `show` commands. Extract the repeated `if (!result.ok) { logError(...); await exitWith(1); return; } console.log(formatJSON(result.data));` pattern into a shared helper near `registerClaudeCodeSessionContextCommand`, and have each action call it with the `readClaudeCodeSession` or `listClaudeCodeSessions` result so all three paths stay consistent.src/commands/session-context/cursor.ts (1)
21-91: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winExtract shared session-context helpers
makeMaxEntriesOption()and the!result.okhandling are duplicated acrossclaude-code.ts,copilot.ts,cursor.ts, andopencode.ts. Move them intosrc/commands/session-context/shared.tsso the four commands stay aligned as more editors are added.🤖 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/commands/session-context/cursor.ts` around lines 21 - 91, The cursor session-context command repeats shared option and error-handling logic that should be centralized with the other editor commands. Move the `makeMaxEntriesOption()` usage and the `!result.ok` branch pattern from `registerCursorSessionContextCommand` into `src/commands/session-context/shared.ts`, then reuse those helpers in `cursor.ts` alongside `claude-code.ts`, `copilot.ts`, and `opencode.ts` so all session-context commands stay consistent.
♻️ Duplicate comments (1)
docs/public/llms-full.txt (1)
4343-4494: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winRegenerate the bundled llms-full.txt — CI is still failing on it.
The pipeline logs report this file as out of sync with the source docs:
docs/public/llms-full.txt is out of date. Run 'bun run docs/scripts/generate-llms-full.ts' and commit the result.This is the same class of issue flagged in a prior review round (reportedly addressed in commits ce4ea47–9e9802d), but the check is failing again for this PR's changes to thesession-contextdocs — meaning the regeneration step wasn't re-run after thelist/showsubcommand rewrite landed.Run the generator and commit the output before merge; this blocks the
validate/CI gate.🔧 Fix
bun run docs/scripts/generate-llms-full.ts git add docs/public/llms-full.txt🤖 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 4343 - 4494, The bundled docs file is stale after the session-context docs rewrite, so regenerate the generated llms-full output from the source docs and commit the updated result. Use the docs generator tied to docs/public/llms-full.txt, then verify the changes include the revised archgate session-context claude-code/copilot/cursor/opencode sections and their list/show subcommands before merging.Source: Pipeline failures
🤖 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 `@src/commands/session-context/claude-code.ts`:
- Around line 15-19: The max-entries parser in makeMaxEntriesOption currently
turns non-numeric input into NaN, which later bypasses the default in
readClaudeCodeSession and disables trimming. Update the argParser for
"--max-entries <n>" to validate the parsed value and throw an
InvalidArgumentError on invalid input instead of returning NaN, so both the base
command and show fail fast on bad values.
In `@src/commands/session-context/copilot.ts`:
- Around line 15-19: `makeMaxEntriesOption()` is duplicated across the
session-context command files, so extract it into a shared helper and reuse it
everywhere. Move the option factory into a common module such as
`src/helpers/cli-options.ts`, then update `claude-code`, `cursor`, `copilot`,
and `opencode` to import and call the shared `makeMaxEntriesOption()` instead of
defining their own copies. Keep the existing `Option` setup and parser behavior
unchanged while centralizing the logic.
- Around line 15-19: The --max-entries option in makeMaxEntriesOption currently
coerces invalid input to NaN without feedback, so update the argParser to
validate the value before returning it. If the input is not a finite numeric
value or is negative/out of range, throw or surface a user-facing error with an
actionable message instead of passing NaN through to readCopilotSession and
downstream slicing logic. Keep the fix localized to makeMaxEntriesOption and the
session-context copilot command flow so invalid CLI input fails fast with a
clear validation message.
In `@src/commands/session-context/cursor.ts`:
- Around line 15-19: Reject non-numeric values for the max entries option in
makeMaxEntriesOption, since Math.trunc(Number(val)) can produce NaN and bypass
the default. Update the argParser to validate the input and throw
InvalidArgumentError when the provided value cannot be parsed as a number, so
cursor/session-context handling does not continue with an invalid max-entries
value.
In `@src/commands/session-context/opencode.ts`:
- Around line 15-19: The makeMaxEntriesOption() factory is duplicated across
multiple editor command files, so extract the shared option निर्माण into a
common helper module and reuse it from opencode.ts, claude-code.ts, copilot.ts,
and cursor.ts. Move the Option construction and argParser logic into a shared
symbol such as makeMaxEntriesOption in a helper like cli-options.ts, then update
each command to import and use that single implementation.
- Around line 15-19: The --max-entries parser in makeMaxEntriesOption currently
accepts invalid input because Math.trunc(Number(val)) can yield NaN, which then
bypasses truncation logic in readOpencodeSession(). Update the argParser in
makeMaxEntriesOption to validate the value, reject non-numeric or non-positive
inputs by throwing InvalidArgumentError, and only return a valid positive
integer so the session command fails fast on bad arguments.
In `@src/helpers/session-context-opencode.ts`:
- Around line 81-100: Remove the synchronous existsSync pre-check from
listOpencodeSessions and the same pattern in readOpencodeSession, since
Bun.file(dbPath).exists() is async and this helper should not add a Node fs
dependency. Let opencodeDbPath()/normalizePath flow into directly opening the
Database in readonly mode and rely on the existing catch path in
listOpencodeSessions/readOpencodeSession to report missing or unreadable
databases.
In `@src/helpers/session-context.ts`:
- Around line 67-75: `SessionListEntry` is missing the `title` field that
`listOpencodeSessions()` already emits, so update the shared session list
contract in `SessionListEntry` to include it and keep `SessionListResult`
aligned with the runtime payload. Make the change in the shared helper types
where `SessionListEntry` is defined so typed callers can rely on the full list
API shape from `listOpencodeSessions()` and any other list implementations.
- Around line 142-149: The session enumerators in enumerateClaudeSessionFiles
and the other scan helper still rely on node:fs readdirSync/statSync, which
violates ARCH-006. Update both scan paths to use Bun filesystem APIs instead,
keeping the same filtering/sorting behavior and preserving the existing return
shapes so callers of these helpers continue to work unchanged.
In `@tests/commands/session-context/claude-code.test.ts`:
- Around line 32-41: The session-context test is using mock.module() on a
first-party module that is imported unmocked elsewhere, which can leak
process-global mock state across tests. Update the claude-code test setup to use
spyOn against the existing readClaudeCodeSession and listClaudeCodeSessions
exports from session-context instead of mocking the whole module, or otherwise
isolate this as an explicitly accepted exception. Keep the focus on the test
helpers in claude-code.test.ts and the shared session-context module so the mock
behavior remains local to this test file.
In `@tests/commands/session-context/copilot.test.ts`:
- Around line 28-36: Replace the new `mock.module()` override for
`../../../src/helpers/session-context-copilot` with a `spyOn`-based mock so the
first-party module stays directly importable by other tests. Keep the existing
`readCopilotSession` and `listCopilotSessions` behavior in
`tests/commands/session-context/copilot.test.ts`, but apply it through spies
rather than module-level mocking to avoid affecting
`tests/helpers/session-context-copilot.test.ts` and similar files.
In `@tests/commands/session-context/cursor.test.ts`:
- Around line 28-36: Replace the `mock.module()` usage for `session-context`
with a `spyOn`-based mock setup in `cursor.test.ts`, since `readCursorSession`
and `listCursorSessions` come from a shared first-party module that other tests
import directly. Update the test to target the specific exported functions
instead of globally swapping `../../../src/helpers/session-context`, and keep
the mock behavior isolated to the `mockReadCursorSession` and
`mockListCursorSessions` cases used in this file.
In `@tests/helpers/session-context-cursor.test.ts`:
- Around line 207-273: Add a regression test in session-context-cursor.test.ts
to cover the readCursorSession error branch when a requested sessionId does not
exist. Use readCursorSession with an unknown sessionId and assert the result is
not ok, the error mentions the missing id, and the available sessions list is
included. Keep the existing happy-path tests for sessionId and default
selection, but add this negative case near test("sessionId reads an earlier
session; default reads the most recent").
---
Outside diff comments:
In `@src/commands/session-context/claude-code.ts`:
- Around line 21-90: The result-handling logic is duplicated in the
`registerClaudeCodeSessionContextCommand` actions for the base `claude-code`,
`list`, and `show` commands. Extract the repeated `if (!result.ok) {
logError(...); await exitWith(1); return; }
console.log(formatJSON(result.data));` pattern into a shared helper near
`registerClaudeCodeSessionContextCommand`, and have each action call it with the
`readClaudeCodeSession` or `listClaudeCodeSessions` result so all three paths
stay consistent.
In `@src/commands/session-context/copilot.ts`:
- Around line 21-90: The copilot session context commands repeat the same
try/catch, result.ok check, logging, exit, and JSON output logic in the base
command, list, and show handlers. Extract that shared flow into a small helper
in or near registerCopilotSessionContextCommand, and have each action call it
with the specific operation (readCopilotSession or listCopilotSessions) so error
handling and output formatting stay centralized and easy to update.
In `@src/commands/session-context/cursor.ts`:
- Around line 21-91: The cursor session-context command repeats shared option
and error-handling logic that should be centralized with the other editor
commands. Move the `makeMaxEntriesOption()` usage and the `!result.ok` branch
pattern from `registerCursorSessionContextCommand` into
`src/commands/session-context/shared.ts`, then reuse those helpers in
`cursor.ts` alongside `claude-code.ts`, `copilot.ts`, and `opencode.ts` so all
session-context commands stay consistent.
In `@src/helpers/session-context-copilot.ts`:
- Around line 71-84: The recency ordering in session-context-copilot currently
sorts by each session directory’s mtime, which can stay stale when new events
arrive. Update the sorting logic in the session directory scan to use the mtime
of each session’s events.jsonl file instead, adjusting the readdirSync/statSync
flow so the newest session is determined from that file’s timestamp rather than
the directory timestamp.
In `@src/helpers/session-context.ts`:
- Around line 274-289: The session ordering in enumerateCursorSessionDirs
currently uses the directory mtime, which can be stale for appended transcript
updates. Update the logic to stat the nested transcript file at
join(transcriptsDir, name, `${name}.jsonl`) and use that mtime for sorting,
while keeping the existing directory/file existence handling and fallback
behavior intact.
In `@tests/commands/session-context.test.ts`:
- Around line 64-75: The session-context command tests are only checking for
presence/absence of a few options, so they would miss accidental extra flags.
Update the affected assertions in registerSessionContextCommand-related tests
(including the claude-code and base editor command cases) to verify the exact
option list for each command rather than using partial contains/not-contains
checks. Use the command objects from Command, parent.commands, and sub.options
to compare the full set of option names against the expected set.
---
Duplicate comments:
In `@docs/public/llms-full.txt`:
- Around line 4343-4494: The bundled docs file is stale after the
session-context docs rewrite, so regenerate the generated llms-full output from
the source docs and commit the updated result. Use the docs generator tied to
docs/public/llms-full.txt, then verify the changes include the revised archgate
session-context claude-code/copilot/cursor/opencode sections and their list/show
subcommands before merging.
🪄 Autofix (Beta)
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: 1277c098-a106-4589-9d33-8a16356ae5df
📒 Files selected for processing (23)
.claude/agent-memory/archgate-developer/MEMORY.md.claude/agent-memory/archgate-developer/feedback_public_repo_privacy.md.claude/agent-memory/archgate-developer/project_session_context_skip_root_fix.mddocs/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/commands/session-context/claude-code.tssrc/commands/session-context/copilot.tssrc/commands/session-context/cursor.tssrc/commands/session-context/opencode.tssrc/helpers/session-context-copilot.tssrc/helpers/session-context-opencode.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/session-context-copilot.test.tstests/helpers/session-context-cursor.test.tstests/helpers/session-context-opencode.test.tstests/helpers/session-context.test.ts
- --max-entries now validates input: non-numeric or non-positive values are rejected with InvalidArgumentError instead of a NaN limit silently disabling transcript trimming (CodeRabbit) - Deduplicate the option factory: exported once from claude-code.ts (cross-command sharing convention) and imported by the other three editor commands (CodeRabbit) - SessionListEntry gains optional `title` so the shared list contract covers the field opencode actually emits (CodeRabbit) - Command tests converted from mock.module() to import * + spyOn per ARCH-005 — removes the process-global module-mock leakage the subprocess tests were working around (CodeRabbit) - Add sessionId-not-found error-path tests for the cursor and copilot helpers (CodeRabbit) Declined with reasoning on the PR: dropping the sync existsSync pre-check and replacing readdirSync/statSync enumeration — ARCH-006 prefers Bun APIs only where alternatives exist; Bun.file().exists() is async (helpers are sync) and Bun has no readdir/stat for directory enumeration. Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
|
Review feedback addressed in 9abed1d: Fixed
Declined (with reasoning)
|
The subprocess-based list/show tests exercise the real wiring but the child process is not instrumented, so the eight new child actions were invisible to coverage (CI dropped to 88.5%). Add in-process tests for every editor's list/show actions using the spyOn pattern (happy path + error path; opencode also covers --root pass-through). Local coverage back above threshold. Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
Claude-Session: https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
## Problem The session-context breaking changes (#446) made simple-release propose **v1.0.0** (release PR #440). We are not ready to publish 1.0.0 — the project still ships no support guarantees. Pre-1.0, breaking changes should produce a **minor** bump (0.46.0). ## Fix Override `getNextVersion` in `.simple-release.js`: when the current version is `0.x` and the conventional-commit computation yields a major bump, return the next minor instead. `bump()` derives its version from `getNextVersion`, so the manifest writes, changelog, release-PR title, and tag all stay consistent from the single cap. Explicit `version`/`as` bump options bypass the cap, so v1.0.0 remains available as a deliberate, forced decision. ## Verification Dry-run against the live git history (which contains the `feat!` commits): | | computed next version | |---|---| | stock `NpmProject` | `1.0.0` | | capped `ArchgateProject` | `0.46.0` | Lint, typecheck, format, and `archgate check` (39/39) green. ## After merge The push to `main` re-triggers the release `pull-request` workflow, which updates release PR #440 in place from 1.0.0 to 0.46.0 (title, changelog, version files, shim versions). **Do not merge #440 before this lands.** https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj Signed-off-by: Rhuan Barreto <rhuan@barreto.work>
# archgate ## [0.46.0](v0.45.7...v0.46.0) (2026-07-02) ### ⚠ BREAKING CHANGES * **session-context:** per-editor list/show subcommands; remove --skip and its false premise (#446) ### Features * **session-context:** per-editor list/show subcommands; remove --skip and its false premise ([#446](#446)) ([dd96230](dd96230)) ### Bug Fixes * **ci:** read POSTHOG_PROJECT_ID from secrets, not vars, in release annotation ([#443](#443)) ([a53b305](a53b305)) * detect opencode Desktop app installs, not just the CLI ([#439](#439)) ([ed92b2b](ed92b2b)) * **hooks:** force bash shell for WorktreeCreate hook on Windows ([#442](#442)) ([9da86cf](9da86cf)) * **release:** cap breaking-change bumps to minor while pre-1.0 ([#447](#447)) ([3df6c91](3df6c91)), closes [#446](#446) [#440](#440) [#440](#440) [#440](#440) * repair broken WorktreeCreate hook and add PR approval policy ([#441](#441)) ([de5e97d](de5e97d)) * **session-context:** select top-level opencode sessions, add --root flag ([#445](#445)) ([29b13f4](29b13f4)) --- This PR was generated with [simple-release](https://github.com/TrigenSoftware/simple-release). <details> <summary>📄 Cheatsheet</summary> <br> You can configure the bot's behavior through a pull request comment using the `!simple-release/set-options` command. ### Command Format ````md !simple-release/set-options ```json { "bump": {}, "publish": {} } ``` ```` ### Useful Parameters #### Bump | Parameter | Type | Description | |-----------|------|-------------| | `version` | `string` | Force set specific version | | `as` | `'major' \| 'minor' \| 'patch' \| 'prerelease'` | Release type | | `prerelease` | `string` | Pre-release identifier (e.g., "alpha", "beta") | | `firstRelease` | `boolean` | Whether this is the first release | | `skip` | `boolean` | Skip version bump | | `byProject` | `Record<string, object>` | Per-project bump options for monorepos | #### Publish | Parameter | Type | Description | |-----------|------|-------------| | `skip` | `boolean` | Skip publishing | | `access` | `'public' \| 'restricted'` | Package access level | | `tag` | `string` | Tag for npm publication | ### Usage Examples #### Force specific version ````md !simple-release/set-options ```json { "bump": { "version": "2.0.0" } } ``` ```` #### Force major bump ````md !simple-release/set-options ```json { "bump": { "as": "major" } } ``` ```` #### Create alpha pre-release ````md !simple-release/set-options ```json { "bump": { "prerelease": "alpha" } } ``` ```` #### Publish with specific access and tag ````md !simple-release/set-options ```json { "bump": { "prerelease": "beta" }, "publish": { "access": "public", "tag": "beta" } } ``` ```` ### Access Restrictions The command can only be used by users with permissions: - repository owner - organization member - collaborator ### Notes - The last comment with `!simple-release/set-options` command takes priority - JSON must be valid, otherwise the command will be ignored - Parameters apply only to the current release execution - The command can be updated by editing the comment or adding a new one </details> <!-- Please do not edit this comment. simple-release-pull-request: true simple-release-branch-from: release simple-release-branch-to: main --> Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 participant
Problem
Follow-up to #445. The
--skipflag on every session-context subcommand existed for one advertised purpose: "skip the sub-agent's own session to read the parent." Verified false on real data (skills run inline; Agent-tool sub-agents create no project session files; zeroisSidechainentries). With that premise dead, positional recency guessing had no remaining role — reading the current conversation needs no knobs, and addressing an earlier session should be explicit.New API (breaking)
Each editor subcommand is now a command group; the editor is the namespace, so no
--editorflag anywhere:session-context <editor> [--max-entries]session-context <editor> listid+updatedAt; opencode addstitle, lists top-level sessions only)session-context <editor> show <session-id> [--max-entries]--rootexists only onopencode show(child → top-level ancestor)Removed:
--skipeverywhere;--session-idflags;--rootfrom the opencode read. (Intermediate shapes iterated on this unreleased branch — per-editor--list/--session-idflags, then top-levellist/showsubcommands with--editor— are also gone.)Notes
####blocks inside each editor's docs section — same pattern asadr domain, matching ARCH-016's one-level rule scopemock.modulestate is process-global across test files, so in-process tests would race the sibling tests' helper mocks)bun run validategreen (1349 tests, 39/39 ADR checks); live smoke test:claude-code list,claude-code show <real-id>verified against real stores;session-context listand--session-idcorrectly rejectedllms-full.txtregenerated; agent memory updated with the final APIRelease sequencing
The distributed lessons-learned skill's escape-hatch text references
<editor> list/<editor> show— this CLI must release before the plugin change ships, and the plugin release should follow promptly (already-installed skills referencing--skip 1will hit their error-fallback path on the new CLI).https://claude.ai/code/session_01SGjSjrywTnZDcUqgHWGrTj