Add worker reference package sync tooling

Author: ottenhoff

README.md

@@ -219,9 +219,17 @@ runtime launch later verifies. On Workers, Lantern uses that reviewed identity
 to key the Dynamic Worker envelope, so the same approved package bytes can be
 reused across sessions without turning reviewed packages into arbitrary
 server-side apps. The Worker app path no longer depends on local disk for demo
-package import or reviewed runtime delivery. The remaining deployment work is
-operational: provision the curated reference package source files into
-`PACKAGE_ARTIFACTS` as part of your Cloudflare bootstrap or release flow.
+package import or reviewed runtime delivery. Provision the curated reference
+package source files into `PACKAGE_ARTIFACTS` during Cloudflare bootstrap or
+release with:
+
+```sh
+deno task reference:sync --bucket=replace-with-package-artifact-bucket
+```
+
+This command shells out to Wrangler's `r2 object put` flow. Authenticate with
+Wrangler first or provide a Cloudflare API token in the environment you use for
+the command.
 
 For local Worker development, Wrangler now builds a single generated Worker
 artifact through `deno task build:worker` before `dev` or `deploy`. The repo
@@ -246,9 +254,11 @@ To run the Worker locally:
 - when using `wrangler dev --local`, make sure that local Hyperdrive connection
   string includes a password segment because Miniflare rejects passwordless DSNs
   even if your local Postgres allows them
-- if you want the demo import path to work on Workers, seed
-  `PACKAGE_ARTIFACTS/reference-packages/<app-id>/source/...` in your local or
-  remote R2 bucket before calling `/admin/packages/import-reference`
+- if you want the demo import path to work on Workers, provision the curated
+  reference sources into the same bucket first with
+  `deno task reference:sync --bucket=<bucket-name>` or
+  `deno task reference:sync --bucket=<bucket-name> --local --persist-to=<dir>`
+  before calling `/admin/packages/import-reference`
 - then run `npx wrangler dev --local`
 
 The reviewed runtime contract remains the same across local Deno preview and the
@@ -344,6 +354,7 @@ Common commands:
 - `deno task app:validate <package-root>`
 - `deno task app:test-preview <package-root>`
 - `deno task app:preview <package-root>`
+- `deno task reference:sync --bucket=<bucket-name>`
 - `deno task fmt`
 - `deno task fmt:check`
 - `deno task lint`

deno.json

@@ -8,14 +8,15 @@
     "app:dev": "deno run --allow-read --allow-net tools/app_dev.ts",
     "app:test-preview": "deno run --allow-read --allow-net tools/app_test_preview.ts",
     "app:new": "deno run --allow-read --allow-write tools/app_new.ts",
+    "reference:sync": "deno run --allow-read --allow-run tools/reference_sync.ts",
     "local:init": "deno run --allow-read --allow-write tools/local_init.ts",
     "local:migrate": "deno run --env-file=.env.local --allow-read --allow-env --allow-net src/db/migrate.ts",
     "local:seed": "deno run --env-file=.env.local --allow-read --allow-write --allow-env --allow-net tools/local_seed.ts",
     "local:bootstrap": "deno task local:seed",
     "local:start": "deno run --env-file=.env.local --allow-read --allow-write --allow-env --allow-net main.ts",
     "local:dev": "deno run --env-file=.env.local --watch --allow-read --allow-write --allow-env --allow-net main.ts",
     "build:worker": "deno bundle --platform=browser src/worker.ts -o output/worker.bundle.mjs",
-    "check:worker": "deno task build:worker && deno run --allow-read tools/check_worker_bundle.ts",
+    "check:worker": "deno task build:worker && deno run --allow-read tools/check_worker_bundle.ts && deno run --allow-read tools/check_worker_config.ts",
     "fmt": "deno run -A npm:oxfmt@0.43.0 --write .",
     "fmt:check": "deno run -A npm:oxfmt@0.43.0 --check .",
     "lint": "deno run -A npm:oxlint@1.58.0",

src/app_worker_services.ts

