Merge version-2.0 into develop

[Minitour]

Summary

• Bring CAPA v2 into develop: interactive capabilities editor, capa wrap shadow workspaces for CLI agents, live project/agent activity observability, and Claude marketplace registries.
• Expand install surface — plugin rules/subagents/hooks unpack, passthrough capa add, headless git auth via access tokens, and hardened install destinations so wrap never mutates the real project.
• Refresh docs/README positioning CAPA as a package manager and MCP gateway, plus tools UI polish and related bugfixes from the v2 branch.

Test plan

• Merge conflicts resolved (if any) and CI green on the merge commit
• capa init / capa install / capa clean against a sample project
• capa wrap for Cursor and Claude — shadow workspace only; real project untouched
• Web UI: capabilities editor YAML sync, tools reorder, Activity run dialog live follow
• Registry browse + Claude marketplace install path
• Auth: access-token headless git flow for self-hosted integrations
• Smoke capa add with and without --passthrough

[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. Manifest path traversal ✓ Resolved 🐞 Bug ⛨ Security

Description

collectFiles() joins repoRoot with unvalidated manifest paths and returns relative() paths
without rejecting absolute paths or .., enabling a plugin manifest to read files outside the
plugin root. Downstream parsers then join(pluginRoot, entry.relativePath) and read those paths, so
a malicious plugin can exfiltrate arbitrary local files into installed/materialized outputs.

Code

src/shared/plugin-manifest/path-field.ts[R43-46]

+	const full = join(repoRoot, relativePath);
+	if (!existsSync(full)) return [];
+
+	const exts = opts.extensions?.map((e) => e.toLowerCase());

Evidence

collectFiles() constructs a filesystem path from a manifest-controlled string without containment
checks and returns potentially out-of-root relative paths; parsers then use those returned paths to
read files from disk via join(pluginRoot, entry.relativePath). This creates a concrete escape from
the plugin root to arbitrary filesystem locations.

src/shared/plugin-manifest/path-field.ts[9-17]
src/shared/plugin-manifest/path-field.ts[38-56]
src/shared/plugin-manifest/commands-parser.ts[14-22]
src/shared/plugin-manifest/commands-parser.ts[40-60]

Agent prompt

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

## Issue description
`src/shared/plugin-manifest/path-field.ts` treats manifest-provided component paths (e.g. `commands`, `rules`, `agents`) as safe. Using `join(repoRoot, relativePath)` without validation allows `relativePath` like `../../..` or `/etc` to escape the plugin root. `collectFiles()` then emits `relative(repoRoot, abs)` paths that may start with `../`, and parsers later `join(pluginRoot, entry.relativePath)` and read them.
## Issue Context
These manifest fields are plugin-author controlled. If plugins can come from registries / remote sources, this becomes an arbitrary file read outside the plugin directory, with potential leakage into materialized skills/rules/agents.
## Fix Focus Areas
- src/shared/plugin-manifest/path-field.ts[9-79]
- src/shared/plugin-manifest/commands-parser.ts[10-60]
## Suggested fix
1. In `normalizePathField()` (or before calling `collectFiles()`), reject any path that is:
- absolute (POSIX `/...`, Windows drive letters like `C:`),
- contains `..` segments,
- empty after normalization (optional policy).
2. In `collectFiles()` enforce containment:
- `const resolved = resolve(repoRoot, relativePath)` and ensure it is inside `repoRoot` (e.g. `isPathInside(resolved, repoRoot)`), otherwise return `[]`.
- When computing `rel = relative(repoRoot, abs)`, skip any `rel` that starts with `..` or is absolute.
3. (Optional hardening) If you want to be robust against symlinks within `repoRoot`, consider using `realpathSync` on both root and candidate and re-check containment.
4. Add unit tests for manifest values like `"../.."`, `"/etc"`, and `"C:\\Windows"` to ensure they are rejected.

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

---

2. Unlinked directory edits lost ✓ Resolved 🐞 Bug ≡ Correctness

Description

promoteToRealProject() does not copy directory contents from workspace → real when both top-level
directories exist but are not linked; it only attempts tryRelink() and returns. When linking fails
(or a directory already exists in the workspace), changes under that directory will not be promoted
to the real project.

Code

src/cli/utils/wrap/symlink-workspace.ts[R304-307]

+    // Both dirs exist separately — prefer linking workspace to real (real wins structure).
+    // Do not delete workspace content without linking; try junction/symlink only.
+    tryRelink(realEntry, wsEntry);
+    return;

Evidence

watch-project uses promoteToRealProject() to propagate top-level changes. In
promoteToRealProject(), the branch for an existing directory in both workspace and real does not
copy content and depends entirely on tryRelink(), which on failure restores the workspace entry
and returns false. Therefore, directory contents are not promoted when relinking fails.

src/cli/utils/wrap/watch-project.ts[102-116]
src/cli/utils/wrap/symlink-workspace.ts[214-262]
src/cli/utils/wrap/symlink-workspace.ts[293-307]

Agent prompt

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

## Issue description
In wrap mode, directory changes are promoted by calling `promoteToRealProject(realRoot, wsRoot, name, providerIds)` where `name` is the top-level directory. If both `wsEntry` and `realEntry` exist as separate directories, `promoteToRealProject()` only calls `tryRelink(realEntry, wsEntry)` and returns without copying any directory contents; `tryRelink()` explicitly leaves the workspace entry as-is on failure.
## Issue Context
This breaks wrap synchronization when directory linking is unavailable/denied or when the workspace already contains a directory (e.g., from a previous session or tool behavior). File promotions have a copy fallback, but directory promotions do not.
## Fix Focus Areas
- src/cli/utils/wrap/symlink-workspace.ts[214-337]
- src/cli/utils/wrap/watch-project.ts[102-136]
## Suggested fix
Add a directory-copy fallback similar to the file case:
1. In the `st.isDirectory()` branch where `realEntry` exists:
- Attempt `tryRelink(realEntry, wsEntry)`.
- If it returns `false`, perform a best-effort mirror from workspace to real, e.g. `cpSync(wsEntry, realEntry, { recursive: true, force: true })` (or a safer merge strategy if needed).
- Optionally log a warning once per session that linking failed and CAPA is falling back to directory copying.
2. Add tests that simulate `createWorkspaceSymlink()` failure (e.g., by stubbing) and verify that a file created under an unlinked directory in the workspace is copied into the real project.

ⓘ 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

CAPA v2 merge: wrap shadow workspaces, web editor/observability, registries

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

AI Description

• Brings CAPA v2 into develop: interactive capabilities editor, registries, and live activity
 observability.
• Adds capa wrap shadow workspaces with detached watchers to avoid mutating real repos.
• Expands install/add flows: plugin unpacking (rules/subagents/hooks), --passthrough, and hardened
 wrap guards.
• Adds headless git auth via access tokens plus extensive refactors and test coverage.

Diagram

graph TD
  CLI["capa CLI"] --> Shadow["Wrap Workspace"] --> Providers["Agent Providers"]
  CLI --> Server["Local CAPA Server"] --> DB[("SQLite DB")]
  WebUI["Web UI"] --> Server
  Registries{{"Registries"}} --> Server
  Hooks{{"Provider Hooks"}} --> Server
  subgraph Legend
    direction LR
    _svc(["Service"]) ~~~ _db[("Database")] ~~~ _ext{{"External"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Make wrap workspaces copy-on-write instead of symlink trees

• ➕ Avoids symlink edge cases on Windows and some filesystems
• ➕ Less risk of tools that traverse symlinks unexpectedly
• ➖ Much higher disk usage and slower sync for large repos
• ➖ Harder to guarantee provider dirs never leak back without extra guards

2. Store activity events append-only (log file) instead of SQLite

• ➕ Simpler persistence layer; easier manual inspection
• ➕ Lower migration/schema coupling
• ➖ Harder queries/pagination/rollups for UI (stats, runs, filtering)
• ➖ More work to prune/limit retention safely

3. Keep install-only changes in CLI; avoid server-side capability mutations

• ➕ Reduces server surface area and write-path complexity
• ➕ Fewer consistency concerns between UI and CLI
• ➖ Web UI editing becomes much harder (needs local FS writes from browser)
• ➖ Harder to support live YAML sync and structured edits

Recommendation: The PR’s direction (symlink-based wrap workspace + SQLite-backed activity + server-side capability mutations) is the best fit for CAPA’s goals: it minimizes repo mutation risk, supports a responsive UI, and enables efficient activity queries. The main review recommendation is procedural: land and review this merge by subsystem/commit (wrap, activity/tool_calls, registries, passthrough, UI editor) and run targeted smoke tests for wrap and passthrough paths, because cross-cutting interactions are the primary risk.

Files changed (72) +13795 / -5339

Enhancement (49) +9825 / -786

adapter.tsAdd Claude plugins registry adapter +20/-0

Add Claude plugins registry adapter

• Introduces adapter logic for a Claude plugins registry source.

registries/claude-plugins/adapter.ts

index.tsWire new CLI commands and expanded add flags +165/-22

Wire new CLI commands and expanded add flags

• Registers wrap and activity-ingest entrypoints and expands 'capa add' to support more capability kinds and passthrough.

src/cli/index.ts

wrap.tsImplement 'capa wrap' shadow workspace runner +246/-0

Implement 'capa wrap' shadow workspace runner

• Adds wrap command to run providers from a persistent shadow workspace with watchers and session tracking.

src/cli/commands/wrap.ts

wrap-prompt.tsInteractive wrap provider resolution +87/-0

Interactive wrap provider resolution

• Adds prompt-based provider selection/validation for wrap targets.

src/cli/commands/wrap-prompt.ts

activity-ingest.tsAdd 'capa activity-ingest' hook reporter +111/-0

Add 'capa activity-ingest' hook reporter

• Reads JSON from stdin, normalizes events, and POSTs to local server fail-open.

src/cli/commands/activity-ingest.ts

add-builders.tsAdd builders for server/tool/rule/hook entries +446/-0

Add builders for server/tool/rule/hook entries

• Provides typed builders and kind resolution for new add flows.

src/cli/commands/add-builders.ts

install.tsHarden install with wrap guards, quiet, passthrough +165/-16

Harden install with wrap guards, quiet, passthrough

• Adds quiet flag handling, passthrough install dispatch, identity/project path options, and refusal to register/install inside wrap workspaces.

src/cli/commands/install.ts

clean-project.tsAdd clean-project implementation +173/-0

Add clean-project implementation

• Implements project cleanup behaviors used by 'capa clean' (including subagent cleanup).

src/cli/commands/clean-project.ts

init.tsExtend init to register project with local server +131/-19

Extend init to register project with local server

• Updates init workflow to create capabilities file and register/manage project identity.

src/cli/commands/init.ts

auth.tsAdd headless git auth via access tokens +188/-17

Add headless git auth via access tokens

• Supports PAT/access-token authentication for self-hosted providers without browser OAuth.

src/cli/commands/auth.ts

plugin-install.tsExpand plugin install to unpack more artifacts +299/-55

Expand plugin install to unpack more artifacts

• Extends plugin install to materialize rules/subagents/hooks along with existing plugin content.

src/cli/commands/plugin-install.ts

registry.tsSupport new registry source types +12/-1

Support new registry source types

• Extends registry CLI to handle additional registry types (including Claude marketplace).

src/cli/commands/registry.ts

args.tsAdd shell tool arg parsing +121/-0

Add shell tool arg parsing

• Implements argument parsing/slug mapping for 'capa sh'.

src/cli/commands/sh/args.ts

fetch.tsAdd shell tool metadata fetch +195/-0

Add shell tool metadata fetch

• Fetches tool listings/schemas from the local server for CLI execution.

src/cli/commands/sh/fetch.ts

help.tsAdd 'capa sh' help generation +97/-0

Add 'capa sh' help generation

• Generates detailed help output for shell tools and groups.

src/cli/commands/sh/help.ts

index.tsAdd 'capa sh' orchestrator +219/-0

Add 'capa sh' orchestrator

• Coordinates discovery, help, and execution for shell tool CLI.

src/cli/commands/sh/index.ts

registry.tsAdd shell tool registry builder +169/-0

Add shell tool registry builder

• Builds group/command registry used by 'capa sh'.

src/cli/commands/sh/registry.ts

workspace.tsImplement wrap workspace lifecycle +410/-0

Implement wrap workspace lifecycle

• Creates/reuses shadow workspaces under ~/.capa/workspaces and fingerprints capabilities to trigger reinstall.

src/cli/utils/wrap/workspace.ts

watch-project.tsImplement wrap watchers +447/-0

Implement wrap watchers

• Watches project/workspace changes and keeps shadow workspace state in sync.

src/cli/utils/wrap/watch-project.ts

watch-worker.tsAdd detached wrap watcher process +62/-0

Add detached wrap watcher process

• Runs wrap watchers in a detached worker to avoid TTY/stdin conflicts.

src/cli/utils/wrap/watch-worker.ts

launch.tsProvider launch helper for wrap +130/-0

Provider launch helper for wrap

• Adds provider spawn logic optimized for interactive TTY providers.

src/cli/utils/wrap/launch.ts

sessions.tsTrack active wrap sessions +279/-0

Track active wrap sessions

• Adds session bookkeeping for stopping/cleaning wrap sessions safely.

src/cli/utils/wrap/sessions.ts

symlink-workspace.tsCreate symlink-based shadow workspace +371/-0

Create symlink-based shadow workspace

• Builds a symlink tree with provider-owned-path exclusions to protect the real repo.

src/cli/utils/wrap/symlink-workspace.ts

wait-for-interrupt.tsGraceful interrupt handling for wrap +73/-0

Graceful interrupt handling for wrap

• Provides cross-platform Ctrl+C / quit handling for wrap sessions.

src/cli/utils/wrap/wait-for-interrupt.ts

index.tsIntroduce passthrough utility entrypoint +10/-0

Introduce passthrough utility entrypoint

• Exports passthrough install/add helpers used by CLI flags.

src/cli/utils/passthrough/index.ts

add.tsImplement 'capa add --passthrough' +252/-0

Implement 'capa add --passthrough'

• Writes provider-native files directly (skills/plugins/servers/rules/hooks) without managed tracking.

src/cli/utils/passthrough/add.ts

install.tsImplement 'capa install --passthrough' +216/-0

Implement 'capa install --passthrough'

• Adds passthrough install path that avoids capabilities management/DB tracking.

src/cli/utils/passthrough/install.ts

env.tsResolve env/auth context for passthrough +57/-0

Resolve env/auth context for passthrough

• Loads env files and opens auth DB to support private repo installs in passthrough mode.

src/cli/utils/passthrough/env.ts

native-mcp.tsWrite provider-native MCP configs in passthrough +158/-0

Write provider-native MCP configs in passthrough

• Upserts MCP server entries directly into provider config formats.

src/cli/utils/passthrough/native-mcp.ts

native-plugin-install.tsNative plugin install path for passthrough +75/-0

Native plugin install path for passthrough

• Installs plugins via provider-native mechanisms when supported.

src/cli/utils/passthrough/native-plugin-install.ts

install-plugin.tsPassthrough plugin installer +140/-0

Passthrough plugin installer

• Installs/unpacks plugins in passthrough flow and records warnings/writes.

src/cli/utils/passthrough/install-plugin.ts

install-skill.tsPassthrough skill installer +46/-0

Passthrough skill installer

• Installs skills directly into provider-native destinations in passthrough flow.

src/cli/utils/passthrough/install-skill.ts

claude-code.tsAdd Claude Code provider entry module +73/-0

Add Claude Code provider entry module

• Defines Claude Code provider integration details for v2 registry layout.

src/shared/providers/entries/claude-code.ts

codex.tsAdd Codex provider entry module +78/-0

Add Codex provider entry module

• Defines Codex integration details for capability fan-out.

src/shared/providers/entries/codex.ts

cursor.tsAdd Cursor provider entry module +85/-0

Add Cursor provider entry module

• Defines Cursor integration details including rules/subagents/hooks support.

src/shared/providers/entries/cursor.ts

adapter.tsAdd Claude marketplace adapter +325/-0

Add Claude marketplace adapter

• Implements registry adapter for marketplace catalogs with preview/install snippet support.

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

fetch.tsAdd Claude marketplace catalog fetcher +326/-0

Add Claude marketplace catalog fetcher

• Fetches and parses marketplace catalogs from supported sources.

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

index.tsExport Claude marketplace registry helpers +42/-0

Export Claude marketplace registry helpers

• Adds module entrypoint for marketplace parsing/fetch/adapter construction.

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

installer.tsExtend registry installer for Claude marketplace type +424/-320

Extend registry installer for Claude marketplace type

• Adds new registry type handling, slug derivation, and adapter install for claude-marketplace.

src/shared/registries/installer.ts

activity-routes.tsAdd activity ingest and hook-sync routes +207/-0

Add activity ingest and hook-sync routes

• Implements POST ingest of tool-call-like events and system hook sync per project.

src/server/activity-routes.ts

tool-call-tracer.tsAdd ToolCallTracer for persistence + live updates +245/-0

Add ToolCallTracer for persistence + live updates

• Adds start/finish tracing with redaction/truncation and SSE notifications for UI.

src/server/tool-call-tracer.ts

git-integrations-routes.tsExtract git integration HTTP routes +338/-0

Extract git integration HTTP routes

• Adds route module for OAuth start/callback, PAT flows, and integration listing/disconnect.

src/server/git-integrations-routes.ts

registries-routes.tsAdd claude-marketplace registry support in API +268/-230

Add claude-marketplace registry support in API

• Extends registry routes to accept and validate the claude-marketplace source type.

src/server/registries-routes.ts

schema.tsExtend schema for registries and activity tracing +118/-23

Extend schema for registries and activity tracing

• Adds claude-marketplace registry type and support tables for tool call activity tracing.

src/db/schema.ts

tool-calls.tsAdd tool_calls repository +406/-0

Add tool_calls repository

• Implements insert/finish/list/prune for tool call records with caps/pagination.

src/db/tool-calls.ts

CapabilitiesSection.tsxUpgrade capabilities UI to interactive editor +301/-83

Upgrade capabilities UI to interactive editor

• Adds richer editing UX (add menus, collapsibles, agents/plugins integration, registry browse entrypoints).

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

RegistryBrowseDialog.tsxAdd registry browse dialog +476/-0

Add registry browse dialog

• New dialog for searching registries and installing skills/plugins (registry/inline/local modes).

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

ActivityRunDialog.tsxAdd live activity run dialog +280/-0

Add live activity run dialog

• Adds detailed run view with follow-latest behavior and span timeline rendering.

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

ReorderableList.tsxAdd reorderable list component +263/-0

Add reorderable list component

• Introduces reusable drag-to-reorder UI used across editors.

web-ui/src/components/common/ReorderableList.tsx

Bug fix (2) +127 / -0

wrap-ensure-binary.tsFail fast when wrap binary is missing +14/-0

Fail fast when wrap binary is missing

• Validates the provider launch binary exists on PATH before workspace prep.

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

marker.tsMark wrap workspaces and refuse unsafe operations +113/-0

Mark wrap workspaces and refuse unsafe operations

• Adds marker and guards used by install/add/clean to prevent accidental writes inside wrap workspaces.

src/cli/utils/wrap/marker.ts

Refactor (8) +2567 / -4453

add.tsRefactor 'capa add' into kind-based flow + passthrough +248/-432

Refactor 'capa add' into kind-based flow + passthrough

• Delegates parsing/building to new modules, adds server/tool/rule/hook kinds, supports '--passthrough', and centralizes registry resolution.

src/cli/commands/add.ts

add-parse-plugin.tsExtract plugin source parsing +149/-0

Extract plugin source parsing

• Moves plugin source grammar parsing out of add.ts for reuse and testing.

src/cli/commands/add-parse-plugin.ts

add-parse-skill.tsExtract skill source parsing +190/-0

Extract skill source parsing

• Moves skill source grammar parsing out of add.ts for reuse and testing.

src/cli/commands/add-parse-skill.ts

clean.tsRefactor clean command surface +41/-126

Refactor clean command surface

• Moves project-specific cleanup logic into a separate module.

src/cli/commands/clean.ts

resolve-registry-source.tsCentralize registry-prefixed source resolution +116/-0

Centralize registry-prefixed source resolution

• Adds shared helper used by add/passthrough to resolve registry items.

src/cli/commands/resolve-registry-source.ts

sh.tsConvert sh command to thin wrapper +3/-703

Convert sh command to thin wrapper

• Replaces monolithic implementation with a small entry file calling sh/ modules.

src/cli/commands/sh.ts

registry.tsSplit provider registry into per-provider entry modules +18/-863

Split provider registry into per-provider entry modules

• Replaces huge inline provider map with composed imports from entries/*.

src/shared/providers/registry.ts

index.tsRestructure server and wire new v2 routes +1802/-2329

Restructure server and wire new v2 routes

• Extracts major route groups and wires capabilities watcher, registries, git integrations, projects, and activity endpoints.

src/server/index.ts

Tests (3) +624 / -0

wrap-prompt.test.tsAdd wrap prompt tests +60/-0

Add wrap prompt tests

• Adds test coverage for provider selection/validation behaviors.

src/cli/commands/tests/wrap-prompt.test.ts

activity-routes.test.tsAdd activity routes tests +171/-0

Add activity routes tests

• Adds tests for activity ingest and related server behaviors.

src/server/tests/activity-routes.test.ts

capabilities.test.tsAdd/expand capabilities parsing tests +393/-0

Add/expand capabilities parsing tests

• Adds tests for v2 capabilities parsing/normalization behavior.

src/shared/tests/capabilities.test.ts

Documentation (8) +458 / -98

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

Rewrite README for v2 positioning and quickstart

• Repositions CAPA as a package manager + MCP gateway and documents wrap, web UI, registries, and activity.

README.md

README.mdRefresh docs index for v2 +15/-9

Refresh docs index for v2

• Updates docs landing content to align with v2 feature set.

docs/README.md

SKILL.mdUpdate bootstrap skill text +4/-4

Update bootstrap skill text

• Adjusts bootstrap guidance to match v2 capabilities layout.

skills/bootstrap/SKILL.md

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

Update capabilities-manager skill docs

• Expands skill instructions to cover new v2 workflows and commands.

skills/capabilities-manager/SKILL.md

capabilities-schema.mdDocument expanded capabilities schema +35/-9

Document expanded capabilities schema

• Adds/updates schema reference for new capability sections and options.

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

commands.mdExpand command reference for v2 CLI +125/-28

Expand command reference for v2 CLI

• Documents new/changed commands including wrap, passthrough add/install, and auth changes.

skills/capabilities-manager/references/commands.md

troubleshooting.mdAdd troubleshooting guide +33/-0

Add troubleshooting guide

• Introduces troubleshooting doc for common installation/editor issues.

skills/capabilities-manager/references/troubleshooting.md

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

Add v2 workflows and examples

• Adds updated examples covering registries, wrap, and activity observability.

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

Other (2) +194 / -2

index.cssAdd styling for v2 UI surface +188/-0

Add styling for v2 UI surface

• Adds CSS to support new dialogs, panels, and activity visuals.

web-ui/src/index.css

tsconfig.jsonUpdate web-ui TypeScript config +6/-2

Update web-ui TypeScript config

• Adjusts TS config to support new modules and build setup.

web-ui/tsconfig.json