commit 226d1b3295f4b705106444314c5ac061f7d66940
parent 3e124e14bff26c0a638f581e1e579c99a1b8233a
Author: triesap <tyson@radroots.org>
Date: Sun, 4 Oct 2026 05:47:14 +0000
build: bind the real web bootstrap to its local lock and commands (HCR-009)
- Delegate root web commands from the web-owned package directory
- Diagnose exact Node and pnpm inputs without downloading tooling
- Run frozen installation and all required real web check lanes
- Verify standalone command failures while preserving native behavior
Diffstat:
6 files changed, 266 insertions(+), 17 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,17 +14,19 @@ native signing and OS keyring orchestration belong in `core/`. Root Gradle and
native configuration retain their existing ownership. Keep generated UniFFI
bindings derived from the canonical Rust producer.
-The browser runtime is planned in `web/` with SvelteKit, strict TypeScript,
+The browser bootstrap exists in `web/` with SvelteKit, strict TypeScript,
static output, and web-owned package inputs. Its IndexedDB, sessions, explicit
extension signing, and Applesauce Nostr adapters are separate from native
-storage, custody, and FFI. No browser build or check lane exists yet. Follow
-`web/AGENTS.md` before implementing it; ordinary browser work must not depend
+storage, custody, and FFI. Use Node 24.21.0 and Corepack with pnpm 12.9.1,
+then `make web-doctor`, `make web-install`, `make web-check`, and
+`make web-build`; `make web-dev` starts the guarded Vite server. Follow
+`web/AGENTS.md`; ordinary browser work must not depend
on Cargo, Gradle, native binaries, or parent artifacts.
Shared public conformance vectors are planned under `contracts/interop/`.
They test the exact pinned Radroots semantics rather than establish new shared
-protocol policy. Browser and interop qualification remain pending real runners
-and assertions.
+protocol policy. Current static-shell conformance runs through `web-check`;
+Food/Message interop and real extension/relay qualification remain pending.
## Development flow
diff --git a/Makefile b/Makefile
@@ -19,6 +19,29 @@ endif
.PHONY: help doctor governed-doctor lock metadata build-logic-check build-logic-stability-check mode-check design-source-check design-goldens-update format format-fix lint test check governed-check build bindings api-check dev-check dev run audit licenses foundation-check package host-package-check governed-package-check source-check governed-source-check package-check integration-check governed-integration-check development-provenance-check development-check governed-development-check governed-linux-x86_64-development-check host-ui-lifecycle-check acceptance-check unsigned-release-check _unsigned-release-check signing-check _signing-check notarization-check _notarization-check release-check _release-check clean
.PHONY: native-doctor native-dev native-check native-build native-package-check
+.PHONY: web-doctor web-install web-dev web-check web-build
+
+web-doctor:
+ cd web && $(BUILD_RUNNER) node tools/doctor.mjs
+
+ifeq ($(BUILD_MODE),governed)
+web-doctor: governed-doctor
+endif
+
+web-install: web-doctor
+ cd web && $(BUILD_RUNNER) corepack pnpm install --frozen-lockfile
+
+web-dev: web-doctor
+ cd web && $(BUILD_RUNNER) corepack pnpm run dev
+
+web-check: web-doctor
+ cd web && $(BUILD_RUNNER) corepack pnpm run check
+ cd web && $(BUILD_RUNNER) corepack pnpm run lint
+ cd web && $(BUILD_RUNNER) corepack pnpm run test:unit
+ cd web && $(BUILD_RUNNER) corepack pnpm run test:conformance
+
+web-build: web-doctor
+ cd web && $(BUILD_RUNNER) corepack pnpm run build
native-doctor: doctor
native-dev: dev
@@ -27,6 +50,7 @@ native-build: build
native-package-check: package-check
help:
+ @printf '%s\n' 'Unqualified targets below retain native meaning.' 'Browser: web-doctor web-install web-dev web-check web-build'
@printf '%s\n' doctor governed-doctor lock metadata build-logic-check build-logic-stability-check mode-check design-source-check design-goldens-update format format-fix lint test check governed-check build bindings api-check dev-check dev run audit licenses foundation-check package host-package-check governed-package-check source-check governed-source-check package-check integration-check governed-integration-check development-check governed-development-check governed-linux-x86_64-development-check host-ui-lifecycle-check acceptance-check unsigned-release-check signing-check notarization-check release-check clean
design-source-check: doctor
diff --git a/README.md b/README.md
@@ -25,11 +25,10 @@ The MVP is designed to work without a managed HarvestCircle account or API.
Future work adds canonical Radroots collective-market contracts, private buyer
commitments, a selectable open reference authority, pickup, and proof.
-## Planned browser prototype
+## Browser prototype bootstrap
-An isolated browser prototype is planned under `web/`, using SvelteKit,
-strict TypeScript, and static output. The prototype is not implemented and
-has no browser build or run commands yet. It will use separate browser
+The isolated bootstrap under `web/` uses SvelteKit, strict TypeScript, and
+static output. Product controllers remain planned. It will use separate browser
IndexedDB storage and sessions, explicit extension identity and signing without
raw private-key custody, and Applesauce for generic Nostr behavior. Shared Radroots contracts must conform to the
exact pinned public Rust oracle without requiring native binaries or the
@@ -44,12 +43,22 @@ paused. See `web/AGENTS.md` for the browser source boundary.
Run commands from the standalone HarvestCircle repository root.
-| | Native desktop (implemented) | Browser (planned) |
+| | Native desktop (implemented) | Browser bootstrap |
|---|---|---|
| Source | Kotlin/Compose in `app/`, product Rust in `core/`, root Gradle inputs | SvelteKit with strict TypeScript and static output in `web/` |
| State and custody | SQLx service database, OS keyring, generated UniFFI boundary | Separate IndexedDB and sessions; explicit extension identity/signing without raw private-key custody |
-| Start | `make native-doctor`, then `make native-dev` | Read `web/AGENTS.md`; no browser install, run, build, or check commands are implemented yet |
-| Check/build | `make native-check`, `make native-build` | Working standalone commands will be documented after implementation and verification |
+| Start | `make native-doctor`, then `make native-dev` | `make web-doctor`, `make web-install`, then `make web-dev` |
+| Check/build | `make native-check`, `make native-build` | `make web-check`, `make web-build` |
+
+Browser commands require Node 24.21.0, Corepack with pnpm 12.9.1 available,
+Make, Git for build provenance, and standard Unix shell/`mkfifo` utilities for
+the provenance tests. The doctor checks exact selected versions
+without downloading tooling; install uses the frozen web lock. Check runs the
+actual type/Svelte, lint/style/import, unit/provenance, and static-conformance
+assertions. It requires no Rust, Java, Gradle, or browser installation.
+Controlled browser tests remain separate web package scripts requiring a
+qualified Playwright browser. Browser commands use the web directory before
+Corepack resolves its package manager; no root JavaScript workspace is added.
Native prerequisites include JDK 21, Rust 1.97.1, and platform packaging tools.
Node is not a native prerequisite. The `native-*` targets are recipe-free
@@ -101,8 +110,9 @@ authority. Listing a target does not authorize its deferred effects.
Planned public test vectors under `contracts/interop/` will compare browser
Radroots adapters with the exact pinned public Rust oracle. Ordinary browser
conformance will use checked vectors without invoking native tools; explicit
-interop qualification will execute both real consumers. These browser and
-interop lanes are not implemented or qualified yet.
+interop qualification will execute both real consumers. Food/Message interop
+remains unimplemented; the current Node-only conformance script checks the
+actual bootstrap static output.
The native artifact contract v3 requires an exact clean Git-revision tree
source archive, including newly tracked `web/` files. A native-only filtered
diff --git a/web/package.json b/web/package.json
@@ -10,13 +10,14 @@
"pnpm": "12.9.1"
},
"scripts": {
+ "dev": "node tools/check-source.mjs && vite",
"build": "node tools/check-source.mjs && node tools/build-info.mjs && vite build",
"check": "node tools/check-source.mjs && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --fail-on-warnings",
"lint": "node tools/check-source.mjs && svelte-kit sync && eslint . --max-warnings 0 && prettier --check .",
"test:unit": "node tools/check-source.mjs && svelte-kit sync && vitest run --config vitest.config.ts && node --test --test-timeout=10000 tests/provenance/*.test.mjs",
- "test:conformance": "pnpm build && node --test tests/conformance/*.test.ts",
- "test:integration": "pnpm build && node --test --test-timeout=10000 tests/integration/*.test.ts",
- "test:e2e": "pnpm build && playwright test"
+ "test:conformance": "corepack pnpm build && node --test tests/conformance/*.test.ts",
+ "test:integration": "corepack pnpm build && node --test --test-timeout=10000 tests/integration/*.test.ts",
+ "test:e2e": "corepack pnpm build && playwright test"
},
"devDependencies": {
"@eslint/js": "10.0.1",
diff --git a/web/tests/provenance/commands.test.mjs b/web/tests/provenance/commands.test.mjs
@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import {
+ mkdtemp,
+ mkdir,
+ readFile,
+ writeFile,
+ rm,
+ symlink
+} from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+
+/** @param {import('node:test').TestContext} t */
+async function fixture(t) {
+ const root = await mkdtemp(path.join(os.tmpdir(), 'hc web commands '));
+ t.after(() => rm(root, { recursive: true, force: true }));
+ await mkdir(path.join(root, 'web/tools'), { recursive: true });
+ await mkdir(path.join(root, 'bin'));
+ for (const [source, target] of [
+ ['../../../Makefile', 'Makefile'],
+ ['../../package.json', 'web/package.json'],
+ ['../../.node-version', 'web/.node-version'],
+ ['../../tools/doctor.mjs', 'web/tools/doctor.mjs']
+ ])
+ await writeFile(
+ path.join(root, target),
+ await readFile(new URL(source, import.meta.url))
+ );
+ await symlink(process.execPath, path.join(root, 'bin/node'));
+ const log = path.join(root, 'calls.jsonl');
+ await writeFile(
+ path.join(root, 'bin/corepack'),
+ `#!${process.execPath}
+import { appendFileSync } from 'node:fs';
+appendFileSync(process.env.HC_COMMAND_LOG, JSON.stringify({ cwd: process.cwd(), args: process.argv.slice(2), network: process.env.COREPACK_ENABLE_NETWORK }) + '\\n');
+if (process.argv.includes('--version')) console.log(process.env.HC_PNPM_VERSION ?? '12.9.1');
+else if (process.argv.includes(process.env.HC_FAIL_COMMAND)) process.exit(37);
+`,
+ { mode: 0o755 }
+ );
+ const env = {
+ ...process.env,
+ PATH: path.join(root, 'bin'),
+ HC_COMMAND_LOG: log
+ };
+ /** @param {string} target @param {Record<string, string>} [extra] */
+ const run = (target, extra = {}) =>
+ spawnSync('/usr/bin/make', ['--no-print-directory', target], {
+ cwd: root,
+ env: { ...env, ...extra },
+ encoding: 'utf8',
+ timeout: 10000
+ });
+ const calls = async () =>
+ (await readFile(log, 'utf8'))
+ .trim()
+ .split('\n')
+ .map((line) => JSON.parse(line));
+ return { root, run, calls };
+}
+
+await test('standalone web targets select web cwd and run every required lane without native tools', async (t) => {
+ const { root, run, calls } = await fixture(t);
+ for (const target of [
+ 'web-doctor',
+ 'web-install',
+ 'web-check',
+ 'web-build',
+ 'web-dev'
+ ]) {
+ const result = run(target);
+ assert.equal(result.status, 0, result.stderr);
+ }
+ const actual = await calls();
+ assert.ok(actual.every((call) => call.cwd === path.join(root, 'web')));
+ assert.ok(
+ actual
+ .filter((call) => call.args.includes('--version'))
+ .every((call) => call.network === '0')
+ );
+ assert.deepEqual(
+ actual
+ .filter((call) => !call.args.includes('--version'))
+ .map((call) => call.args),
+ [
+ ['pnpm', 'install', '--frozen-lockfile'],
+ ['pnpm', 'run', 'check'],
+ ['pnpm', 'run', 'lint'],
+ ['pnpm', 'run', 'test:unit'],
+ ['pnpm', 'run', 'test:conformance'],
+ ['pnpm', 'run', 'build'],
+ ['pnpm', 'run', 'dev']
+ ]
+ );
+});
+
+await test('doctor rejects a mismatched selected manager before installation', async (t) => {
+ const { run, calls } = await fixture(t);
+ const result = run('web-install', { HC_PNPM_VERSION: '10.25.0' });
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /Expected pnpm 12\.9\.1; selected 10\.25\.0/);
+ assert.equal((await calls()).length, 1);
+});
+
+await test('web check propagates failing commands and stops subsequent lanes', async (t) => {
+ const { run, calls } = await fixture(t);
+ const result = run('web-check', { HC_FAIL_COMMAND: 'lint' });
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /Error 37/);
+ assert.deepEqual(
+ (await calls()).map((call) => call.args),
+ [
+ ['pnpm', '--version'],
+ ['pnpm', 'run', 'check'],
+ ['pnpm', 'run', 'lint']
+ ]
+ );
+});
+
+await test('missing web tooling fails without trying native tools', async (t) => {
+ const { root, run } = await fixture(t);
+ await rm(path.join(root, 'bin/corepack'));
+ const result = run('web-build');
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /ENOENT/);
+});
+
+await test('doctor rejects mismatched toolchain authorities', async (t) => {
+ const { root, run } = await fixture(t);
+ await writeFile(path.join(root, 'web/.node-version'), '24.20.0\n');
+ const result = run('web-doctor');
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /Web toolchain pins disagree or are not exact/);
+});
+
+await test('doctor rejects wrong selected Node before invoking Corepack', async (t) => {
+ const { root, run } = await fixture(t);
+ const file = path.join(root, 'web/package.json');
+ const inputs = JSON.parse(await readFile(file, 'utf8'));
+ inputs.engines.node = '24.20.0';
+ await writeFile(file, JSON.stringify(inputs));
+ await writeFile(path.join(root, 'web/.node-version'), '24.20.0\n');
+ const result = run('web-doctor');
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /Expected Node 24\.20\.0; selected 24\.21\.0/);
+});
diff --git a/web/tools/doctor.mjs b/web/tools/doctor.mjs
@@ -0,0 +1,64 @@
+import { execFileSync } from 'node:child_process';
+import { constants, openSync, fstatSync, readSync, closeSync } from 'node:fs';
+
+/** @param {URL} file */
+function readToolInput(file) {
+ const fd = openSync(
+ file,
+ constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK
+ );
+ try {
+ const stat = fstatSync(fd);
+ if (!stat.isFile() || stat.size > 64 * 1024)
+ throw new Error('Unsafe web toolchain input');
+ const buffer = Buffer.alloc(64 * 1024 + 1);
+ let size = 0;
+ while (size < buffer.length) {
+ const count = readSync(fd, buffer, size, buffer.length - size, null);
+ if (!count) break;
+ size += count;
+ }
+ if (size > 64 * 1024) throw new Error('Oversized web toolchain input');
+ return new TextDecoder('utf-8', { fatal: true }).decode(
+ buffer.subarray(0, size)
+ );
+ } finally {
+ closeSync(fd);
+ }
+}
+
+const inputs = JSON.parse(
+ readToolInput(new URL('../package.json', import.meta.url))
+);
+const nodeVersion = inputs.engines?.node;
+const pnpmVersion = inputs.engines?.pnpm;
+if (
+ typeof nodeVersion !== 'string' ||
+ typeof pnpmVersion !== 'string' ||
+ !/^\d+\.\d+\.\d+$/.test(nodeVersion) ||
+ !/^\d+\.\d+\.\d+$/.test(pnpmVersion) ||
+ inputs.packageManager !== `pnpm@${pnpmVersion}` ||
+ readToolInput(new URL('../.node-version', import.meta.url)).trim() !==
+ nodeVersion
+)
+ throw new Error('Web toolchain pins disagree or are not exact');
+
+if (process.versions.node !== nodeVersion)
+ throw new Error(
+ `Expected Node ${nodeVersion}; selected ${process.versions.node}`
+ );
+
+// Diagnosis must not install a missing package manager or fetch its tooling.
+const selectedPnpm = execFileSync('corepack', ['pnpm', '--version'], {
+ cwd: process.cwd(),
+ env: { ...process.env, COREPACK_ENABLE_NETWORK: '0' },
+ encoding: 'utf8',
+ timeout: 10000,
+ maxBuffer: 64 * 1024,
+ stdio: ['ignore', 'pipe', 'pipe']
+}).trim();
+if (selectedPnpm !== pnpmVersion)
+ throw new Error(`Expected pnpm ${pnpmVersion}; selected ${selectedPnpm}`);
+console.log(
+ `HarvestCircle web tools: Node ${nodeVersion}, pnpm ${pnpmVersion}`
+);