@@ -6,6 +6,7 @@ import { createHyperdriveDatabasePool, type HyperdriveBinding } from './db/pool.
 import { createOpsRepository, type OpsRepository } from './ops/repository.ts';
 import type { EnvReader } from './platform/env.ts';
 import {
+  getReferencePackageBucketSourceRoot,
   importPackage,
   isReferencePackageId,
   loadPackageSnapshot,
@@ -39,7 +40,7 @@ const WORKER_RUNTIME_ARTIFACT_MESSAGE =
 const WORKER_EVIDENCE_ARTIFACT_MESSAGE =
   'Cloudflare Workers evidence artifact storage requires an R2 binding named PACKAGE_ARTIFACTS with write access. Bind the reviewed package artifact bucket before accepting anonymous evidence uploads on Workers.';
 const WORKER_REFERENCE_PACKAGE_MESSAGE =
-  'Curated reference packages must be stored in PACKAGE_ARTIFACTS under reference-packages/<app-id>/source before Workers can import or inspect them.';
+  'Curated reference packages must be stored in PACKAGE_ARTIFACTS under reference-packages/<app-id>/source before Workers can import or inspect them. Run `deno task reference:sync --bucket=<bucket-name>` during Worker bootstrap or release.';
 const WORKER_RUNTIME_DELIVERY_MESSAGE =
   'Cloudflare Workers reviewed runtime delivery requires a Worker Loader binding named LOADER. Bind the Dynamic Worker loader before serving immutable reviewed runtime bytes from Workers.';
 const WORKER_AUTHORING_REFERENCE_MESSAGE =
@@ -161,7 +162,7 @@ function resolveWorkerReferencePackageSource(
   const bucket = bindings.PACKAGE_ARTIFACTS;
 
   if (isRuntimeArtifactBucket(bucket) && typeof bucket.list === 'function') {
-    return createBucketPackageSource(bucket, `reference-packages/${appId}/source`);
+    return createBucketPackageSource(bucket, getReferencePackageBucketSourceRoot(appId));
   }
 
   return createUnsupportedPackageSource(WORKER_REFERENCE_PACKAGE_MESSAGE);

src/app_worker_services_test.ts

@@ -1,6 +1,7 @@
 import { assertEquals, assertRejects } from '@std/assert';
 import { resolveWorkerServices } from './app_worker_services.ts';
 import { createObjectEnvReader } from './platform/env.ts';
+import { getReferencePackageBucketSourceRoot } from './package_review/intake.ts';
 import { createMemoryPackageSource } from './package_review/package_source.ts';
 import { verifyReviewedRuntimeContractSignature } from './package_review/runtime_contract.ts';
 import type { RuntimeArtifactBucket } from './runtime/artifact_store.ts';
@@ -10,7 +11,7 @@ import {
   buildRuntimeSessionRecord,
 } from './test_helpers/package_review.ts';
 
-const DEMO_BUCKET_SOURCE_ROOT = 'reference-packages/chapter-4-asteroids/source';
+const DEMO_BUCKET_SOURCE_ROOT = getReferencePackageBucketSourceRoot('chapter-4-asteroids');
 const DEMO_SNAPSHOT_ROOT = 'var/packages/chapter-4-asteroids/0.1.0';
 const DEMO_REFERENCE_SOURCE_FILES = {
   'manifest.json': `{

src/package_review/intake.ts

@@ -13,6 +13,7 @@ export const REFERENCE_PACKAGE_SOURCE_ROOTS = {
   'web-checkup': 'examples/apps/web-checkup',
   'typescript-ladder-game': 'examples/apps/typescript-ladder-game',
 } as const;
+export const REFERENCE_PACKAGE_BUCKET_ROOT = 'reference-packages';
 
 export type ReferencePackageId = keyof typeof REFERENCE_PACKAGE_SOURCE_ROOTS;
 
@@ -57,6 +58,12 @@ export function getReferencePackageSourceRoot(appId: string): string {
   return REFERENCE_PACKAGE_SOURCE_ROOTS[appId];
 }
 
+export function getReferencePackageBucketSourceRoot(appId: string): string {
+  assertReferencePackageId(appId);
+
+  return joinPath(REFERENCE_PACKAGE_BUCKET_ROOT, appId, 'source');
+}
+
 export async function readReferencePackageReviewData(
   appId: string,
   source: PackageSource,

src/package_review/intake_test.ts

@@ -1,6 +1,7 @@
 import { assert, assertEquals, assertRejects, assertThrows } from '@std/assert';
 import { getTestToolPrivateJwkEnvValue } from '../test_helpers/lti.ts';
 import {
+  getReferencePackageBucketSourceRoot,
   getReferencePackageSourceRoot,
   importDemoPackage,
   importPackage,
@@ -214,13 +215,25 @@ Deno.test('curated authoring examples stay explicitly registered in the referenc
 
   assertEquals(ids.includes('template-app'), true);
   assertEquals(getReferencePackageSourceRoot('template-app'), 'examples/apps/template');
+  assertEquals(
+    getReferencePackageBucketSourceRoot('template-app'),
+    'reference-packages/template-app/source',
+  );
   assertEquals(ids.includes('web-checkup'), true);
   assertEquals(getReferencePackageSourceRoot('web-checkup'), 'examples/apps/web-checkup');
+  assertEquals(
+    getReferencePackageBucketSourceRoot('web-checkup'),
+    'reference-packages/web-checkup/source',
+  );
   assertEquals(ids.includes('typescript-ladder-game'), true);
   assertEquals(
     getReferencePackageSourceRoot('typescript-ladder-game'),
     'examples/apps/typescript-ladder-game',
   );
+  assertEquals(
+    getReferencePackageBucketSourceRoot('typescript-ladder-game'),
+    'reference-packages/typescript-ladder-game/source',
+  );
 });
 
 Deno.test('importReferencePackage snapshots web-checkup through the explicit curated registry', async () => {

tools/check_worker_config.ts

@@ -0,0 +1,30 @@
+export function validateWorkerConfigBindings(configText: string): string[] {
+  return REQUIRED_BINDINGS.filter(({ pattern }) => !pattern.test(configText)).map(
+    ({ description }) => description,
+  );
+}
+
+const REQUIRED_BINDINGS = [
+  {
+    description: 'worker_loaders binding LOADER',
+    pattern: /"worker_loaders"\s*:\s*\[[\s\S]*?"binding"\s*:\s*"LOADER"/,
+  },
+  {
+    description: 'r2_buckets binding PACKAGE_ARTIFACTS',
+    pattern: /"r2_buckets"\s*:\s*\[[\s\S]*?"binding"\s*:\s*"PACKAGE_ARTIFACTS"/,
+  },
+] as const;
+
+if (import.meta.main) {
+  const configPath = new URL('../wrangler.jsonc', import.meta.url);
+  const configText = await Deno.readTextFile(configPath);
+  const failures = validateWorkerConfigBindings(configText);
+
+  if (failures.length > 0) {
+    throw new Error(
+      `wrangler.jsonc is missing required Worker bindings:\n${failures.map((failure) => `- ${failure}`).join('\n')}`,
+    );
+  }
+
+  console.log('Worker config keeps LOADER and PACKAGE_ARTIFACTS bindings wired.');
+}

tools/check_worker_config_test.ts

@@ -0,0 +1,31 @@
+import { assertEquals } from '@std/assert';
+import { validateWorkerConfigBindings } from './check_worker_config.ts';
+
+Deno.test('validateWorkerConfigBindings accepts wrangler config with LOADER and PACKAGE_ARTIFACTS', () => {
+  const config = `{
+    "worker_loaders": [
+      {
+        "binding": "LOADER"
+      }
+    ],
+    "r2_buckets": [
+      {
+        "binding": "PACKAGE_ARTIFACTS"
+      }
+    ]
+  }`;
+
+  assertEquals(validateWorkerConfigBindings(config), []);
+});
+
+Deno.test('validateWorkerConfigBindings reports missing required Worker bindings', () => {
+  const config = `{
+    "worker_loaders": [],
+    "r2_buckets": []
+  }`;
+
+  assertEquals(validateWorkerConfigBindings(config), [
+    'worker_loaders binding LOADER',
+    'r2_buckets binding PACKAGE_ARTIFACTS',
+  ]);
+});

tools/local_seed.ts

@@ -27,7 +27,7 @@ if (import.meta.main) {
     console.log('Next:');
     console.log('1. Run `deno task local:start`.');
     console.log('2. Open http://localhost:8417/admin/packages.');
-    console.log('3. Start with Template App, Web Checkup, or Office Hours Web Lab.');
+    console.log('3. Start with Template App, Web Checkup, or TypeScript Ladder Game.');
   } finally {
     await pool.end();
   }

tools/reference_sync.ts

@@ -0,0 +1,27 @@
+import { readArgs, syncReferencePackageSources } from './reference_sync_support.ts';
+
+try {
+  const args = readArgs(Deno.args);
+  const summary = await syncReferencePackageSources(args);
+
+  console.log(
+    `${summary.dryRun ? 'Planned' : 'Synced'} ${summary.uploads.length} curated reference source file(s) to ${summary.bucket} (${summary.mode}).`,
+  );
+  console.log(`Packages: ${summary.appIds.join(', ')}`);
+
+  if (summary.dryRun) {
+    console.log('Uploads:');
+
+    for (const upload of summary.uploads) {
+      console.log(`- ${summary.bucket}/${upload.objectKey} <- ${upload.sourcePath}`);
+    }
+  } else {
+    console.log('');
+    console.log('Next:');
+    console.log('1. Run Workers against the same PACKAGE_ARTIFACTS bucket.');
+    console.log('2. Import curated apps from /admin/packages/reference.');
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : 'Reference package source sync failed.');
+  Deno.exit(1);
+}