first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-06
|
||||
@@ -0,0 +1,61 @@
|
||||
## Context
|
||||
|
||||
The existing artifact transfer channel handles run-to-platform upload with chunk/resume semantics and platform-owned artifact metadata. Browser consumers need the opposite user-facing surface: list and download available artifacts from server/job/plugin contexts through platform authorization. The browser should receive safe references and platform routes, not raw storage locations.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Add platform artifact download metadata and content routes for authorized browser users and plugin bridge actions.
|
||||
- Support bounded chunk/range reads or download responses that can report progress in the frontend.
|
||||
- Enforce artifact owner scope, user/server access, plugin permissions, availability state, and response redaction.
|
||||
- Add frontend API client methods and UI controls for artifact download/open from operational pages.
|
||||
- Add plugin bridge artifact helpers that return safe references rather than raw paths or storage credentials.
|
||||
- Verify with tests and browser walkthrough.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- No external object storage backend or presigned raw storage URLs.
|
||||
- No browser direct access to run endpoints, host filesystem paths, sockets, or storage backend credentials.
|
||||
- No artifact upload from browser unless a future change explicitly adds it.
|
||||
- No archive extraction, malware scanning, lifecycle cleanup, billing, cloud host sales, or unrelated marketplace behavior.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Browser downloads go through platform routes
|
||||
|
||||
The platform exposes artifact content through authorized API routes. Any download URL or token is a platform route scoped to the requesting user/session and artifact, not a raw backend location.
|
||||
|
||||
Alternative considered: return storage adapter paths or presigned backend URLs. Rejected because no storage backend exists yet and raw locations can leak internals.
|
||||
|
||||
### Decision 2: Artifact availability is required for download
|
||||
|
||||
Only artifacts in an available/complete state can be downloaded by browser consumers. Uploading, failed, missing, or unauthorized artifacts return stable safe errors.
|
||||
|
||||
Alternative considered: stream partial uploading artifacts. Rejected because partial reads complicate integrity and user expectations.
|
||||
|
||||
### Decision 3: Plugin bridge receives artifact references, not bytes by default
|
||||
|
||||
Bridge actions can request artifact metadata/open/download references. Large byte transfer stays in platform/browser client code, preserving bounded payloads across plugin bridge messages.
|
||||
|
||||
Alternative considered: pass base64 artifact bytes through plugin page bridge messages. Rejected because large payloads can block UI and violate channel separation.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] In-memory artifact payload storage limits realistic download size. Mitigation: keep interfaces ready for storage adapters and test bounded content behavior.
|
||||
- [Risk] Browser downloads can expose sensitive server files if ownership checks are weak. Mitigation: validate artifact owner scope, user/server access, plugin permissions, and availability before content reads.
|
||||
- [Risk] Plugin pages may expect direct bytes. Mitigation: provide safe artifact references and frontend host download helpers.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Add platform artifact download contracts, validators, service methods, routes, and docs.
|
||||
2. Add frontend API client, UI controls, bridge host helpers, and tests.
|
||||
3. Add plugin SDK artifact reference helpers/tests if needed.
|
||||
4. Run browser walkthrough, structure check, and strict OpenSpec validation.
|
||||
|
||||
Rollback removes browser download routes/client integration and this change's artifacts before plugin pages depend on them.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Which durable artifact storage adapter should back downloads after in-memory transfer state is replaced?
|
||||
- Whether browser upload should be a separate future transfer direction.
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
Run can upload artifacts to the platform transfer channel, but operators and plugin pages still need a safe way to discover, download, and hand off artifact references in the browser. Artifact download must remain platform-mediated so browser code never receives raw storage backend credentials, raw host paths, or direct run sockets.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add platform artifact download/read APIs that authorize artifact access and stream or return bounded content through platform-owned routes.
|
||||
- Add browser-facing artifact metadata, download URL/token, chunk read, and transfer progress contracts without exposing storage internals.
|
||||
- Add frontend API client and UI behavior for artifact download from server/job/plugin contexts.
|
||||
- Integrate plugin bridge artifact actions with browser-safe artifact references.
|
||||
- Add platform and frontend tests plus browser walkthrough for download, access denial, resume/progress, and no-secret rendering.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `artifact-download-and-browser-transfer`: Browser-safe platform-mediated artifact discovery, download, and plugin bridge transfer references.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- Builds on `artifact-transfer-channel`, plugin bridge contracts, and server/job workflows without changing run upload semantics.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects `platform/` artifact DTOs, validators, services, APIs, and docs.
|
||||
- Affects `platform_web/` API contracts, artifact UI/download behavior, plugin bridge host integration, and tests.
|
||||
- May affect `plugins/` SDK artifact reference helpers/tests.
|
||||
- Does not add external object storage, presigned raw backend URLs, direct plugin-to-run access, billing, cloud host sales, or unrelated SaaS marketplace features.
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Browser artifact downloads are platform-mediated
|
||||
|
||||
The platform SHALL provide browser-safe artifact metadata and content download APIs that authorize access and do not expose storage backend credentials, raw host paths, or direct run sockets.
|
||||
|
||||
#### Scenario: Authorized artifact download starts
|
||||
- **WHEN** an authorized operator requests download metadata for an available artifact in an accessible server or job context
|
||||
- **THEN** the platform MUST return a browser-safe artifact reference or platform download route with filename, content type, size, checksum, and expiry metadata
|
||||
|
||||
#### Scenario: Unauthorized artifact download is denied
|
||||
- **WHEN** a user or plugin page requests an artifact outside its server, job, or plugin permission scope
|
||||
- **THEN** the platform MUST return a stable safe error and MUST NOT return artifact bytes or download references
|
||||
|
||||
### Requirement: Artifact content reads are bounded and integrity-aware
|
||||
|
||||
The platform SHALL validate artifact availability, requested range/chunk bounds, checksum metadata, and response size before returning artifact content to browser clients.
|
||||
|
||||
#### Scenario: Available artifact content is read
|
||||
- **WHEN** a browser client requests a valid byte range or full download for an available artifact
|
||||
- **THEN** the platform MUST return content with safe headers and integrity metadata
|
||||
|
||||
#### Scenario: Incomplete artifact cannot be downloaded
|
||||
- **WHEN** a browser client requests an uploading, failed, missing, or incomplete artifact
|
||||
- **THEN** the platform MUST reject the request and leave artifact state unchanged
|
||||
|
||||
### Requirement: Frontend exposes artifact download workflow
|
||||
|
||||
The frontend SHALL provide centralized API client methods and UI controls for artifact download/open flows from server, job, or plugin contexts.
|
||||
|
||||
#### Scenario: Operator downloads artifact
|
||||
- **WHEN** an operator clicks an artifact download/open action
|
||||
- **THEN** the page MUST request platform download metadata/content, show progress or completion state, and avoid raw path/credential display
|
||||
|
||||
#### Scenario: Download fails safely
|
||||
- **WHEN** an artifact download request fails validation, authorization, or availability checks
|
||||
- **THEN** the UI MUST show a safe error state without exposing backend paths, run sockets, storage credentials, or raw secrets
|
||||
|
||||
### Requirement: Plugin bridge uses artifact references safely
|
||||
|
||||
The plugin bridge SHALL expose artifact actions as safe metadata or download references rather than raw bytes, host paths, direct run endpoints, or storage backend credentials.
|
||||
|
||||
#### Scenario: Plugin page opens artifact reference
|
||||
- **WHEN** a plugin page requests an allowed artifact action
|
||||
- **THEN** the platform/host MUST return a scoped artifact reference that the browser host can download through platform APIs
|
||||
|
||||
#### Scenario: Plugin page lacks artifact permission
|
||||
- **WHEN** a plugin page requests artifact access without required manifest/page permission
|
||||
- **THEN** the platform MUST deny the request before returning metadata, bytes, or download references
|
||||
|
||||
### Requirement: Artifact download is verified end to end
|
||||
|
||||
The change SHALL include backend tests, frontend tests/build, plugin SDK tests if artifact bridge helpers are added, browser walkthrough evidence, structure validation, and strict OpenSpec validation.
|
||||
|
||||
#### Scenario: Verification commands pass
|
||||
- **WHEN** the change is complete
|
||||
- **THEN** platform tests, platform_web tests/typecheck/build, relevant plugin tests, `scripts/check-structure.sh`, and `openspec validate implement-artifact-download-and-browser-transfer --strict` MUST pass
|
||||
@@ -0,0 +1,46 @@
|
||||
## 1. Platform Artifact Download Contracts
|
||||
|
||||
- [x] 1.1 Add domain and DTO contracts for browser artifact metadata, download references, range/content requests, progress, and safe errors.
|
||||
- [x] 1.2 Add validators for artifact IDs, owner/user/plugin scope, availability state, range bounds, response size, checksum metadata, and unsafe secret/path/socket content.
|
||||
- [x] 1.3 Add service methods for authorized artifact metadata lookup, download reference creation, and bounded content reads.
|
||||
|
||||
## 2. Platform Artifact Download API
|
||||
|
||||
- [x] 2.1 Implement artifact metadata/download reference route using named DTOs and service methods.
|
||||
- [x] 2.2 Implement bounded artifact content/range route with safe headers and integrity metadata.
|
||||
- [x] 2.3 Integrate plugin bridge artifact actions with safe artifact references.
|
||||
- [x] 2.4 Update platform route/protocol documentation for browser artifact download and deferred storage backend behavior.
|
||||
- [x] 2.5 Add platform tests for successful download, range reads, unavailable artifacts, unauthorized scope, unsafe references, and no raw path/credential responses.
|
||||
|
||||
## 3. Frontend Browser Transfer
|
||||
|
||||
- [x] 3.1 Add centralized `platform_web/api` artifact download types and client methods.
|
||||
- [x] 3.2 Add UI controls/state for artifact download/open flows from relevant server/job/plugin contexts.
|
||||
- [x] 3.3 Add bridge host handling for artifact references and browser-mediated download actions.
|
||||
- [x] 3.4 Add frontend tests for progress/success/error states, unauthorized failures, and no raw secret/path rendering.
|
||||
|
||||
## 4. Plugin SDK Artifact Helpers
|
||||
|
||||
- [x] 4.1 Add or update plugin SDK helpers for artifact bridge request/reference parsing if bridge artifact actions need new helper types.
|
||||
- [x] 4.2 Add plugin tests for artifact reference helpers and forbidden direct run/storage access assumptions if helper code changes.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run `cd platform && go test ./...` and record evidence.
|
||||
- [x] 5.2 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
|
||||
- [x] 5.3 Run relevant plugin tests/typecheck if plugin SDK helpers changed and record evidence.
|
||||
- [x] 5.4 Run browser walkthrough for artifact download/browser transfer and record evidence.
|
||||
- [x] 5.5 Run `scripts/check-structure.sh` and record evidence.
|
||||
- [x] 5.6 Run `openspec validate implement-artifact-download-and-browser-transfer --strict` and record evidence.
|
||||
|
||||
## Evidence
|
||||
|
||||
- 1.1-2.5: `cd platform && go test ./api -run TestArtifactDownload` passed, covering browser-safe references, bounded content/range reads, unavailable artifact rejection, unauthorized scope denial, bridge `artifacts.open`, and forbidden fragment checks.
|
||||
- 3.1-3.4: `cd platform_web && npm run typecheck` passed. `cd platform_web && npm test -- --run api/client.test.ts utils/pluginBridgeHost.test.ts pages/ServerDetailPage.test.tsx` passed, covering artifact client methods, chunk metadata, bridge artifact reference parsing/rejection, and server detail artifact workflow source checks.
|
||||
- 4.1-4.2: `cd plugins && npm run typecheck` passed. `cd plugins && npm test` passed, covering `createArtifactOpenRequest`, `parseArtifactReference`, permission checks, and rejection of direct storage URL assumptions.
|
||||
- 5.1: `cd platform && go test ./...` passed.
|
||||
- 5.2: `cd platform_web && npm run typecheck` passed; `cd platform_web && npm test` passed; `cd platform_web && npm run build` passed.
|
||||
- 5.3: `cd plugins && npm run typecheck` passed; `cd plugins && npm test` passed.
|
||||
- 5.4: Browser walkthrough passed with a temporary local mock server and headless Chrome: opened server detail, selected `操作历史`, clicked artifact `打开`, observed `已打开 artifact-walk.bin`, and checked rendered text for forbidden path/token/storage fragments. Temporary walkthrough files were removed.
|
||||
- 5.5: `scripts/check-structure.sh` passed.
|
||||
- 5.6: `openspec validate implement-artifact-download-and-browser-transfer --strict` reported `Change 'implement-artifact-download-and-browser-transfer' is valid`. PostHog telemetry flush logged DNS errors afterward, but validation exited 0.
|
||||
Reference in New Issue
Block a user