cursedbelt-core 2.1.1 → 2.3.0

package/src/config/appConfig.ts

@@ -1,7 +1,7 @@
 /**
  * `app-config.json` — the single schema the compiler AND the runtime import
  * (02-MASTER-ENGINES §2). Nothing else may re-declare this shape: a second copy
- * is how `privateMedia` without `guard` parsed as valid for a year (J2-1).
+ * is how a feature without the engine it needs parsed as valid for a year (J2-1).
  *
  * Two laws are encoded here rather than in prose:
  *
@@ -9,8 +9,8 @@
  *    `features` block — is a parse ERROR (`unknown-config-key`), never silently
  *    stripped. A typo'd flag that gets dropped reads as "the feature is off" at
  *    runtime, which is indistinguishable from a bug in the feature.
- * 2. `.superRefine()` cross-engine dependencies. `privateMedia` needs `guard`,
- *    `oralHistory` needs `asset`, `auth.enabled` needs `guard`, and the saas
+ * 2. `.superRefine()` cross-engine dependencies. `oralHistory` needs `asset`,
+ *    `auth.enabled` needs `guard`, and the saas
  *    profile needs `guard` + `rbac:true`. These are structural: the config
  *    references something that will not exist at runtime, so it dies at V0 —
  *    fail-closed on structure (04 §0).
@@ -35,7 +35,9 @@ export const AssetFeatures = z
     editor: z.boolean().default(false), // lazy chunk; joins bundleKey
     fileBrowser: z.boolean().default(false),
     taggedFiles: z.boolean().default(false),
-    privateMedia: z.boolean().default(false), // requires guard engine — enforced in superRefine
+    // `privateMedia` was here until 2.3.0 (task 330). Its server module and the `pfs/` keyspace
+    // were deleted from cursedbelt-server in 4.0.0, so the flag named a tier that no longer
+    // exists; `.strict()` now refuses it as `unknown-config-key`, which is the honest answer.
     vaultSource: z.boolean().default(false),
     ocr: z.boolean().default(false),
     imageStudio: z.boolean().default(false),
@@ -326,11 +328,6 @@ export const AppConfigSchema = z
       const f = parsed.data as Record<string, unknown>;
 
       // (c) cross-engine dependencies — hard blocks, not comments (J2-1)
-      if (inst.engine === 'asset' && f.privateMedia === true && !engineSet.has('guard'))
-        issue(
-          ['instances', i, 'features', 'privateMedia'],
-          `'privateMedia' requires the 'guard' engine in engines[] (engine-dependency-missing).`,
-        );
       if (inst.engine === 'knowledge' && f.oralHistory === true && !engineSet.has('asset'))
         issue(
           ['instances', i, 'features', 'oralHistory'],

package/src/core/offline/shellWorker.spec.ts

@@ -0,0 +1,392 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  classifyRequest,
+  installShellWorker,
+  mayFallBackToShell,
+  type RequestFacts,
+  resolveShellWorkerConfig,
+  type ShellExtendableEvent,
+  type ShellFetchEvent,
+  type ShellWorkerCache,
+  type ShellWorkerConfig,
+  type ShellWorkerRequest,
+  type ShellWorkerRequestInfo,
+  type ShellWorkerResponse,
+  type ShellWorkerScope,
+  shouldCache,
+} from './shellWorker.js';
+
+/** roms' worker, expressed as a config — the two special cases are the point. */
+const ROMS: ShellWorkerConfig = {
+  cachePrefix: 'roms-shell-',
+  version: 'v3',
+  precache: ['/', '/emulator-frame.html', '/emulator-runtime.js'],
+  passthroughPrefixes: ['/_nes-roms/'],
+  noShellFallback: ['/emulator-frame.html'],
+};
+
+const facts = (pathname: string, over: Partial<RequestFacts> = {}): RequestFacts => ({
+  method: 'GET',
+  sameOrigin: true,
+  pathname,
+  isNavigate: false,
+  ...over,
+});
+
+describe('classifyRequest — roms parity', () => {
+  const table: Array<[string, RequestFacts, string]> = [
+    ['non-GET is passthrough', facts('/app.js', { method: 'POST' }), 'passthrough'],
+    ['cross-origin is passthrough', facts('/app.js', { sameOrigin: false }), 'passthrough'],
+    ['/api/ is api', facts('/api/saves'), 'api'],
+    ['/api/ wins over the .json asset extension', facts('/api/library.json'), 'api'],
+    ['/api/ wins over a navigation', facts('/api/me', { isNavigate: true }), 'api'],
+    ['roms ROM bytes are passthrough (config)', facts('/_nes-roms/mario.nes'), 'passthrough'],
+    ['roms ROM path as a .json is still passthrough', facts('/_nes-roms/index.json'), 'passthrough'],
+    ['a navigation is navigate', facts('/library/nes', { isNavigate: true }), 'navigate'],
+    ['the frame document is a navigation', facts('/emulator-frame.html', { isNavigate: true }), 'navigate'],
+    ['hashed JS is an asset', facts('/assets/index-abc123.js'), 'asset'],
+    ['WASM is an asset', facts('/cores/snes9x.wasm'), 'asset'],
+    ['a font is an asset', facts('/fonts/inter.woff2'), 'asset'],
+    ['upper-case extension is an asset', facts('/icons/LOGO.PNG'), 'asset'],
+    ['an extensionless non-navigation is passthrough', facts('/healthz'), 'passthrough'],
+    ['a .nes file outside the ROM path is passthrough', facts('/other/mario.nes'), 'passthrough'],
+  ];
+  for (const [name, input, route] of table) {
+    it(name, () => expect(classifyRequest(input, ROMS)).toBe(route));
+  }
+
+  it('without the passthrough config the ROM path would be an asset — the config is what decides', () => {
+    expect(classifyRequest(facts('/_nes-roms/index.json'), {})).toBe('asset');
+  });
+
+  it('/api/ stays api even when a config lists only other API prefixes', () => {
+    expect(classifyRequest(facts('/api/me'), { apiPrefixes: ['/rpc/'] })).toBe('api');
+    expect(classifyRequest(facts('/rpc/call.json'), { apiPrefixes: ['/rpc/'] })).toBe('api');
+  });
+
+  it('a custom asset regex replaces the default', () => {
+    expect(classifyRequest(facts('/a.js'), { assetExtensions: /\.css$/ })).toBe('passthrough');
+    expect(classifyRequest(facts('/a.css'), { assetExtensions: /\.css$/ })).toBe('asset');
+  });
+});
+
+describe('shouldCache / mayFallBackToShell', () => {
+  it('caches assets and navigations, never the API or passthrough', () => {
+    expect(shouldCache('asset')).toBe(true);
+    expect(shouldCache('navigate')).toBe(true);
+    expect(shouldCache('api')).toBe(false);
+    expect(shouldCache('passthrough')).toBe(false);
+  });
+
+  it('refuses the shell to roms’ frame and allows it everywhere else', () => {
+    expect(mayFallBackToShell('/emulator-frame.html', ROMS)).toBe(false);
+    expect(mayFallBackToShell('/library/nes', ROMS)).toBe(true);
+    expect(mayFallBackToShell('/emulator-frame.html', {})).toBe(true);
+  });
+});
+
+describe('resolveShellWorkerConfig — the refusals', () => {
+  it('names the cache prefix+version and always precaches the shell', () => {
+    const resolved = resolveShellWorkerConfig({ cachePrefix: 'music-shell-', version: 'v1', precache: ['/player.js'] });
+    expect(resolved.cacheName).toBe('music-shell-v1');
+    expect(resolved.precache).toEqual(['/', '/player.js']);
+    expect(resolved.apiPrefixes).toEqual(['/api/']);
+  });
+
+  it('keeps roms’ precache as written when the shell is already listed', () => {
+    expect(resolveShellWorkerConfig(ROMS).precache).toEqual(ROMS.precache);
+  });
+
+  it('refuses an empty prefix — activate would delete every cache on the origin', () => {
+    expect(() => resolveShellWorkerConfig({ ...ROMS, cachePrefix: '' })).toThrow(/cachePrefix/);
+  });
+
+  it('refuses to precache anything under an API prefix', () => {
+    expect(() => resolveShellWorkerConfig({ ...ROMS, precache: ['/', '/api/me'] })).toThrow(/API is never cached/);
+    expect(() => resolveShellWorkerConfig({ ...ROMS, apiPrefixes: ['/rpc/'], precache: ['/rpc/x'] })).toThrow(
+      /API is never cached/,
+    );
+  });
+
+  it('refuses a relative precache entry and a shell that may not be its own fallback', () => {
+    expect(() => resolveShellWorkerConfig({ ...ROMS, precache: ['app.js'] })).toThrow(/starting with "\/"/);
+    expect(() => resolveShellWorkerConfig({ ...ROMS, noShellFallback: ['/'] })).toThrow(/noShellFallback/);
+  });
+});
+
+// ── A fake worker scope ─────────────────────────────────────────────────────────
+
+const ORIGIN = 'https://app.test';
+
+class FakeResponse implements ShellWorkerResponse {
+  constructor(
+    readonly body: string,
+    readonly ok = true,
+  ) {}
+  clone(): FakeResponse {
+    return new FakeResponse(this.body, this.ok);
+  }
+}
+
+const req = (path: string, over: Partial<ShellWorkerRequest> = {}): ShellWorkerRequest => ({
+  url: path.startsWith('http') ? path : `${ORIGIN}${path}`,
+  method: 'GET',
+  mode: 'cors',
+  ...over,
+});
+const nav = (path: string): ShellWorkerRequest => req(path, { mode: 'navigate' });
+
+const urlOf = (info: ShellWorkerRequestInfo): string =>
+  typeof info === 'string' ? new URL(info, ORIGIN).href : 'href' in info ? info.href : info.url;
+
+const stripSearch = (url: string): string => {
+  const u = new URL(url);
+  return `${u.origin}${u.pathname}`;
+};
+
+/**
+ * A worker scope backed by Maps: `server` is what the network answers when `online`,
+ * `cacheStore` is CacheStorage. Every network call and every cache write is recorded,
+ * so a test can prove a request was NEVER touched, not merely answered correctly.
+ */
+const makeWorld = () => {
+  const server = new Map<string, FakeResponse>();
+  const cacheStore = new Map<string, Map<string, FakeResponse>>();
+  const networkCalls: string[] = [];
+  const cacheWrites: string[] = [];
+  const listeners: Record<string, (event: never) => void> = {};
+  let online = true;
+  let skipped = false;
+  let claimed = false;
+
+  const network = async (url: string): Promise<FakeResponse> => {
+    networkCalls.push(url);
+    if (!online) throw new TypeError('Failed to fetch');
+    return server.get(url) ?? new FakeResponse('not found', false);
+  };
+
+  const openCache = (name: string): ShellWorkerCache => {
+    let entries = cacheStore.get(name);
+    if (!entries) {
+      entries = new Map();
+      cacheStore.set(name, entries);
+    }
+    const bucket = entries;
+    return {
+      async addAll(paths) {
+        for (const path of paths) {
+          const res = await network(`${ORIGIN}${path}`);
+          if (!res.ok) throw new TypeError(`addAll: ${path} answered not-ok`);
+          bucket.set(`${ORIGIN}${path}`, res);
+        }
+      },
+      async put(request, response) {
+        cacheWrites.push(urlOf(request));
+        bucket.set(urlOf(request), response as FakeResponse);
+      },
+    };
+  };
+
+  const scope: ShellWorkerScope = {
+    addEventListener(type: string, listener: (event: never) => void) {
+      listeners[type] = listener;
+    },
+    caches: {
+      open: async (name) => openCache(name),
+      keys: async () => [...cacheStore.keys()],
+      delete: async (name) => cacheStore.delete(name),
+      async match(request, options) {
+        const raw = urlOf(request);
+        for (const entries of cacheStore.values()) {
+          const exact = entries.get(raw);
+          if (exact) return exact;
+          if (options?.ignoreSearch) {
+            for (const [key, value] of entries) if (stripSearch(key) === stripSearch(raw)) return value;
+          }
+        }
+        return undefined;
+      },
+    },
+    clients: {
+      async claim() {
+        claimed = true;
+      },
+    },
+    location: { origin: ORIGIN },
+    fetch: (request) => network(urlOf(request)),
+    async skipWaiting() {
+      skipped = true;
+    },
+  };
+
+  const extendable = async (type: 'install' | 'activate'): Promise<void> => {
+    const waits: Promise<unknown>[] = [];
+    const event: ShellExtendableEvent = { waitUntil: (p) => void waits.push(p) };
+    (listeners[type] as (e: ShellExtendableEvent) => void)(event);
+    await Promise.all(waits);
+  };
+
+  /** Dispatch a fetch. `response` is undefined when the worker did not call respondWith. */
+  const dispatch = (request: ShellWorkerRequest) => {
+    const waits: Promise<unknown>[] = [];
+    let response: Promise<ShellWorkerResponse> | undefined;
+    const event: ShellFetchEvent = {
+      request,
+      waitUntil: (p) => void waits.push(p),
+      respondWith: (r) => {
+        response = r;
+      },
+    };
+    (listeners.fetch as (e: ShellFetchEvent) => void)(event);
+    return {
+      response,
+      /** Resolve the response, then let every deferred cache write land. */
+      settled: async () => {
+        const body = response ? await response : undefined;
+        await Promise.all(waits);
+        return body as FakeResponse | undefined;
+      },
+    };
+  };
+
+  return {
+    scope,
+    server,
+    cacheStore,
+    networkCalls,
+    cacheWrites,
+    extendable,
+    dispatch,
+    goOffline: () => {
+      online = false;
+    },
+    get skipped() {
+      return skipped;
+    },
+    get claimed() {
+      return claimed;
+    },
+  };
+};
+
+/** A roms-shaped world, installed while online. */
+const installedRoms = async () => {
+  const world = makeWorld();
+  world.server.set(`${ORIGIN}/`, new FakeResponse('<shell>'));
+  world.server.set(`${ORIGIN}/emulator-frame.html`, new FakeResponse('<frame>'));
+  world.server.set(`${ORIGIN}/emulator-runtime.js`, new FakeResponse('runtime'));
+  installShellWorker(world.scope, ROMS);
+  await world.extendable('install');
+  return world;
+};
+
+describe('installShellWorker — install and activate', () => {
+  it('precaches the configured paths into prefix+version and skips waiting', async () => {
+    const world = await installedRoms();
+    expect([...(world.cacheStore.get('roms-shell-v3')?.keys() ?? [])]).toEqual([
+      `${ORIGIN}/`,
+      `${ORIGIN}/emulator-frame.html`,
+      `${ORIGIN}/emulator-runtime.js`,
+    ]);
+    expect(world.skipped).toBe(true);
+  });
+
+  it('does not skip waiting when the precache fails — the old worker keeps serving', async () => {
+    const world = makeWorld(); // nothing on the server: addAll rejects
+    installShellWorker(world.scope, ROMS);
+    await expect(world.extendable('install')).rejects.toThrow(/answered not-ok/);
+    expect(world.skipped).toBe(false);
+  });
+
+  it('deletes old versions of its own prefix on activate, keeps everything else, and claims', async () => {
+    const world = await installedRoms();
+    world.cacheStore.set('roms-shell-v2', new Map());
+    world.cacheStore.set('roms-shell-v1', new Map());
+    world.cacheStore.set('roms-rom-digests', new Map()); // the app's own cache
+    await world.extendable('activate');
+    expect([...world.cacheStore.keys()].sort()).toEqual(['roms-rom-digests', 'roms-shell-v3']);
+    expect(world.claimed).toBe(true);
+  });
+});
+
+describe('installShellWorker — fetch', () => {
+  it('serves an online navigation from the network and caches it', async () => {
+    const world = await installedRoms();
+    world.server.set(`${ORIGIN}/library/nes`, new FakeResponse('<library>'));
+    const body = await world.dispatch(nav('/library/nes')).settled();
+    expect(body?.body).toBe('<library>');
+    expect(world.cacheWrites).toContain(`${ORIGIN}/library/nes`);
+  });
+
+  it('falls back to the SHELL for an offline navigation nothing cached', async () => {
+    const world = await installedRoms();
+    world.goOffline();
+    const body = await world.dispatch(nav('/library/snes?sort=recent')).settled();
+    expect(body?.body).toBe('<shell>');
+  });
+
+  it('answers the frame offline from its own cached copy, ignoring the query', async () => {
+    const world = await installedRoms();
+    world.goOffline();
+    const body = await world.dispatch(nav('/emulator-frame.html?system=nes')).settled();
+    expect(body?.body).toBe('<frame>');
+  });
+
+  it('🔴 never hands the SHELL to a noShellFallback path — it rejects instead (the 2026-08-12 incident)', async () => {
+    const world = makeWorld();
+    world.server.set(`${ORIGIN}/`, new FakeResponse('<shell>'));
+    // The 2026-08-12 shape: the frame is NOT precached, the shell is.
+    installShellWorker(world.scope, { ...ROMS, precache: ['/'] });
+    await world.extendable('install');
+    world.goOffline();
+    const { response } = world.dispatch(nav('/emulator-frame.html?system=nes'));
+    expect(response).toBeDefined();
+    await expect(response as Promise<ShellWorkerResponse>).rejects.toThrow('Failed to fetch');
+  });
+
+  it('rethrows the network error when offline with nothing cached at all, rather than resolving anything', async () => {
+    const world = makeWorld();
+    installShellWorker(world.scope, ROMS); // never installed: no shell in any cache
+    world.goOffline();
+    await expect(world.dispatch(nav('/library/nes')).response as Promise<ShellWorkerResponse>).rejects.toThrow(
+      'Failed to fetch',
+    );
+  });
+
+  it('serves assets cache-first and caches only an ok response', async () => {
+    const world = await installedRoms();
+    world.server.set(`${ORIGIN}/assets/app-1.js`, new FakeResponse('app'));
+    expect((await world.dispatch(req('/assets/app-1.js')).settled())?.body).toBe('app');
+    expect((await world.dispatch(req('/assets/missing.js')).settled())?.ok).toBe(false);
+    expect(world.cacheWrites).toEqual([`${ORIGIN}/assets/app-1.js`]);
+    world.goOffline();
+    const calls = world.networkCalls.length;
+    expect((await world.dispatch(req('/assets/app-1.js')).settled())?.body).toBe('app');
+    expect(world.networkCalls.length).toBe(calls); // from the cache, not the network
+  });
+
+  it('🔴 never intercepts, reads or caches /api/ — even with a stale copy planted in the cache', async () => {
+    const world = await installedRoms();
+    world.cacheStore.get('roms-shell-v3')?.set(`${ORIGIN}/api/me`, new FakeResponse('{"user":"revoked"}'));
+    for (const request of [req('/api/me'), nav('/api/me'), req('/api/library.json')]) {
+      const { response } = world.dispatch(request);
+      expect(response, `${request.url} (${request.mode}) must not be answered by the worker`).toBeUndefined();
+    }
+    world.goOffline();
+    expect(world.dispatch(req('/api/me')).response).toBeUndefined();
+    expect(world.networkCalls.filter((u) => u.includes('/api/'))).toEqual([]);
+    expect(world.cacheWrites.filter((u) => u.includes('/api/'))).toEqual([]);
+  });
+
+  it('leaves non-GET, cross-origin and passthrough-prefixed requests to the browser', async () => {
+    const world = await installedRoms();
+    for (const request of [
+      req('/assets/app.js', { method: 'POST' }),
+      req('https://cdn.other.test/lib.js'),
+      req('/_nes-roms/mario.nes'),
+      req('/healthz'),
+    ]) {
+      expect(world.dispatch(request).response, request.url).toBeUndefined();
+    }
+  });
+});