Release: develop into main (v2.0.0)

[Minitour]

Summary

Release PR promoting develop into main for CAPA v2.0. Bundles the full version-2.0 surface merged via #160, plus dependency bumps already on develop (#151, #152).

What changed

Wrap / CLI agents

• capa wrap shadow workspaces so installs never mutate the real project (Enhance CLI wrap functionality and streamline install options #141, feat: extend capa wrap to Cursor agent and other CLI providers #154, fix(wrap): never mutate the real project during shadow install #159)
• Cursor agent and other CLI providers; Windows .cmd shim resolution
• Provider noise rules, permission/cli.json sync, and safer exclusion detection (root skills/ no longer implies openclaw)

Web UI / capabilities

• Interactive capabilities editor with live YAML sync (feat(web-ui): interactive capabilities editor with live YAML sync #142)
• Local file pickers, Agents editor, project init/register/delete (feat: local skills/rules from file + Agents section #143–feat: register projects on init and delete from UI #145)
• Tools editor polish and reliable reorder (fix: polish tools editor UX for spaces, loading, and descriptions #149)
• Full plugin unpack: rules, sub-agents, hooks with UI lock parity (feat: unpack plugin rules, subagents, and hooks with UI lock parity #153)

Observability

• Live project tool-call activity traces (feat: add live project tool-call activity traces #148)
• Agent activity run dialog with timeline, usage stats, and fresh-span polish (feat: agent activity observability and wrap project isolation #155)

Auth / registries / install

• Headless git auth via access tokens (feat(auth): support headless git auth via access tokens #156)
• Claude marketplace registry support (feat: add Claude marketplace registry support #150)
• Hardened capability install destination allow-lists (Harden install path ids and polish activity run dialog #158)
• Expanded capa add kinds and --passthrough file-broker mode (feat: expand capa add kinds and add --passthrough mode #146)

Docs / MCP / hygiene

• README and shipped skills refreshed for the v2 package-manager + MCP gateway story (docs: refresh README and shipped skills for v2 #157)
• MCP server icons, metadata, and ping (feat(mcp): expose server icons, metadata, and ping support #138)
• Code cleanup / readability (Refactor large modules for readability #147); CodeQL and path-safety hardening from the v2 merge

Notable PRs since v1.9.18

#137–#160 (including #141 wrap, #142 capabilities editor, #148/#155 activity, #154 CLI agents, #156 auth tokens, #157 docs, #160 version-2.0 merge)

Test plan

• CI green on this PR (typecheck, tests, CodeQL)
• capa wrap agent on Windows resolves the Cursor CLI shim
• Wrap does not mutate the real project; shadow symlink exclusions behave for root skills/
• Web UI: edit capabilities YAML, reorder tools, open Activity run dialog
• capa install / plugin unpack / marketplace registry smoke
• Auth with access token for a self-hosted git skill source

Checklist

• Tests added or updated on develop
• Docs updated (README + skills)
• Ready to tag v2.0.0 after merge

366 files changed, ~49k insertions / ~17k deletions vs main.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Symlink statSync bypasses handler ✓ Resolved 🐞 Bug ☼ Reliability

Description

createWorkspaceSymlink() evaluates statSync(targetPath) before entering its try/catch, so filesystem
errors bypass symlinkErrorMessage() and can abort wrap workspace setup with an unwrapped exception.

Code

src/cli/utils/wrap/symlink-workspace.ts[R56-58]

+export function createWorkspaceSymlink(targetPath: string, linkPath: string): void {
+  const targetIsDir = existsSync(targetPath) && statSync(targetPath).isDirectory();
+  try {

Evidence

The function computes targetIsDir using statSync() before entering the try that wraps errors
with symlinkErrorMessage(), so any statSync() exception will bypass the intended error handling.

src/cli/utils/wrap/symlink-workspace.ts[52-75]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`createWorkspaceSymlink()` computes `targetIsDir` using `statSync()` before the function’s `try/catch`. If `statSync()` throws (race, permissions, transient FS error), the error bypasses the intended `symlinkErrorMessage()` wrapping, reducing debuggability and potentially crashing `capa wrap` workspace preparation.
## Issue Context
This function is used to build/sync the shadow workspace symlink tree; failures should produce the friendly, platform-specific guidance in `symlinkErrorMessage()`.
## Fix Focus Areas
- Ensure *all* filesystem probes that may throw (`statSync`) are inside the `try/catch` that wraps errors via `symlinkErrorMessage()`.
- Consider treating failures to determine dir-vs-file as a symlink attempt error that still gets the friendly message.
### Suggested approach
- Move `targetIsDir` computation into the `try` block.
- Alternatively, wrap the `statSync()` in its own `try/catch` and rethrow as `new Error(symlinkErrorMessage(err))`.
## Fix Focus Areas (code)
- src/cli/utils/wrap/symlink-workspace.ts[56-75]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. IPv6 loopback CORS denied ✓ Resolved 🐞 Bug ≡ Correctness

Description

isAllowedOrigin() only auto-allows http origins for localhost and 127.0.0.1, so http://[::1]:<port>
is rejected unless CAPA_ALLOWED_ORIGINS is set, breaking local UI on IPv6 loopback.

Code

src/server/cors-origin.ts[R10-14]

+		const parsed = new URL(origin);
+		if (
+			parsed.protocol === "http:" &&
+			(parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1")
+		) {

Evidence

The allowlist conditional explicitly checks only localhost and 127.0.0.1; IPv6 loopback (::1)
is not included, so those origins are denied unless explicitly configured.

src/server/cors-origin.ts[1-30]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The default CORS allow logic only recognizes `localhost` and `127.0.0.1` as loopback origins. Browsers/dev servers that use IPv6 loopback (`::1`) will be blocked by CORS unless users set `CAPA_ALLOWED_ORIGINS`, which can break local development and some local deployments.
## Issue Context
`Origin: http://[::1]:5173` parses to `parsed.hostname === "::1"` in `new URL(origin)`. This is currently not allowed.
## Fix Focus Areas
- Extend the loopback allow check to include IPv6 loopback hostname `::1`.
- (Optional) consider allowing `http://[::1]` variants automatically the same way as `127.0.0.1`.
- Add a small unit test for `http://[::1]:<port>`.
## Fix Focus Areas (code)
- src/server/cors-origin.ts[1-30]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. PAT host validation too strict ✓ Resolved 🐞 Bug ≡ Correctness

Description

authenticateWithAccessToken() rejects provider strings that are not DNS-style domains, which blocks
PAT auth for self-hosted Git endpoints addressed as localhost, IP literals, or host:port even when
--type github-enterprise/gitlab-self-managed is supplied.

Code

src/cli/commands/auth.ts[R243-246]

+  if (!isValidProvider(provider)) {
+    error(`Invalid provider: ${provider}`);
+    error('Provider must be a domain name (e.g., github.com, gitlab.com)');
+    db.close();

Evidence

The access-token path rejects non-domain inputs up-front, and the validator enforces a . pattern,
which excludes IP literals, localhost, and anything with :port.

src/cli/commands/auth.ts[228-249]
src/cli/commands/auth.ts[406-408]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PAT-based auth flow validates `provider` using a domain-only regex before it resolves `--type` for self-hosted instances. This prevents authenticating to enterprise/self-managed Git when the host is provided as `localhost`, an IP literal, or `host:port`.
## Issue Context
Self-hosted validation later composes URLs like `https://${host}/...`, which can support `host:port` if allowed, but the current validation rejects these inputs early.
## Fix Focus Areas
- Change validation to accept:
- DNS hostnames (existing behavior)
- `localhost`
- IPv4 / IPv6 literals (IPv6 may be bracketed in user input; normalize)
- optional `:port`
- Prefer parsing via `new URL('https://' + provider)` and then validating `url.hostname` via `net.isIP()` / hostname checks, rather than regex-only.
- Keep rejecting schemes (`https://`) in the CLI argument if that is desired, but do so explicitly and with a clear error.
## Fix Focus Areas (code)
- src/cli/commands/auth.ts[228-289]
- src/cli/commands/auth.ts[406-408]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Release v2.0.0: package-manager + MCP gateway (develop → main)

✨ Enhancement 🐞 Bug fix ⚙️ Configuration changes 📝 Documentation 🧪 Tests 🕐 40+ Minutes

AI Description

• Release PR merging develop into main for CAPA v2.0, bundling PRs #137–#160.
• Adds capa wrap shadow workspaces, expanded capa add (kinds + --passthrough), and headless
 git auth via access tokens.
• Ships major Web UI upgrades: capabilities editor, registry browse, tools/agents/plugins editors,
 and activity traces.
• Introduces server-side tool-call tracing (tool_calls + ToolCallTracer) and MCP server
 icons/metadata/ping.
• Refactors large modules into smaller submodules (providers registry, OAuth, hooks, sh, add,
 clean).

Diagram

graph TD
  CLI["capa CLI"] --> WRAP["wrap: shadow workspace"] --> INSTALL["install pipeline"]
  CLI --> SH["capa sh gateway"] --> MCPPROXY["MCP proxy/handler"]
  INSTALL --> PROVIDERS["Provider registry"]
  MCPPROXY --> TRACER["ToolCallTracer"] --> DB[("SQLite DB")]
  WEBUI["Web UI"] --> SERVERAPI["Server API routes"] --> DB
  SERVERAPI --> REGISTRIES["Registries: marketplace"]
  WEBUI --> ACTIVITY["Activity dashboard"] --> TRACER
  subgraph Legend
    direction LR
    _svc([Service]) ~~~ _db[(Database)] ~~~ _ext{{External}}
  end

Loading

High-Level Assessment

This is an aggregation/release PR promoting develop → main for v2.0.0; the meaningful design decisions live in the component PRs (#137–#160). At this level, focus review on integration/regression risk: CI green, smoke tests from the release checklist, and verifying no release blockers (auth, wrap on Windows, registry install/unpack, UI activity traces).

Files changed (32) +5901 / -2753

Enhancement (15) +4271 / -653

wrap.tsAdd 'capa wrap' command +246/-0

Add 'capa wrap' command

• Implements wrap command to create/reuse a shadow workspace, start watchers, and launch the provider without mutating the real repo.

src/cli/commands/wrap.ts

tool-call-tracer.tsAdd ToolCallTracer persistence/broadcast service +245/-0

Add ToolCallTracer persistence/broadcast service

• Introduces ToolCallTracer with AsyncLocalStorage request context, secret redaction, preview truncation, and DB persistence for the activity feed.

src/server/tool-call-tracer.ts

adapter.tsAdd Claude marketplace registry adapter +325/-0

Add Claude marketplace registry adapter

• Implements RegistryAdapter for Claude marketplace catalogs including preview/install snippet generation and optional tree inspection.

src/shared/registries/claude-marketplace/adapter.ts

registries-routes.tsSupport claude-marketplace registry source type +270/-230

Support claude-marketplace registry source type

• Extends registry routes to accept/validate claude-marketplace type and improves error sanitization.

src/server/registries-routes.ts

installer.tsInstall support for claude-marketplace registries +424/-320

Install support for claude-marketplace registries

• Extends slug derivation and install pipeline to handle claude-marketplace registries (parse/fetch/build adapter).

src/shared/registries/installer.ts

mcp-meta-routes.tsAdd MCP meta endpoints for UI/CLI +217/-0

Add MCP meta endpoints for UI/CLI

• Adds endpoints to list server tools and resolve skill content, with better error handling for unreachable/auth-required servers.

src/server/mcp-meta-routes.ts

activity-routes.tsAdd project activity ingest route +213/-0

Add project activity ingest route

• Adds handler to ingest tool-call/activity events, gating on agent-activity enabled and avoiding repeated disk parses via session cache.

src/server/activity-routes.ts

tool-calls.tsAdd ToolCallsRepo +406/-0

Add ToolCallsRepo

• Adds SQLite repository for inserting/finishing/listing tool_calls with per-project caps and pagination cursors.

src/db/tool-calls.ts

mcp-icons.tsExpose CAPA MCP server icons +10/-0

Expose CAPA MCP server icons

• Exports serverInfo icons for MCP (base64 inlined SVG favicon).

src/shared/mcp-icons.ts

auth.tsAdd 'capa auth --access-token' flow +188/-17

Add 'capa auth --access-token' flow

• Adds headless access-token authentication path (incl. self-hosted GitHub Enterprise / GitLab self-managed), with guidance/error messaging.

src/cli/commands/auth.ts

index.tsImplement 'capa sh' dispatcher +219/-0

Implement 'capa sh' dispatcher

• Adds command dispatch, schema loading, required-arg checks, and MCP execution wiring for shell tool invocation.

src/cli/commands/sh/index.ts

CapabilitiesSection.tsxRework capabilities editor section +301/-83

Rework capabilities editor section

• Adds collapsible capability sections, tools add menu, and integrates new editors (agents/plugins/tools) plus registry browse entry points.

web-ui/src/features/projects/components/CapabilitiesSection.tsx

ActivityRunDialog.tsxAdd Activity run details dialog +280/-0

Add Activity run details dialog

• Adds a timeline/run dialog with follow-latest behavior, fresh-span highlighting, and token usage summary.

web-ui/src/features/projects/components/activity/ActivityRunDialog.tsx

RegistryBrowseDialog.tsxAdd registry browse/search dialog +476/-0

Add registry browse/search dialog

• Adds dialog for browsing registries and adding skills/plugins via registry, inline, or local path modes.

web-ui/src/features/projects/components/registry-browse/RegistryBrowseDialog.tsx

hooks.tsAdd live project subscriptions + reorder helpers +451/-3

Add live project subscriptions + reorder helpers

• Adds project event subscription plumbing and helper reorder functions for tools/skills/servers.

web-ui/src/features/projects/hooks.ts

Refactor (4) +289 / -1998

adapter.tsImprove adapter organization comments +20/-0

Improve adapter organization comments

• Adds section headers to clarify structure (HTML utils, listing scrape, marketplace manifest, detail/install, export).

registries/claude-plugins/adapter.ts

registry.tsSplit provider registry into entries/* +18/-863

Split provider registry into entries/*

• Replaces large inline provider registry with composed imports from entries modules (claude-code, cursor, codex, etc.).

src/shared/providers/registry.ts

sh.tsRefactor 'capa sh' into module tree +3/-703

Refactor 'capa sh' into module tree

• Replaces monolithic implementation with submodules under src/cli/commands/sh/* and leaves a thin entrypoint.

src/cli/commands/sh.ts

add.tsRefactor and expand 'capa add' +248/-432

Refactor and expand 'capa add'

• Shrinks add.ts by delegating parsing/building to new modules and supporting more capability kinds and passthrough mode.

src/cli/commands/add.ts

Tests (3) +879 / -0

wrap-ensure-binary.test.tsAdd wrap binary resolution tests +32/-0

Add wrap binary resolution tests

• Adds unit tests ensuring wrap fails fast when provider binaries/shims are missing.

src/cli/commands/tests/wrap-ensure-binary.test.ts

tool-call-tracer.test.tsAdd ToolCallTracer tests +487/-0

Add ToolCallTracer tests

• Adds coverage for tool-call persistence, truncation/redaction, and state transitions.

src/server/tests/tool-call-tracer.test.ts

claude-marketplace.test.tsAdd Claude marketplace registry tests +360/-0

Add Claude marketplace registry tests

• Adds parsing/adapter tests for marketplace catalogs and snippet generation.

src/shared/registries/tests/claude-marketplace.test.ts

Documentation (8) +458 / -98

README.mdRewrite README for v2 positioning +156/-26

Rewrite README for v2 positioning

• Repositions CAPA as a package manager + MCP gateway; restructures quick start and highlights wrap, Web UI, activity traces, registries, and plugin unpack.

README.md

README.mdRefresh docs index +15/-9

Refresh docs index

• Updates the docs landing page to reflect v2 workflow and entry points.

docs/README.md

SKILL.mdAdjust bootstrap skill docs +4/-4

Adjust bootstrap skill docs

• Minor documentation updates for the bootstrap workflow.

skills/bootstrap/SKILL.md

SKILL.mdUpdate capabilities-manager skill docs +19/-14

Update capabilities-manager skill docs

• Documentation refresh aligned to v2 features and workflows.

skills/capabilities-manager/SKILL.md

capabilities-schema.mdExpand capabilities schema reference +35/-9

Expand capabilities schema reference

• Updates schema reference to match the v2 capabilities surface.

skills/capabilities-manager/references/capabilities-schema.md

commands.mdExpand CLI reference docs +125/-28

Expand CLI reference docs

• Documents additional v2 commands/flags (notably wrap, sh, passthrough, auth token usage).

skills/capabilities-manager/references/commands.md

troubleshooting.mdAdd troubleshooting reference +33/-0

Add troubleshooting reference

• New troubleshooting documentation for common setup and install issues.

skills/capabilities-manager/references/troubleshooting.md

workflows-and-examples.mdAdd v2 workflows/examples +71/-8

Add v2 workflows/examples

• Adds updated examples and workflows to match the v2 feature set.

skills/capabilities-manager/references/workflows-and-examples.md

Other (2) +4 / -4

security.ymlPin CodeQL action versions +2/-2

Pin CodeQL action versions

• Pins github/codeql-action init/analyze steps to v4.37.3 instead of floating v4.

.github/workflows/security.yml

package.jsonBump production dependencies +2/-2

Bump production dependencies

• Updates listr2 to ^11.0.0 and nanoid to ^6.0.0.

package.json

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.