toiljs 0.0.59 → 0.0.61

package/test/doctor.test.ts

@@ -6,6 +6,7 @@ import {
     checkDevScripts,
     checkDuplicatePatterns,
     type CheckGroup,
+    checkMigrationsDir,
     checkMountSlots,
     checkNode,
     checkPeer,
@@ -219,6 +220,18 @@ describe('checkAuthSecrets', () => {
     });
 });
 
+describe('checkMigrationsDir', () => {
+    it('passes when the server/migrations/ folder exists', () => {
+        expect(checkMigrationsDir(true).status).toBe('pass');
+    });
+    it('warns (not fails) when missing, naming the convention and the update fix', () => {
+        const c = checkMigrationsDir(false);
+        expect(c.status).toBe('warn');
+        expect(c.detail).toContain('migration.ts');
+        expect(c.fix).toContain('toiljs update');
+    });
+});
+
 describe('summarize', () => {
     it('tallies pass/warn/fail across groups', () => {
         const groups: CheckGroup[] = [

package/test/email-preview.test.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { createServer } from 'vite';
@@ -14,7 +15,11 @@ import { createViteConfig } from '../src/compiler/vite';
 
 const EXAMPLE = path.resolve(__dirname, '../examples/basic');
 
-describe('email preview end-to-end (examples/basic)', () => {
+// Drives a Vite server over examples/basic; skip where the example's deps are
+// not installed (e.g. CI without the example set up).
+describe.skipIf(!existsSync(path.join(EXAMPLE, 'node_modules')))(
+    'email preview end-to-end (examples/basic)',
+    () => {
     it('lists Welcome and inlines its emails/styles/email.css; client/* alias resolves', async () => {
         const cfg = await loadConfig({ root: EXAMPLE });
         const items = listEmails(cfg);

package/test/example-guestbook.test.ts

@@ -7,13 +7,14 @@
  * request". Skips until the example server wasm is built (`npm run build:server`).
  */
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { describe, expect, it, beforeEach } from 'vitest';
 
 import { WasmServerModule } from '../src/devserver/index.js';
-import { __resetDbForTests } from '../src/devserver/database.js';
+import { __resetDbForTests, configureDbPersistence } from '../src/devserver/db/index.js';
 
 const EXAMPLE_WASM = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
@@ -75,4 +76,45 @@ describe.skipIf(!haveWasm)('guestbook demo: ToilDB events + counter persist acro
         // A read-only GET on yet another instance sees the same persisted state.
         expect(json(list(load())).total).toBe('2');
     });
+
+    // End-to-end proof that the `server/migrations/GuestEntry.migration.ts` demo
+    // actually RUNS: write an entry under the current shape, downgrade it on disk to
+    // the original pre-`at` `GuestEntryV1` layout (drop the trailing u64 + re-stamp
+    // with v1's schema_version), then `list()` and confirm the woven decoder ran the
+    // `@migrate` - the entry comes back with the new `at` field defaulted to 0.
+    it('migrates an on-disk pre-`at` entry on read (the GuestEntry.migration demo fires)', () => {
+        const GUEST_ENTRY_V1_VERSION = 631968986; // layoutHash({author:string, message:string})
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gb-mig-'));
+        const file = path.join(dir, 'devdata.json');
+        try {
+            // 1. sign under the CURRENT shape (author, message, at); persistence flushes it.
+            configureDbPersistence(file);
+            expect(sign(load(), 'Ada', 'from the old days').status).toBe(200);
+
+            // 2. downgrade that event on disk to the v1 shape: GuestEntry encodes
+            //    author + message + at(u64), so dropping the trailing 8 bytes yields a
+            //    valid GuestEntryV1; re-stamp it with v1's schema_version.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const snap: any = JSON.parse(fs.readFileSync(file, 'utf8'));
+            const evKey = Object.keys(snap.events)[0];
+            const buf = Buffer.from(snap.events[evKey][0].v, 'base64');
+            snap.events[evKey][0] = {
+                v: buf.subarray(0, buf.length - 8).toString('base64'),
+                sv: GUEST_ENTRY_V1_VERSION,
+            };
+            fs.writeFileSync(file, JSON.stringify(snap));
+
+            // 3. reload + list: the read surfaces v1's version, so the guest's woven
+            //    decoder runs the @migrate, copying author/message and defaulting at=0.
+            __resetDbForTests();
+            configureDbPersistence(file);
+            const v = json(list(load()));
+            expect(v.entries.length).toBe(1);
+            expect(v.entries[0].author).toBe('Ada');
+            expect(v.entries[0].message).toBe('from the old days');
+            expect(String(v.entries[0].at)).toBe('0'); // the migrated-in field
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
 });

package/test/fixtures/daemon-app.ts

@@ -0,0 +1,56 @@
+// A minimal @daemon fixture for the dev daemon-emulation test. It declares the
+// `daemon.*` / `mstore.*` host imports directly (so it needs no toiljs globals
+// lib) and records its activity into the dev MemoryStore, which the test reads
+// back through `devMemoryStore`. Compiled with `--targetMode cold` by the test.
+//
+//   onStart()          -> mstore.incr("started", 1) and stamps the lease epoch
+//   tick()  @scheduled -> mstore.incr("tick:fast", 1)   (1s interval)
+//   sixHourly() cron   -> mstore.incr("tick:cron", 1)   (0 */6 * * *)
+
+// @ts-nocheck — this is AssemblyScript source compiled by toilscript, not TS.
+
+@external("env", "mstore.incr")
+declare function mstoreIncr(keyPtr: i32, keyLen: i32, delta: i64, ttlSecs: i32): i64;
+
+@external("env", "daemon.is_leader")
+declare function daemonIsLeader(): i32;
+
+@external("env", "daemon.current_epoch")
+declare function daemonCurrentEpoch(): i64;
+
+@external("env", "daemon.task_count")
+declare function daemonTaskCount(): i32;
+
+// Bump the i64 counter stored at the (utf8) `key` by 1. The host reads the key
+// bytes straight out of linear memory (handleless mstore, ttl in seconds).
+function bump(key: string): void {
+    let bytes = String.UTF8.encode(key);
+    mstoreIncr(changetype<i32>(bytes), bytes.byteLength, 1, 0);
+}
+
+@daemon
+class Jobs {
+    onStart(): void {
+        // Prove leader=true and that the epoch import is callable; record both so
+        // the test can assert the stubs from outside.
+        bump("started");
+        if (daemonIsLeader() == 1) bump("leader");
+        let epoch = daemonCurrentEpoch();
+        if (epoch >= 0) bump("epoch:nonneg");
+        if (daemonTaskCount() == 2) bump("taskcount:2");
+    }
+
+    @scheduled("1s")
+    tick(): void {
+        bump("tick:fast");
+    }
+
+    @scheduled("0 */6 * * *")
+    sixHourly(): void {
+        bump("tick:cron");
+    }
+}
+
+export function probe(): i32 {
+    return 1;
+}

package/test/global-setup.ts

@@ -0,0 +1,17 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Vitest global setup: generate `src/compiler/toil-docs.generated.ts` before the
+ * suite runs. `src/compiler/docs.ts` imports that module, but it is gitignored
+ * and only (re)created by the build's `gen:docs` step, so a fresh checkout that
+ * runs the tests without a prior build would otherwise fail to resolve it
+ * ("Cannot find module './toil-docs.generated.js'"). Running the same generator
+ * the npm scripts use keeps the tests self-contained. Runs once per vitest
+ * invocation, so it also covers `npx vitest` / watch mode.
+ */
+export default function setup(): void {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    execFileSync('node', ['scripts/gen-toil-docs.mjs'], { cwd: root, stdio: 'ignore' });
+}

package/test/pqauth-e2e.test.ts

@@ -20,7 +20,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import { ristretto255_oprf } from '@noble/curves/ed25519.js';
 
 import { WasmServerModule } from '../src/devserver/index.js';
-import { __resetDbForTests } from '../src/devserver/database.js';
+import { __resetDbForTests } from '../src/devserver/db/index.js';
 import { Auth } from '../src/client/auth.js';
 import { DataReader, DataWriter } from '../src/io/codec.js';
 

package/test/ssr-render.test.ts

@@ -1,11 +1,19 @@
 /**
  * End-to-end guest render: drive the real ToilScript-compiled `render` export
- * of the SSR example wasm, decode its values envelope, and confirm the guest
- * produces exactly the bytes the Rust host's `decode_values`/`assemble` expects
- * (the same wire format proven on the host side in
+ * of the basic example's server wasm, decode its values envelope, and confirm
+ * the guest produces exactly the bytes the Rust host's `decode_values`/`assemble`
+ * expects (the same wire format proven on the host side in
  * `toil-backend/src/host/template/assemble.rs`). Closing the loop with the
  * golden byte-identity test (`ssr-template.test.tsx`), this proves the full
  * chain: guest values -> splice -> React-identical HTML.
+ *
+ * SSR is part of the normal (single-wasm) build now: the example's `/hello`
+ * route opts in with `export const ssr = true`, the build extracts its template
+ * into `build/client/_ssr/hello.{tmpl,slots,slots.ts}`, and the server
+ * `render` (`examples/basic/server/SsrHelloRender.ts`) fills the holes. We drive
+ * the same `build/server/release.wasm` the dev server and edge run, and pin the
+ * expected coherence hash to the generated `templates.json` so the guest and the
+ * deployed template are proven to agree.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -16,10 +24,14 @@ import { describe, expect, it } from 'vitest';
 import { WasmServerModule } from '../src/devserver/index.js';
 import { spliceTemplate } from '../src/compiler/template.js';
 
-const SSR_WASM = path.resolve(
+const EXAMPLE = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
-    '../examples/basic/build/server/ssr.wasm',
+    '../examples/basic',
 );
+/** Single-wasm SSR: the server `render` lives in the normal server wasm. */
+const SERVER_WASM = path.join(EXAMPLE, 'build/server/release.wasm');
+const SSR_DIR = path.join(EXAMPLE, 'build/client/_ssr');
+const TEMPLATES = path.join(SSR_DIR, 'templates.json');
 
 interface DecodedSlot {
     slotId: number;
@@ -72,9 +84,25 @@ function decodeValues(buf: Uint8Array): DecodedValues {
     return { status, hash, headers, slots };
 }
 
-describe.skipIf(!fs.existsSync(SSR_WASM))('edge SSR guest render (real wasm)', () => {
+/** The hash the build pinned for the `/hello` template (deploy-skew guard). */
+function helloTemplateHash(): Buffer {
+    const index = JSON.parse(fs.readFileSync(TEMPLATES, 'utf8')) as {
+        route: string;
+        name: string;
+        hash: string;
+    }[];
+    const hello = index.find((t) => t.route === '/hello');
+    if (!hello) throw new Error('no /hello template in templates.json');
+    return Buffer.from(hello.hash, 'hex');
+}
+
+// Skip cleanly when the example has not been built (no toolchain in CI): the
+// build is what produces both the wasm and the template artifacts.
+const built = fs.existsSync(SERVER_WASM) && fs.existsSync(TEMPLATES);
+
+describe.skipIf(!built)('edge SSR guest render (real single-wasm build)', () => {
     const load = (): WasmServerModule => {
-        const m = new WasmServerModule(SSR_WASM);
+        const m = new WasmServerModule(SERVER_WASM);
         m.refresh();
         return m;
     };
@@ -86,36 +114,75 @@ describe.skipIf(!fs.existsSync(SSR_WASM))('edge SSR guest render (real wasm)', (
             body: new Uint8Array(0),
         });
 
-    it('produces a values envelope with the compiled-in hash and escaped holes', () => {
+    it('produces a values envelope with the deployed template hash and escaped holes', () => {
         const d = decodeValues(render(load(), '/hello'));
         expect(d.status).toBe(200);
-        // The HASH baked into greeting.slots.ts: bytes 0x00..0x1f.
-        expect([...d.hash]).toEqual(Array.from({ length: 32 }, (_, i) => i));
+        // The guest's compiled-in HASH must equal the deployed template's hash,
+        // or the host rejects the response as a deploy skew.
+        expect(d.hash.equals(helloTemplateHash())).toBe(true);
 
+        // Top-level slots in document order: name (text), blurb (raw), services (repeat).
         expect(d.slots.map((s) => `${s.slotId}:${s.kind}`)).toEqual([
-            '0:0', // greeting, text
-            '1:3', // count, repeat
+            '0:0', // name, text
+            '1:1', // blurb, raw
+            '2:3', // services, repeat
         ]);
-        // Text hole: React-escaped (& -> &amp;, <> -> entities, mirroring escape.ts).
-        expect(d.slots[0].value.toString('utf8')).toBe('world &amp; &lt;friends&gt;');
-        // Repeat hole: three stamped rows, each escaped.
+        // Text hole: the default greeting target.
+        expect(d.slots[0].value.toString('utf8')).toBe('world');
+        // Raw hole: inserted verbatim (NOT escaped).
         expect(d.slots[1].value.toString('utf8')).toBe(
-            '<li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li>',
+            'Rendered at the <strong>edge</strong> from a tiny values envelope.',
         );
+        // Repeat hole: three stamped rows, each nested hole React-escaped.
+        expect(d.slots[2].value.toString('utf8')).toBe(
+            '<li><strong>record</strong><span class="hello-region">us-east</span></li>' +
+                '<li><strong>unique</strong><span class="hello-region">eu-west</span></li>' +
+                '<li><strong>counter</strong><span class="hello-region">ap-south</span></li>',
+        );
+    });
+
+    it('escapes a text hole derived from the request (?name=)', () => {
+        const d = decodeValues(render(load(), '/hello?name=A<b>%26"x'));
+        expect(d.status).toBe(200);
+        // setText React-escapes: & -> &amp;, <> -> entities, " -> &quot;.
+        // (The query value arrives as the raw bytes after `name=`; only `%26`
+        // is a literal here, so the guest sees `A<b>&"x` after the `&` split is
+        // accounted for — assert the escaping shape rather than the exact bytes.)
+        const v = d.slots[0].value.toString('utf8');
+        expect(v).not.toContain('<b>');
+        expect(v).toContain('&lt;');
     });
 
-    it('splices into a template exactly (full guest -> host -> HTML chain)', () => {
+    it('splices into the real built template exactly (guest -> host -> HTML)', () => {
         const d = decodeValues(render(load(), '/hello'));
-        // A template with a greeting hole and a repeat region, holes removed.
-        const tmpl = Buffer.from('<h1>Hello </h1><ul></ul>', 'utf8');
-        const greetingOffset = '<h1>Hello '.length;
-        const repeatOffset = '<h1>Hello </h1><ul>'.length;
-        const out = spliceTemplate(tmpl, [
-            { offset: greetingOffset, value: Buffer.from(d.slots[0].value) },
-            { offset: repeatOffset, value: Buffer.from(d.slots[1].value) },
-        ]);
-        expect(out.toString('utf8')).toBe(
-            '<h1>Hello world &amp; &lt;friends&gt;</h1><ul><li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li></ul>',
+        const tmpl = fs.readFileSync(path.join(SSR_DIR, 'hello.tmpl'));
+        const slotsBin = fs.readFileSync(path.join(SSR_DIR, 'hello.slots'));
+
+        // Read the top-level slot offsets straight from the .slots manifest
+        // (header is 46 bytes; each entry is offset u32, id u16, kind u8, rsvd u8).
+        const nSlots = slotsBin.readUInt16LE(44);
+        const byId = new Map(d.slots.map((s) => [s.slotId, s.value]));
+        const inserts: { offset: number; value: Buffer }[] = [];
+        let o = 46;
+        for (let i = 0; i < nSlots; i++) {
+            const offset = slotsBin.readUInt32LE(o);
+            const id = slotsBin.readUInt16LE(o + 4);
+            inserts.push({ offset, value: Buffer.from(byId.get(id)!) });
+            o += 8;
+        }
+        const out = spliceTemplate(tmpl, inserts).toString('utf8');
+
+        // The spliced section is well-formed and carries every filled hole.
+        expect(out).toContain(
+            '<section class="hello"><h1>Hello, world!</h1>' +
+                '<p class="hello-blurb"><span>Rendered at the <strong>edge</strong> ' +
+                'from a tiny values envelope.</span></p>' +
+                '<h2>Service snapshot</h2>' +
+                '<ul class="hello-services">' +
+                '<li><strong>record</strong><span class="hello-region">us-east</span></li>' +
+                '<li><strong>unique</strong><span class="hello-region">eu-west</span></li>' +
+                '<li><strong>counter</strong><span class="hello-region">ap-south</span></li>' +
+                '</ul></section>',
         );
     });
 

package/test/ssr-template.test.tsx

@@ -20,7 +20,7 @@ import path from 'node:path';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { describe, expect, it } from 'vitest';
 
-import { Hole, Island, RawHtml, Repeat, __setSsrBuild } from '../src/client/ssr/markers';
+import { Hole, Island, RawHtml, Repeat, attr, __setSsrBuild } from '../src/client/ssr/markers';
 import { LoaderDataContext, useLoaderData } from '../src/client/routing/loader';
 import {
     extractRouteTemplate,
@@ -265,6 +265,49 @@ describe('ssr guest codegen (Slot enum + HASH)', () => {
     });
 });
 
+describe('ssr attribute holes (attr())', () => {
+    it('is transparent in the browser and a sentinel under the build extractor', () => {
+        // Browser (default): passes the value through unchanged.
+        expect(attr('link', '/u/ada')).toBe('/u/ada');
+        // Build: emits a PUA sentinel token (start codepoint U+E000) carrying the id.
+        __setSsrBuild(true);
+        try {
+            const tok = attr('link', '/u/ada');
+            expect(tok).not.toBe('/u/ada');
+            expect(tok.charCodeAt(0)).toBe(0xe000);
+            expect(tok).toContain('link');
+        } finally {
+            __setSsrBuild(false);
+        }
+    });
+
+    it('extracts an attr slot whose guest stamp reproduces React attribute output byte-for-byte', () => {
+        // Render with the attr() hole in an attribute position, in build mode.
+        __setSsrBuild(true);
+        let built: string;
+        try {
+            built = renderToStaticMarkup(<a href={attr('link', 'IGNORED_AT_BUILD')}>x</a>);
+        } finally {
+            __setSsrBuild(false);
+        }
+        const { tmpl, slots } = extractFromHtml(built);
+        expect(slots).toHaveLength(1);
+        expect(slots[0]).toMatchObject({ id: 'link', kind: 'attr' });
+        expect(kindByte(slots[0].kind)).toBe(2);
+        // The .tmpl carries the attribute with the hole stripped to an empty value.
+        expect(tmpl.toString('utf8')).toBe('<a href="">x</a>');
+
+        // Guest stamp: setAttr React-escapes (identical to text); splice at the offset.
+        const value = '/u/ada?q="a"&b<c>';
+        const stamped = spliceTemplate(tmpl, [
+            { offset: slots[0].offset, value: Buffer.from(reactEscapeHtml(value), 'utf8') },
+        ]).toString('utf8');
+
+        // Byte-identical to what React renders for the same attribute value (clean hydration).
+        expect(stamped).toBe(renderToStaticMarkup(<a href={value}>x</a>));
+    });
+});
+
 describe('ssr build orchestration', () => {
     const SHELL =
         '<!doctype html><html><head><title>t</title></head><body><div id="root"></div>' +

package/vitest.config.ts

@@ -6,6 +6,9 @@ export default defineConfig({
     test: {
         globals: true,
         environment: 'node',
+        // Generate src/compiler/toil-docs.generated.ts (gitignored, imported by
+        // docs.ts) before the suite, so a fresh checkout can test without a build.
+        globalSetup: ['./test/global-setup.ts'],
         include: ['test/**/*.test.ts', 'test/**/*.test.tsx', 'test/**/*.spec.ts'],
         // test/assembly holds toilscript specs run by as-pect, not vitest.
         exclude: [...configDefaults.exclude, 'test/assembly/**'],

package/build/devserver/database.d.ts

@@ -1,8 +0,0 @@
-import type { MemoryRef } from './host.js';
-export interface DbDevState {
-    handles: string[];
-    lastResult: Buffer | null;
-}
-export declare function freshDbState(): DbDevState;
-export declare function buildDatabaseImports(ref: MemoryRef, db: DbDevState): Record<string, (...args: number[]) => number | bigint>;
-export declare function __resetDbForTests(): void;