feat: Implement isolated plugin runtimes and project-scoped source management (#207)

Author: finxo

.claude/docs/community-plugins.md

@@ -4,238 +4,176 @@
 
 Titan supports community plugins in addition to the official plugins bundled with the CLI.
 
-There are currently two source channels:
+There are two source channels:
 
-- `stable`: install from a git repository at an explicit tag or commit
-- `dev_local`: use a local plugin checkout during development
+- `stable`: a shared project pin stored in `.titan/config.toml`
+- `dev_local`: a user-local override stored in `~/.titan/config.toml`
 
-Community plugin installs are tracked globally in `~/.titan/community_plugins.toml`, while the active source selection for a given project is stored in that project's `.titan/config.toml`.
+Titan itself can remain globally installed, while project-pinned community plugins are prepared in isolated local runtimes.
 
 ---
 
 ## Key Files
 
 | File | Role |
 |------|------|
-| `titan_cli/core/plugins/community.py` | Business logic for URL parsing, metadata preview, stable/dev-local install helpers, updates, uninstall, tracking file I/O |
-| `titan_cli/core/plugins/models.py` | Plugin source config model (`source.channel`, `source.path`) |
-| `titan_cli/core/plugins/plugin_registry.py` | Applies `dev_local` source overrides before plugin initialization |
-| `titan_cli/ui/tui/screens/install_plugin_screen.py` | Stable community plugin install wizard |
-| `titan_cli/ui/tui/screens/plugin_management.py` | Source display, update/uninstall actions, stable reset for `dev_local` |
-| `titan_cli/ui/tui/widgets/wizard.py` | Shared wizard widgets: `StepStatus`, `WizardStep`, `StepIndicator` |
+| `titan_cli/core/plugins/community_sources.py` | URL parsing, metadata preview, ref resolution, update checks |
+| `titan_cli/core/plugins/runtime.py` | Isolated runtime/cache manager for `stable` community plugins |
+| `titan_cli/core/plugins/models.py` | Plugin source config model |
+| `titan_cli/core/plugins/plugin_registry.py` | Resolves effective source and loads `dev_local` or cached `stable` plugin code |
+| `titan_cli/ui/tui/screens/install_plugin_screen.py` | Adds a stable community plugin to the current project |
+| `titan_cli/ui/tui/screens/plugin_management.py` | Displays source state and handles update/remove/dev override actions |
 
 ---
 
-## Channels
+## Source Model
 
-### `stable`
+### Shared project pin (`stable`)
 
-This is the normal community-plugin flow. The user installs from a git repository URL and must include an explicit version selector:
-
-```text
-https://github.com/user/titan-plugin-custom@v1.2.0
-https://github.com/user/titan-plugin-custom@abc123def456
-```
-
-Titan resolves that ref to a concrete commit SHA and installs from that pinned revision. After install, the current project stores:
+The shared stable source lives in `.titan/config.toml`:
 
 ```toml
 [plugins.custom]
 enabled = true
 
 [plugins.custom.source]
 channel = "stable"
+repo_url = "https://github.com/user/titan-plugin-custom"
+requested_ref = "v1.2.0"
+resolved_commit = "0123456789abcdef0123456789abcdef01234567"
 ```
 
-For update detection, Titan checks the repository's latest GitHub Release and
-uses its `tag_name` as the next requested stable version. In other words:
-- install/update discovery is version/tag based
-- the actual installed artifact is still pinned to the resolved commit SHA
-
-### `dev_local`
+Notes:
+- `requested_ref` stores the exact tag/ref used by that repository
+- `resolved_commit` is the operational truth
+- this block is meant to be committed and reviewed in PRs
 
-This is the development channel. It is not a remote dev feed or prerelease registry. It means "load this plugin from a local repository path".
+### User-local override (`dev_local`)
 
-The current project stores:
+The active local development override lives in `~/.titan/config.toml`:
 
 ```toml
-[plugins.custom]
-enabled = true
-
 [plugins.custom.source]
 channel = "dev_local"
 path = "/absolute/path/to/local/plugin/repo"
 ```
 
-When `dev_local` is active, the plugin registry loads the plugin directly from that repo:
-
-1. Reads `pyproject.toml`
-2. Parses the `titan.plugins` entry points
-3. Finds the requested Titan plugin name
-4. Prepends the repo to `sys.path`
-5. Imports and instantiates the plugin class
-
-This override is applied before plugin initialization, so the local checkout wins over any installed stable version for that project.
-
-If `channel = "dev_local"` is set without a `path`, the plugin is marked as failed to load.
+Notes:
+- this is not committed to the project
+- if present, it wins over the project's `stable` pin on that machine
+- when switching back to `stable`, the remembered `path` may stay in global config as UX state, but it is ignored
 
 ---
 
-## Stable URL Format
+## Resolution Rules
 
-Users must always include an explicit version — bare URLs without `@version` are rejected:
+Titan resolves the effective source in this order:
 
-```
-# Accepted
-https://github.com/user/titan-plugin-custom@v1.2.0
-https://github.com/user/titan-plugin-custom@abc123def456
+1. global `dev_local` override
+2. project `stable` pin
 
-# Rejected
-https://github.com/user/titan-plugin-custom
-```
-
-Internally this becomes: `git+https://github.com/user/titan-plugin-custom.git@v1.2.0`
+If neither exists, the plugin is treated as a normal installed plugin with no community source metadata.
 
 ---
 
-## Stable Install Flow (4 steps)
+## Stable Install Flow
 
 ### 1. URL
-User enters `https://repo@version`. Validated with `validate_url()` before advancing.
-
-### 2. Preview
-Fetches `pyproject.toml` from the repo at that exact version and shows:
-- Package name, version, description, authors
-- Titan entry points registered (`[titan.plugins]`)
-- Python dependencies
 
-**Host detection** (`PluginHost` StrEnum): `GITHUB`, `GITLAB`, `BITBUCKET`, `UNKNOWN`
+The user enters a URL with an explicit ref:
 
-Raw URL patterns per host:
-```
-GitHub:    https://raw.githubusercontent.com/{path}/{version}/pyproject.toml
-GitLab:    https://gitlab.com/{path}/-/raw/{version}/pyproject.toml
-Bitbucket: https://bitbucket.org/{path}/raw/{version}/pyproject.toml
-Unknown:   fetch skipped — warning shown, install still allowed
+```text
+https://github.com/user/titan-plugin-custom@v1.2.0
+https://github.com/user/titan-plugin-custom@abc123def456
 ```
 
-Error cases (all allow proceeding):
-- HTTP 404 → URL or version not found
-- Network error → connection problem
-- No `[titan.plugins]` entry point → warns plugin won't be visible in Titan
-- Unparseable pyproject.toml → warns metadata unreadable
+Bare repository URLs without `@ref` are rejected.
 
-A **security warning** is always shown regardless of outcome.
-
-### 3. Install
-Runs a package install in Titan's active Python environment:
+### 2. Preview
 
-- pipx environment: `pipx inject titan-cli git+<url>.git@<resolved_commit>`
-- non-pipx environment: `python -m pip install git+<url>.git@<resolved_commit>`
+Titan fetches `pyproject.toml` from that source and shows:
+- package name
+- version
+- description
+- authors
+- Titan entry points
+- Python dependencies
 
-The requested tag or short ref is resolved to a full commit SHA first. This is the security anchor for stable installs: updates only happen when the user explicitly installs or updates again.
+### 3. Pin + runtime
 
-On success:
-1. Saves record to `~/.titan/community_plugins.toml`
-2. Writes the project source override as `channel = "stable"`
-3. Calls `self.config.load()` → auto-reloads registry + re-initializes all plugins (no restart needed)
+Titan resolves the requested ref to a full commit SHA and then:
 
-On failure: shows pipx stderr + actionable suggestions.
+1. writes the shared stable pin into the current project's `.titan/config.toml`
+2. prepares an isolated runtime for that plugin commit
+3. reloads config/registry so the plugin becomes available immediately
 
 ### 4. Done
-Success or failure summary. "Finish" dismisses the wizard.
 
----
+The wizard shows the pinned ref/commit and the Titan plugin name if found.
 
-## Tracking File
+---
 
-`~/.titan/community_plugins.toml` is global and stores installed/tracked community plugin records. It is not the same as project source selection.
+## Runtime Layout
 
-Current stable records look like this:
+Stable community plugins are prepared in a cache like:
 
-```toml
-[[plugins]]
-repo_url = "https://github.com/user/titan-plugin-custom"
-package_name = "titan-plugin-custom"
-titan_plugin_name = "custom"
-installed_at = "2026-03-06T10:30:00+00:00"
-channel = "stable"
-requested_ref = "v1.2.0"
-resolved_commit = "0123456789abcdef0123456789abcdef01234567"
-```
-
-`dev_local` records use the same structure but store the local path instead of git revision metadata:
-
-```toml
-[[plugins]]
-repo_url = ""
-package_name = "titan-plugin-custom"
-titan_plugin_name = "custom"
-installed_at = "2026-03-06T10:30:00+00:00"
-channel = "dev_local"
-dev_local_path = "/absolute/path/to/local/plugin/repo"
+```text
+~/.titan/plugin-cache/<plugin_name>/<resolved_commit>/
+  src/
+  venv/
 ```
 
-Key functions in `community.py`:
-- `load_community_plugins()` → `list[CommunityPluginRecord]`
-- `save_community_plugin(record)` → appends to file
-- `remove_community_plugin_by_name(titan_plugin_name)` → removes all tracked channels for a Titan plugin name
-- `remove_community_plugin_by_channel(titan_plugin_name, channel)` → removes one tracked channel only
-- `get_community_plugin_names()` → `set[str]` of titan_plugin_names (used for `[community]` badge)
-- `get_community_plugin_by_titan_name(name)` → `Optional[CommunityPluginRecord]`
-- `get_community_plugin_by_name_and_channel(name, channel)` → specific channel lookup
-
----
+The runtime manager:
 
-## Uninstall Flow
+1. checks out the pinned commit into `src/`
+2. creates a dedicated `venv/`
+3. installs the plugin into that isolated environment
 
-In Plugin Management, pressing `u` (or clicking "Uninstall") on a community plugin:
-1. If the active source is `dev_local`, Titan does not uninstall a package. It only resets the project source override back to `stable` and removes `path`.
-2. If the active source is a tracked stable community plugin, Titan uninstalls the package from the active environment.
-3. Removes the tracked record(s) as needed.
-4. Calls `self.config.load()` to reload the registry.
-5. Refreshes the plugin list.
+The plugin registry then loads the plugin from:
+- the cached source directory
+- the cached `site-packages`
 
-Only stable community plugins can be updated. `dev_local` intentionally has no update flow.
+This gives dependency isolation per `plugin + commit` while still using the current in-process plugin API.
 
 ---
 
-## Dev-Local Install Helper
+## Update Flow
+
+Only `stable` community plugins can be updated.
 
-The codebase includes `install_community_plugin_dev_local(local_path)`, which performs an editable install:
+Update behavior:
 
-- pipx environment: `pipx runpip titan-cli install -e <path>`
-- non-pipx environment: `python -m pip install -e <path>`
+1. check latest release/tag from the repo host
+2. resolve that ref to a full SHA
+3. update the current project's `.titan/config.toml`
+4. prepare the runtime for the new commit
+5. reload Titan config/registry
 
-This is useful for plugin development, but the current TUI install wizard is specifically built around the `stable` git URL flow. The active `dev_local` behavior is primarily driven by project config source overrides.
+`dev_local` has no update flow by design.
 
 ---
 
-## Wizard Widgets (`titan_cli/ui/tui/widgets/wizard.py`)
+## Remove Flow
 
-Shared by `install_plugin_screen.py` and `plugin_config_wizard.py`:
+In Plugin Management:
 
-```python
-class StepStatus(StrEnum):
-    PENDING     = "pending"
-    IN_PROGRESS = "in_progress"
-    COMPLETED   = "completed"
+- if the active source is `dev_local`, remove the local override from global config
+- if the active source is `stable`, remove the plugin from the current project's config
 
-@dataclass
-class WizardStep:
-    id: str
-    title: str
+This no longer uninstalls a package from Titan's global environment, because `stable` community plugins are no longer managed with `pipx inject`.
 
-class StepIndicator(Static):
-    def __init__(self, step_number: int, step: WizardStep, status: StepStatus): ...
-```
+---
 
-Exported from `titan_cli/ui/tui/widgets/__init__.py`.
+## Important Notes
 
----
+- `~/.titan/community_plugins.toml` is no longer used
+- `community.py` was replaced by `community_sources.py`
+- official plugins can still follow their own global install path; the per-project runtime model here is specifically for community plugins
 
-## Known Technical Debt
+---
 
-`plugin_config_wizard.py` still uses plain dicts (`{"id": ..., "title": ...}`) for its steps instead of `WizardStep`. It wraps them with `WizardStep(id=step["id"], title=step["title"])` when calling `StepIndicator`. Full refactor is pending a future PR.
+## Known Limits
 
-The public docs are still sparse on community plugins, and some older references still describe only the stable install flow. When updating docs, treat `dev_local` as a first-class source channel and avoid describing it as a remote development release channel.
+- community plugins still run in-process after being imported
+- dependency isolation is per plugin runtime, but execution is not sandboxed in a subprocess
+- a future architecture could move plugin execution out-of-process if stronger isolation is needed

.titan/config.toml

@@ -20,4 +20,4 @@ pr_template_path = ".github/pull_request_template.md"
 auto_assign_prs = true
 
 [plugins.jira]
-enabled = false
+enabled = false

docs/concepts/plugins.md

@@ -28,30 +28,32 @@ Titan also supports community plugins from external repositories.
 
 There are currently two source channels:
 
-- `stable`: install a plugin from a git repository pinned to a tag or commit
+- `stable`: pin a plugin version in the project config using a git tag or commit
 - `dev_local`: use a local checkout of a plugin repository during development
 
-Project source selection is stored in `.titan/config.toml`:
+The shared stable pin lives in `.titan/config.toml`:
 
 ```toml
 [plugins.custom]
 enabled = true
 
 [plugins.custom.source]
 channel = "stable"
+repo_url = "https://github.com/user/titan-plugin-custom"
+requested_ref = "v1.2.0"
+resolved_commit = "0123456789abcdef0123456789abcdef01234567"
 ```
 
-For local plugin development:
+`requested_ref` stores the exact tag or ref used by that repository. Some repos use
+tags like `v1.2.0`; others use `1.2.0`.
 
-```toml
-[plugins.custom]
-enabled = true
+For local plugin development, the active override lives in `~/.titan/config.toml`:
 
+```toml
 [plugins.custom.source]
 channel = "dev_local"
 path = "/absolute/path/to/local/plugin/repo"
 ```
 
-In `dev_local`, Titan loads the plugin directly from the local repository by reading its `pyproject.toml` and `titan.plugins` entry point.
-
-Community plugin installation metadata is tracked globally in `~/.titan/community_plugins.toml`.
+In `dev_local`, Titan loads the plugin directly from the local repository. In `stable`,
+Titan prepares an isolated local runtime for the pinned commit.