feat(plugins): install from subdirectories and select update refs

[dviejokfs]

Install TypeScript plugins from a self-contained GitHub subdirectory and select branches, tags, or commits for updates. For example:

bunx @temps-sdk/cli plugin install https://github.com/example/plugins --path plugins/route-checker --ref release/v1
bunx @temps-sdk/cli plugin update route-checker --ref v1.1.0

The console exposes the directory at install time and a ref override when updating. Catalog review opens the exact directory at the reviewed commit. Updating without a ref retains the stored selection; every install records the resolved commit. Root installations remain compatible.

The selected path is validated and included in receipts, status, audit attribution, source conflict checks, and actor identity. Same-source ref updates preserve grants; attempting to install the same plugin name from another path is rejected. Only the selected subtree enters the existing bounded Docker builder. Catalog schema v2 permits sibling plugins in one repository; schema v1 remains supported for root entries.

Registry companion: gotempsh/plugins#5. Plugin authoring skill and generated API/CLI references are updated here.

Evidence

• cargo test --lib -p temps-external-plugins -- --test-threads=1: 193 passed. New coverage includes paths, sibling identity conflicts, receipt tampering, backward-compatible root receipts, custom branches/tags/SHAs, missing refs, and catalog v2.
• cargo test --lib -p temps-external-plugins pinned_builder_compiles_without_host_mounts_when_image_available -- --nocapture: 1 passed, Docker and the pinned builder image were present. The selected plugins/fixture compiled successfully despite invalid plugin manifests at repository root and in a sibling. Final changed fixture/conflict tests were rerun after the full suite.
• cargo check --lib -p temps-external-plugins and Clippy with -D warnings: passed.
• bun test src/commands/plugin/install.test.ts: 35 passed; CLI typecheck passed.
• Local source CLI against the real isolated API: bun run src/index.ts plugin install <public-template-repository> --path missing-plugin-fixture --ref main --yes exited 1 with Repository must contain a matching package.json and src/index.ts. A temporary local API key was created (201) and deleted (204); no plugin was installed.
• Relevant web library/component/page tests: 50 passed; web typecheck and targeted ESLint passed. Production web build passed.
• Regenerated both API clients from the new local server. Canonical CLI OpenAPI check passed (836 paths).
• Real authenticated local API: invalid paths ../escape, /absolute, and plugins//demo each returned 400 Invalid Plugin Repository. The live OpenAPI schema exposes the install path field.
• Browser walkthrough exercised directory and slash-containing ref controls, with desktop/mobile captures and 390px viewport / 390px document width.
• Committed Playwright regression plugin-source-selection.spec.ts: 1 passed against the production web bundle and local session. Plugin endpoints were mocked: observed update bodies were {"ref_name":"release/v2"} then {}, confirming the override clears after success. It also checks the stored directory and mobile width.
• Independent security review and scoped frontend/CLI/registry review: passed.

Limits

No published nested plugin was installed and upgraded end to end in this session; evidence separates real source/build/API tests from mocked UI update responses. The shared browser assertion initially reported the existing theme-script React warning in development mode; the same test passed against the production bundle. No broad web lint cleanup is included.

Each directory requires its own lockfile and complete source/build assets; parent workspace dependencies are not included. Whole-repository download/extraction limits still apply. Catalog-selected installs remain pinned to the reviewed commit; selecting a new branch/tag is explicit. Native plugins run with the host OS account's permissions, not in an OS sandbox.

[github-actions]

📓 Changelog preview

This is what your commits will add to the generated CHANGELOG.md at release time (via git-cliff). Do not edit CHANGELOG.md by hand — it is generated from your Conventional Commit messages.

## [Unreleased]

### Added

- **plugins:** Install from subdirectories and select update refs

### Fixed

- **plugins:** Explain invalid repository directory paths

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no outstanding correctness, security, or repository-rule violations were identified.

Summary

This PR adds support for installing GitHub-hosted plugins from validated repository subdirectories and selecting branches, tags, or commits during installation and updates.

• Persists the selected directory and resolved commit in receipts, status responses, audit attribution, and source identity checks.
• Extends catalog schema v2 to represent sibling plugins from one repository while retaining schema v1 compatibility.
• Adds matching CLI and console controls, validation, generated API types, documentation, and regression coverage.
• The follow-up change provides sanitized, actionable API guidance for invalid plugin paths without disclosing rejected input.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[CLI or Console] -->|repository, path, ref| B[Install API]
    B --> C[Validate URL, path, and ref]
    C --> D[Resolve Git ref to commit]
    D --> E[Extract link-free archive]
    E --> F[Select plugin subtree]
    F --> G[Bounded Docker build]
    G --> H[Install plugin]
    H --> I[Persist receipt]
    I --> J[Status, audit, and future updates]
    J -->|stored path and ref| D

Loading

_{Reviews (2) · Last reviewed commit: "fix(plugins): explain invalid repository..."}