67 lines
6.6 KiB
Markdown
67 lines
6.6 KiB
Markdown
## Context
|
|
|
|
There are two local run checkouts: `/Users/tasia/Desktop/code/browser/run` and `/Users/tasia/Desktop/code/run`. Both point at `git.npc0.com:admin343/run.git`, but neither should be treated as the final generated runtime artifact. The current-directory checkout is an ignored editable source input for convenience and project-size control. Local debug must copy or upload that source into an ignored closed build bucket before any build-capable worker uses it. The sibling checkout has unrelated dirty changes and should not be required by this workflow.
|
|
|
|
Platform already queues `distribution.build` jobs and exposes safe browser download routes only after the build artifact is available. The run worker already has a real build path that fetches secret-bearing build input through a leased job channel, copies an approved build source, builds a target executable, packages it with config, uploads it through the artifact channel, and returns `artifact://<id>` as the terminal job result. This change closes the remaining gaps around source snapshotting, closed build bucket scoping, local smoke proof, and concurrency evidence.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Make local debug use the run checkout under this repository root as editable source input only.
|
|
- Snapshot that source into an ignored closed build bucket before the bootstrap worker starts or any generated run distribution is built.
|
|
- Build and start the local bootstrap worker from the bucket snapshot instead of `go run`-ing `browser/run` directly.
|
|
- Keep run as a separate Git repository and keep browser from tracking run source files.
|
|
- Build run packages in plugin/job-scoped isolated directories below the closed bucket so multiple servers for the same plugin cannot overwrite each other's source, config, archive, upload, or result.
|
|
- Prove download works after build completion by opening the latest run distribution reference and reading artifact content chunks.
|
|
- Report the exact configuration surface needed to run and verify the flow.
|
|
|
|
**Non-Goals:**
|
|
- Do not move run source into browser's tracked source tree.
|
|
- Do not delete or mutate `/Users/tasia/Desktop/code/run`; only stop using it as the default local debug target.
|
|
- Do not add arbitrary shell execution, cloud hosting, billing, SaaS marketplace flows, plugin raw credentials, or direct sockets.
|
|
- Do not implement production signing/KMS or rollout rings.
|
|
- Do not require a live Windows host for local acceptance; local smoke can cross-compile Windows packages and verify the artifact archive.
|
|
|
|
## Decisions
|
|
|
|
### Decision 1: Local debug separates editable source from build buckets
|
|
|
|
`scripts/local-debug-env.sh` will introduce `RUN_SOURCE_DIR` as the editable source checkout, defaulting to `$LOCAL_DEBUG_ROOT_DIR/run`. The legacy `RUN_REPO_DIR` environment variable remains an alias for source selection for compatibility, but it is not the build or execution artifact path.
|
|
|
|
The scripts will snapshot `RUN_SOURCE_DIR` into `RUN_BUILD_SOURCE_ROOT`, defaulting under `$LOCAL_DEBUG_ROOT/run/build-buckets/source/current`. Local debug will build `RUN_BOOTSTRAP_BIN` from that snapshot, then start the bootstrap worker binary. Platform-dispatched `distribution.build` jobs will copy from the bucket snapshot into plugin/job workspaces, never from the editable checkout.
|
|
|
|
Alternative considered: set `RUN_BUILD_SOURCE_ROOT=$RUN_SOURCE_DIR` and run from `browser/run`. Rejected because it conflates source input with build/runtime artifacts and allows the editable tree to become the effective execution directory.
|
|
|
|
### Decision 2: Build workspaces are plugin/job-scoped
|
|
|
|
The run worker will create distribution build workspaces under `RUN_WORKSPACE_ROOT/distribution-builds/<pluginId>/<jobId>`. The plugin dimension keeps same-plugin build queues inspectable and ready for per-plugin scheduling, while the job dimension prevents two servers or two idempotency keys from sharing mutable files. Artifact IDs and build job IDs remain Platform-derived and server-scoped.
|
|
|
|
Alternative considered: one directory per server. Rejected because multiple builds for the same plugin should queue and isolate by job, not mutate a long-lived per-server build tree.
|
|
|
|
### Decision 3: Download proof is mandatory after build success
|
|
|
|
Local smoke should keep the existing action availability check, but when `generate-run` is available it must generate a run package, wait for the build job to succeed, open `/run/download`, read content chunks, verify size/checksum metadata, and reject forbidden fragments. A build-capable run endpoint that cannot produce a downloadable artifact is a failing smoke.
|
|
|
|
### Decision 4: `/Users/tasia/Desktop/code/run` remains optional
|
|
|
|
The sibling checkout is not required for this workflow once local debug snapshots from `browser/run` by default. It can remain for manual comparison or be removed by the user later, but this change will not delete it, mutate it, or depend on it.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] Running `go mod download` during local smoke may need network if caches are cold. Mitigation: tests exercise build logic without network where possible; full smoke may require pre-cached modules or an approved network-capable environment.
|
|
- [Risk] `RUN_MAX_JOBS>1` does not by itself make the current worker execute multiple jobs at once if its main loop is synchronous. Mitigation: workspace isolation is still required and tested directly; worker parallelism can remain a future scheduler improvement.
|
|
- [Risk] Cross-compiling Windows packages on macOS validates packaging but not Windows service activation. Mitigation: local acceptance checks archive content and platform artifact flow; OS-native activation remains a target-environment proof.
|
|
- [Risk] Two run checkouts can confuse operators. Mitigation: local debug prints the editable source, bucket snapshot, bootstrap binary, and final handoff documents the optional sibling checkout clearly.
|
|
|
|
## Migration Plan
|
|
|
|
1. Update local debug defaults to snapshot `browser/run` into `.local-debug` and pass the snapshot as `RUN_BUILD_SOURCE_ROOT`.
|
|
2. Harden run distribution build workspace naming and add concurrency/isolation tests in the run checkout.
|
|
3. Extend local smoke to download and checksum the generated run artifact.
|
|
4. Run OpenSpec validation, structure checks, focused Platform tests, focused run tests, and smoke/script syntax checks.
|
|
5. Rollback by pointing `RUN_SOURCE_DIR`/`RUN_REPO_DIR` at another checkout and disabling the new smoke assertions; generated artifacts remain ordinary platform artifacts.
|
|
|
|
## Open Questions
|
|
|
|
- Whether to keep `/Users/tasia/Desktop/code/run` as a personal scratch checkout is an operator workspace decision; it is not required by local debug after this change.
|