Files
kandev/docs/specs/plugins/system-design/repository-provider-task-creation.md
T

271 lines
12 KiB
Markdown

---
status: current
system: plugins
requirements:
- REQ-PLUGINS-REPOSITORY-TASK-CREATION-001
---
# Plugin Repository Task Creation System Design
## Purpose and boundaries
The plugin system owns the server-side contract that turns an untrusted plugin
repository selection into an authoritative repository descriptor. The task
service consumes that contract before it writes a new task.
The task system continues to own task validation, idempotency, repository
attachment, branch policies, and task persistence. The workspace system
continues to own repository rows. The plugin keeps ownership of provider API
calls and external credentials.
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.1` | [Create sequence](#create-sequence) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.2` | [Inspection action](#inspection-action) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.3` | [Trust boundary](#trust-boundary) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.4` | [Descriptor validation](#descriptor-validation) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.5` | [Failure contract](#failure-contract) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.6` | [Multi-repository preflight](#multi-repository-preflight) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.7` | [Compatibility](#compatibility) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.8` | [Failure contract](#failure-contract) |
| `AC-PLUGINS-REPOSITORY-TASK-CREATION-001.9` | [Responsive behavior](#responsive-behavior) |
## Components and responsibilities
- `internal/plugins.Service` resolves the active manifest owner and invokes its
standardized workspace-scoped `repositories.inspect` action. It limits,
parses, and validates the response.
- A narrow task-service `RepositorySelectionResolver` interface accepts the
verified workspace ID and an untrusted repository selection. Production
composition adapts the plugin service to this interface. Focused task tests
use a stub.
- `internal/task/service.Service` preflights all first-use plugin selections,
replaces each one with an internal trusted descriptor, and only then enters
the existing create and repository-attachment sequence.
- Task HTTP and WebSocket handlers map typed inspection failures to bounded
client errors. The existing task-dialog submit path keeps the dialog open and
shows the returned message in its error toast.
- The plugin fixture supplies deterministic list, inspect, and branch action
results for backend and Playwright tests. It contains no real credentials.
## Data and contracts
No database migration or public task-create schema change is required. The
existing task-create repository fields remain selection hints. The internal
`TrustedProviderDescriptor` marker remains unavailable to JSON callers.
The task service classifies each selection before persistence:
- An existing `repository_id` or an internal trusted descriptor uses its
existing server-owned path.
- A remote URL with a non-built-in provider uses the plugin resolver.
- A remote URL with a blank or built-in provider is parsed through the existing
built-in path. An unsupported, malformed, or provider-mismatched URL fails
closed before any task or repository write.
The resolver returns the existing internal repository input shape with a
complete descriptor and `TrustedProviderDescriptor` set by server code. It
does not return credentials.
## Inspection action
A plugin that supports first-use repository selection declares this action:
```yaml
actions:
- key: "repositories.inspect"
scope: "workspace"
max_body_bytes: 16384
```
Kandev selects the active plugin from manifest ownership of the requested
provider ID. It does not accept a plugin ID from the request. It invokes the
action with verified workspace context and a small body:
```json
{
"url": "https://code.example.com/owner/repository"
}
```
The URL is untrusted. The plugin must first prove that the URL belongs to its
configured provider connection. It must not send connection credentials to an
origin selected only by this value.
A successful response contains either a `repository` object or the same object
as the top-level response for compatibility with existing provider actions:
```json
{
"repository": {
"provider_id": "example-provider",
"provider_host": "https://code.example.com",
"provider_scope": "https://code.example.com/context-a",
"provider_repository_id": "immutable-repository-id",
"owner_or_project": "owner",
"name": "repository",
"clone_url": "https://code.example.com/owner/repository.git",
"default_branch": "main"
}
}
```
`{"matched":false}` is a normal no-match response. Pull-request inspection
envelopes may contain additional change-request fields, but task repository
resolution reads only the nested repository descriptor.
The host applies the declared request limit, a 15-second deadline, a 1 MiB
response limit, and typed action error classification. It does not retry the
action inside one task-create attempt.
## Trust boundary
The request's provider ID is used only to select a manifest ownership slot. The
active registry determines the plugin record. The remote URL and any other
request fields are lookup or pinning hints. They never become persisted
authority and never enter the Git credential broker.
The plugin response is authoritative because it arrives server-to-server from
the active manifest owner under verified workspace context. Installed plugin
code is trusted to use its own connection safely, but Kandev still validates
the returned descriptor before persistence.
The browser cannot set `TrustedProviderDescriptor`. The existing plugin Host
`Tasks.Create` adapter can still set it after its separate authenticated Host
authorization. These are the only two server-owned paths to the trusted
resolver.
## Descriptor validation
The plugin service and task service jointly enforce these rules before writes:
- The response provider ID equals the manifest-owned provider ID.
- Provider host is a normalized HTTPS origin without user information.
- Provider scope is either empty or a valid normalized scope.
- Immutable provider repository ID, owner or project, name, clone URL, and
default branch are present.
- Clone URL is credential-free HTTPS and its origin matches the provider host.
- Optional immutable request hints, such as provider scope or repository ID,
match the response. Mutable owner, name, host, clone URL, and branch values
from the browser are ignored.
- The response is within size limits and contains one repository descriptor.
The existing trusted remote repository validator remains the final persistence
guard. Validation logic should be shared instead of creating a weaker plugin
action path.
## Create sequence
```mermaid
sequenceDiagram
actor User
participant UI as Native task dialog
participant Task as Task service
participant Plugins as Plugin service
participant Plugin as Connected code-host plugin
participant DB as Kandev database
User->>UI: Select plugin repository and create task
UI->>Task: Task fields plus repository selection
Task->>Task: Authorize workspace and check external ID
Task->>Plugins: Resolve selection in verified workspace
Plugins->>Plugins: Find active manifest owner
Plugins->>Plugin: repositories.inspect with untrusted URL
Plugin-->>Plugins: Authoritative credential-free descriptor
Plugins->>Plugins: Validate identity, origin, scope, and limits
Plugins-->>Task: Internal trusted descriptor
Task->>Task: Preflight all selected repositories
Task->>DB: Create task, canonical repository, and association
Task-->>UI: Created task
UI-->>User: Open created task
```
Task-create idempotency stays first. If an external ID already names an
existing task, Kandev returns that task without contacting a plugin. For a new
task, plugin preflight runs after workspace authorization and request
normalization but before the task row insert.
After preflight, the existing `resolveTrustedRemoteRepository` and
`FindOrCreateRepository` path preserves canonical provider identity and
deduplicates a repository that another request registered concurrently.
## Multi-repository preflight
Kandev resolves repository selections in request order into an in-memory list.
It validates every plugin descriptor before it creates a task or repository
row. A failure discards the list and returns an error.
The service can resolve selections sequentially in the first implementation.
This avoids concurrent calls to the same plugin connection and keeps error
ordering deterministic. Repository database insertion continues through the
existing canonical identity lock after all external work succeeds.
This boundary prevents the issue's empty task and partially registered plugin
repository set. It does not make later blocker, branch-policy, attachment, or
database failures transactional. That broader create-atomicity work remains
separate.
## Failure contract
Inspection failures use typed categories instead of string matching:
| Failure | REST result | WebSocket result | User result |
| --- | --- | --- | --- |
| Invalid selection or descriptor | `400` | validation error | Correct the repository selection. |
| Provider or repository not found | `404` | not-found or validation error | Reconnect or select another repository. |
| Plugin inactive, timeout, rate limit, or upstream unavailable | `503` or typed retryable status | unavailable error | Retry after the provider is available. |
The response includes a stable error code for plugin repository resolution and
a bounded message. Logs can include workspace ID, provider ID, plugin ID,
action key, duration, and failure category. Logs and client responses exclude
secrets, authenticated URLs, plugin configuration, and raw response bodies.
Cancellation stops the action and returns without writes. A provider-specific
failure occurs before the task-created event and before task-create last-used
settings are recorded.
## Compatibility
- A non-empty workspace `repository_id` keeps the current authorized lookup.
- GitHub, GitLab, and Azure DevOps URLs keep the built-in parser.
- Plugin Host `Tasks.Create` keeps its authenticated trusted-descriptor path.
- REST, WebSocket, and MCP callers cannot set the internal trust marker.
- A provider without a valid workspace-scoped `repositories.inspect` action
cannot create a task from a first-use repository. Its already-persisted
repositories remain usable.
- Direct and nested repository action responses are accepted during the
compatibility period. Public documentation defines the nested form as the
preferred shape.
## Responsive behavior
The feature uses the existing shared task dialog and repository picker. It
adds no desktop-only control, compressed table, hover-only action, or new phone
navigation. The same submit error keeps the dialog open on both presentations.
Playwright must prove the complete first-use flow in a desktop project and a
phone project. The phone test also verifies that the repository and branch
controls remain reachable, the submit action has a touch-sized target, and the
dialog has no horizontal overflow.
## Observability
Structured logs record one inspection outcome with provider ID, plugin ID,
workspace ID, duration, response shape, and typed failure category. Success
logs do not include repository URLs. Existing task-created logs remain the
evidence that persistence followed a successful preflight.
No new metric is required for the first implementation. If operational data
shows repeated provider-specific failures, a later change can add bounded
outcome counters without changing this contract.
## Related decisions
- [Resolve First-Use Plugin Repositories on the Server](../../../decisions/2026-08-26-server-owned-plugin-repository-task-resolution.md)
- [Plugin Repository Provider Extensions](../../../decisions/2026-07-31-plugin-repository-provider-extensions.md)
- [Authenticated Plugin Actions](../../../decisions/2026-07-31-authenticated-plugin-actions.md)
- [Provider-Neutral Git Credential Broker](../../../decisions/2026-07-31-provider-neutral-git-credential-broker.md)
- [Code-Host Plugins Reuse Native Dashboard Primitives](../../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md)