Skip to content

developer-toolchains.md

Latest commit

 

History

History
160 lines (147 loc) · 8.75 KB

developer-toolchains.md

File metadata and controls

160 lines (147 loc) · 8.75 KB
Raw

Developer toolchains

Web toolchain pins

Tool Version
Node.js 24.18.1
pnpm 10.34.0
React 19.2.8
React DOM 19.2.8
TypeScript 6.0.3
Vite 8.2.1
Vitest 4.1.10
Testing Library React 16.3.2
Testing Library jest-dom 7.0.1
Playwright 1.62.1
Biome 2.3.2

Native toolchain pins

Tool Version
Rust toolchain 1.95.0
Tauri CLI 2.11.4
Tauri crate 2.11.2
tauri-build 2.6.2
serde 1.0.228

Deterministic local ports

  • Vite dev server: 127.0.0.1:4173
  • Vite preview server: 127.0.0.1:4174
  • Tauri dev URL: http://127.0.0.1:4173

Phase 1 boundary notes

  • The repository consumes exact vendored packed @opencoven/* artifacts from vendor/opencoven-sdk; production imports never resolve to SDK workspace source.
  • src/lib/desktop-host.ts is the only typed webview-to-host bridge and is limited to the non-secret app_identity and app_installation_id commands. The latter validates the canonical UUID v4 pairing identity returned from native secure storage.
  • src/lib/sdk/native-boundary.ts is the narrow SDK-managed Cave bridge. It accepts only opaque authority handles, bounded page options, canonical conversation IDs, and SDK-safe result snapshots. SDK operation contexts are reduced to an unpredictable, epoch/counter-bound single-use attempt ID plus a timeout of at most five seconds; aborts use the dedicated cave_cancel_operation command with only the attempt ID and the canonical aborted or timeout reason.
  • The same bounded operation and cancellation controls expose only the exact raw ordinary { status: "ok" } Coven health result. A dedicated native single-worker executor rejects overlapping health work with a retryable bounded diagnostic and releases capacity only after the synchronous producer call actually returns. Caller timeout or cancellation does not stop the OS call. Native production code consumes the producer-owned Rust coven-client at exact Coven revision 721437b84026c042e431b0882dcd14fdb29ac07d; it resolves explicit COVEN_HOME or the current account's real platform home plus .coven, then relies on that crate for live Unix connected-peer credentials or Windows named-pipe ownership and connected identity. Native trust unavailability fails closed, with no pathname-only, constructed-pipe, shell, PowerShell, lsof, or Node-private fallback.
  • Native credential mutations use one bounded worker reservation. Work cancelled while queued never acquires the keyring lock; once an irreversible mutation starts, concurrent retries fail with non-retryable credential_update_in_progress until the authoritative result is coherent.
  • Credential records use binary secret-store APIs and zeroizing transient buffers. Windows entries require Local persistence and migrate prior Enterprise values plus legacy UTF-16 password encoding; mutation locking uses a current-user-only Global\ mutex with verified ownership/DACL and the shipped session-local mutex during the compatibility window. Unix lock acquisition is owner-private and bounded.
  • Packed tarballs are verified by the cross-repository canary against the exact canonical release manifest, package paths, sizes, and digests in a temporary install copy rather than by a source-relative or absolute path dependency.
  • Run the local canary with pnpm test:contract-canary -- --sdk-root <sdk-root> --cave-root <cave-root>.
  • Run the packaged real-authority matrix through the trusted outer launcher: /bin/sh scripts/phase1-conformance-launcher.sh "$(command -v node)". Its independent phase1-conformance.lock.json pins Chat, the SDK package candidate, Cave, Coven, all four frozen SDK artifacts, and the SDK evidence authority; the harness creates exact clean detached clones rather than trusting source repositories' current branches.
  • CI reads contract-canary.lock.json, checks out those exact reviewed SDK and Cave revisions, rejects dirty SDK or Cave checkouts, and verifies the checked-out HEADs before the canary runs. The SDK lock targets canonical main commit 96804bc483a063e41e9a9738a4ace61970f6c0a4 and manifest digest 2001d754823ef9183e49c35db6f3a890913c8301460b34a0df236b8dccc6cb6a. The lock also pins the Cave producer's Client v1 contract fixture and hpke-bound-v1 vector digests; the current canary and frozen-consumer verifier require packed fixture and vector byte identity with the reviewed Cave checkout, in addition to proving the ancestry and exact historical bytes of the SDK's fixture provenance. Standalone historical-fixture validation retains support for authenticated older, different fixture bytes; it is not the current-candidate canary policy.
  • This adoption uses the fresh private SDK 0.0.1 candidate including the public Automations API. Only the Coven archive differs from candidate 77d825d; the other three archives are byte-identical. Previous candidate evidence remains historical. The new production consumer retains its reviewed native sources; the producer preserves the subsequently reviewed lifecycle and diagnostic changes. A validator freeze after reviewed producer landing is still required. Local packed-consumer verification is not accepted conformance evidence or publication authorization.
  • src-tauri/gen/schemas/desktop-schema.json is intentionally kept outside the ignore rules so the capability $schema can ship with fresh checkouts.
  • Tauri capabilities are limited to reviewed autogenerated allow-app-identity, allow-app-installation-id, and Cave adapter permissions for the main window.
  • No shell, filesystem, opener, or network plugin permissions are configured.
  • The feature-gated phase1-native-rpc binary is a headless conformance-only NDJSON bridge. It is excluded from default Cargo and Tauri builds. Unit scenarios default to in-memory custody, while the real-authority runner explicitly selects the production NativeKeyring, restarts the RPC process, and verifies credential reuse and deletion. Cave launch paths are accepted only through its two explicit OPENCOVEN_PHASE1_CONFORMANCE_NODE_PATH and OPENCOVEN_PHASE1_CONFORMANCE_CAVE_SERVER_PATH environment variables.
  • Run its subprocess integration gate with pnpm test:native-e2e; normal pnpm app:dev selects the opencoven-chat desktop binary by default.
  • Run the persisted Windows GNU cross-target compile gate with pnpm cargo:check:windows-gnu.
  • The legacy Phase 1 harness creates mode-0700 process-owned roots under the real OS temporary directory. Protected schema-v2 macOS/Linux lanes add a distinct ephemeral non-admin UID, isolated home/workspace/tool caches, cgroup-v2 teardown on Linux or exact-UID account/process teardown on macOS, and a no-follow descriptor handoff into one broker-owned mode-0600 artifact. The completed record is rescanned after handoff. See phase1-conformance.md.
  • Coven conformance starts the real locked daemon and invokes Chat phase1-native-rpc command coven_health; it never uses coven daemon status or reimplements producer-owned peer/pipe identity checks.

CI image proposal credential and retries

The weekly CI image workflow builds and verifies an image before proposing a new digest in .github/workflows/ci.yml. Configure repository Actions secret CI_IMAGE_BUMP_TOKEN with a fine-grained token restricted to OpenCoven/chat and Contents: write, Workflows: write, and Pull requests: write. The proposal job does not fall back to GITHUB_TOKEN: workflow-file updates require additional authorization, and the separate credential permits PR CI. See GitHub's Contents API permissions.

The token is consumed only by scripts/ci-image-proposal.mjs; checkout does not persist credentials. Do not paste a token into issues, logs, or source files. An absent credential fails before any API call.

Retries reconcile the digest branch, file update, and PR separately. A branch left behind after a failed write is repaired; a completed file update with no PR gets a proposal; an existing PR is reused. Closed proposals are not reopened. Unrelated workflow edits cause an explicit reconciliation failure. Contents updates include the observed blob SHA so conflicting file writes fail without creating a PR. API failures remain failures and can be retried after repair.

The image digest update remains subject to normal PR checks, including any required conformance authority rebind. Successful image build verification is not proof that the proposed repository changes pass CI or satisfy release gates. Tracked operational acceptance: Chat #149.