89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# ADR: Global Installer Contract and Canonical Manifest (`installer.v1`)
|
|
|
|
- Date: 2026-03-03
|
|
- Status: Accepted
|
|
- Scope: `beadboard-05a.1.1` + `beadboard-05a.1.2`
|
|
|
|
## Context
|
|
|
|
The `beadboard-05a` epic requires one installer contract shared by all platform wrappers and launcher behavior.
|
|
Without a canonical schema, wrappers can drift and the driver skill can emit inconsistent remediation guidance.
|
|
|
|
Constraints:
|
|
|
|
- `bd` remains source of truth for work state.
|
|
- Driver skill must remain detect/remediate only, with no install side effects.
|
|
- Windows and POSIX wrappers must map to one shared semantic model.
|
|
|
|
## Decision
|
|
|
|
Adopt `installer.v1` as the canonical manifest contract and validate it centrally in code.
|
|
|
|
Contract requirements:
|
|
|
|
1. **Versioned schema**
|
|
- `version` must be exactly `installer.v1`.
|
|
|
|
2. **Distribution contract**
|
|
- `distribution.packageName` declares the global package identity.
|
|
- `distribution.shimNames` declares required command shims (`bb`, `beadboard`).
|
|
|
|
3. **Wrapper contract**
|
|
- `wrappers.windows.script` and `wrappers.posix.script` are required and explicit.
|
|
|
|
4. **Runtime command contract**
|
|
- `runtime.start`, `runtime.open`, and `runtime.status` are required.
|
|
|
|
5. **Driver boundary contract**
|
|
- `driver.remediationMode` must be `detect_only`.
|
|
- `driver.installSideEffects` must be `false`.
|
|
|
|
## Implementation
|
|
|
|
Added canonical validator and type contract:
|
|
|
|
- `src/lib/install-manifest.ts`
|
|
- `tests/lib/install-manifest.test.ts`
|
|
|
|
Exported artifacts:
|
|
|
|
- `INSTALLER_SCHEMA_VERSION = "installer.v1"`
|
|
- `validateInstallerManifest(input)`
|
|
- `canonicalInstallerManifest` for shared reference in downstream wrapper and launcher tasks
|
|
|
|
## Verification Evidence
|
|
|
|
TDD red:
|
|
|
|
- `node --import tsx --test tests/lib/install-manifest.test.ts`
|
|
failed with `Cannot find module '../../src/lib/install-manifest'`
|
|
|
|
TDD green:
|
|
|
|
- `node --import tsx --test tests/lib/install-manifest.test.ts`
|
|
passed (`4/4`)
|
|
|
|
Suite registration:
|
|
|
|
- `package.json` test script now explicitly includes `tests/lib/install-manifest.test.ts`
|
|
|
|
## Consequences
|
|
|
|
Positive:
|
|
|
|
- Platform wrappers now have one schema target.
|
|
- Launcher semantics are pre-declared before wrapper implementation.
|
|
- Driver detection-only boundary is encoded in validator rules.
|
|
|
|
Tradeoff:
|
|
|
|
- Wrapper and CI tasks (`05a.2+`) must now conform to `installer.v1`; they cannot introduce ad hoc fields.
|
|
|
|
## Runtime Manager Alignment
|
|
|
|
This ADR is paired with `docs/adr/2026-03-03-runtime-manager-global-install.md`.
|
|
|
|
- Canonical runtime home is `~/.beadboard/runtime/<version>`.
|
|
- Global install (`npm i -g beadboard`) is the primary operator path.
|
|
- Wrappers remain supported as fallback bootstraps.
|
|
- Legacy repo-bound shim migration is mandatory for backward compatibility.
|