@treeseed/sdk 0.1.1 → 0.3.0

package/dist/scripts/tenant-deploy.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { applyTreeseedEnvironmentToProcess } from '../operations/services/config-runtime.js';
+import { assertDeploymentInitialized, createBranchPreviewDeployTarget, createPersistentDeployTarget, deployTargetLabel, ensureGeneratedWranglerConfig, finalizeDeploymentState, runRemoteD1Migrations, } from '../operations/services/deploy.js';
+import { currentManagedBranch, PRODUCTION_BRANCH, STAGING_BRANCH } from '../operations/services/git-workflow.js';
+import { packageScriptPath, resolveWranglerBin } from '../operations/services/runtime-tools.js';
+import { runTenantDeployPreflight } from '../operations/services/save-deploy-preflight.js';
+const tenantRoot = process.cwd();
+const args = process.argv.slice(2);
+function writeDeployReport(payload) {
+    const target = process.env.TREESEED_DEPLOY_REPORT_PATH;
+    if (!target) {
+        return;
+    }
+    const filePath = resolve(target);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+function parseArgs(argv) {
+    const parsed = {
+        dryRun: false,
+        only: null,
+        name: null,
+        environment: null,
+        targetBranch: null,
+    };
+    const rest = [...argv];
+    while (rest.length) {
+        const current = rest.shift();
+        if (!current)
+            continue;
+        if (current === '--dry-run') {
+            parsed.dryRun = true;
+            continue;
+        }
+        if (current === '--only') {
+            parsed.only = rest.shift() ?? null;
+            continue;
+        }
+        if (current === '--name') {
+            parsed.name = rest.shift() ?? null;
+            continue;
+        }
+        if (current === '--environment') {
+            parsed.environment = rest.shift() ?? null;
+            continue;
+        }
+        if (current.startsWith('--environment=')) {
+            parsed.environment = current.split('=', 2)[1] ?? null;
+            continue;
+        }
+        if (current === '--target-branch') {
+            parsed.targetBranch = rest.shift() ?? null;
+            continue;
+        }
+        if (current.startsWith('--target-branch=')) {
+            parsed.targetBranch = current.split('=', 2)[1] ?? null;
+            continue;
+        }
+        throw new Error(`Unknown deploy argument: ${current}`);
+    }
+    return parsed;
+}
+function inferEnvironmentFromBranch() {
+    const branch = currentManagedBranch(tenantRoot);
+    if (branch === STAGING_BRANCH) {
+        return 'staging';
+    }
+    if (branch === PRODUCTION_BRANCH) {
+        return 'prod';
+    }
+    return null;
+}
+function resolveTarget(options) {
+    if (options.targetBranch) {
+        return {
+            target: createBranchPreviewDeployTarget(options.targetBranch),
+            scope: 'staging',
+        };
+    }
+    const environment = options.environment ?? (process.env.CI ? inferEnvironmentFromBranch() : null);
+    if (!environment) {
+        throw new Error('Treeseed deploy requires `--environment local|staging|prod` outside CI.');
+    }
+    return {
+        target: createPersistentDeployTarget(environment),
+        scope: environment,
+    };
+}
+function runNodeScript(scriptPath, scriptArgs = [], env = {}) {
+    const result = spawnSync(process.execPath, [scriptPath, ...scriptArgs], {
+        stdio: 'inherit',
+        cwd: tenantRoot,
+        env: { ...process.env, ...env },
+    });
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+function runWranglerDeploy(configPath) {
+    const result = spawnSync(process.execPath, [resolveWranglerBin(), 'deploy', '--config', configPath], {
+        stdio: 'inherit',
+        cwd: tenantRoot,
+        env: { ...process.env },
+    });
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+async function main() {
+    const options = parseArgs(args);
+    const { target, scope } = resolveTarget(options);
+    applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override: true });
+    const allowedSteps = new Set(['migrate', 'build', 'publish']);
+    if (options.only && !allowedSteps.has(options.only)) {
+        throw new Error(`Unsupported deploy step "${options.only}". Expected one of ${[...allowedSteps].join(', ')}.`);
+    }
+    const shouldRun = (step) => !options.only || options.only === step;
+    if (options.name) {
+        console.log(`Deploy target label: ${options.name}`);
+    }
+    if (scope === 'local') {
+        runTenantDeployPreflight({ cwd: tenantRoot, scope: 'local' });
+        runNodeScript(packageScriptPath('tenant-build'));
+        writeDeployReport({ ok: true, kind: 'success', scope, dryRun: options.dryRun, target: deployTargetLabel(target) });
+        console.log('Treeseed local deploy completed as a build-only publish target.');
+        return;
+    }
+    try {
+        assertDeploymentInitialized(tenantRoot, { target });
+        runTenantDeployPreflight({ cwd: tenantRoot, scope });
+    }
+    catch (error) {
+        writeDeployReport({
+            ok: false,
+            kind: 'preflight_failed',
+            target: deployTargetLabel(target),
+            message: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+    const { wranglerPath } = ensureGeneratedWranglerConfig(tenantRoot, { target });
+    if (shouldRun('migrate')) {
+        const result = runRemoteD1Migrations(tenantRoot, { dryRun: options.dryRun, target });
+        console.log(`${options.dryRun ? 'Planned' : 'Applied'} remote migrations for ${result.databaseName}.`);
+    }
+    if (shouldRun('build')) {
+        if (options.dryRun) {
+            console.log('Dry run: skipped tenant build.');
+        }
+        else {
+            runNodeScript(packageScriptPath('tenant-build'));
+        }
+    }
+    if (shouldRun('publish')) {
+        if (options.dryRun) {
+            console.log(`Dry run: would deploy ${deployTargetLabel(target)} with generated Wrangler config at ${resolve(wranglerPath)}.`);
+        }
+        else {
+            runWranglerDeploy(wranglerPath);
+            finalizeDeploymentState(tenantRoot, { target });
+        }
+    }
+    writeDeployReport({
+        ok: true,
+        kind: 'success',
+        dryRun: options.dryRun,
+        only: options.only,
+        target: deployTargetLabel(target),
+    });
+}
+try {
+    await main();
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+}

package/dist/scripts/tenant-destroy.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { applyTreeseedEnvironmentToProcess, assertTreeseedCommandEnvironment } from '../operations/services/config-runtime.js';
+import { cleanupDestroyedState, createPersistentDeployTarget, destroyCloudflareResources, loadDeployState, printDestroySummary, validateDestroyPrerequisites, } from '../operations/services/deploy.js';
+import { deriveCloudflareWorkerName } from '../platform/deploy/config.js';
+const tenantRoot = process.cwd();
+function parseArgs(argv) {
+    const parsed = {
+        dryRun: false,
+        force: false,
+        skipConfirmation: false,
+        confirm: null,
+        removeBuildArtifacts: false,
+        environment: null,
+    };
+    const rest = [...argv];
+    while (rest.length) {
+        const current = rest.shift();
+        if (!current)
+            continue;
+        if (current === '--dry-run') {
+            parsed.dryRun = true;
+            continue;
+        }
+        if (current === '--force') {
+            parsed.force = true;
+            continue;
+        }
+        if (current === '--skip-confirmation') {
+            parsed.skipConfirmation = true;
+            continue;
+        }
+        if (current === '--confirm') {
+            parsed.confirm = rest.shift() ?? null;
+            continue;
+        }
+        if (current === '--remove-build-artifacts') {
+            parsed.removeBuildArtifacts = true;
+            continue;
+        }
+        if (current === '--environment') {
+            parsed.environment = rest.shift() ?? null;
+            continue;
+        }
+        if (current.startsWith('--environment=')) {
+            parsed.environment = current.split('=', 2)[1] ?? null;
+            continue;
+        }
+        throw new Error(`Unknown destroy argument: ${current}`);
+    }
+    return parsed;
+}
+function getExpectedConfirmation(deployConfig) {
+    return deployConfig.slug;
+}
+function printDangerMessage(deployConfig, state, expectedConfirmation) {
+    console.error('DANGER: treeseed destroy will permanently delete this site and its Cloudflare resources.');
+    console.error(`  Site: ${deployConfig.name}`);
+    console.error(`  Slug: ${deployConfig.slug}`);
+    console.error(`  Worker: ${state.workerName ?? deriveCloudflareWorkerName(deployConfig)}`);
+    console.error(`  D1: ${state.d1Databases.SITE_DATA_DB.databaseName}`);
+    console.error(`  KV FORM_GUARD_KV: ${state.kvNamespaces.FORM_GUARD_KV.name}`);
+    console.error(`  KV SESSION: ${state.kvNamespaces.SESSION.name}`);
+    console.error('  This action is irreversible.');
+    console.error(`  To continue, type exactly: ${expectedConfirmation}`);
+}
+async function readConfirmation(expectedConfirmation) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        return (await rl.question('Confirmation: ')).trim() === expectedConfirmation;
+    }
+    finally {
+        rl.close();
+    }
+}
+const options = parseArgs(process.argv.slice(2));
+const scope = options.environment ?? 'prod';
+const target = createPersistentDeployTarget(scope);
+applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override: true });
+assertTreeseedCommandEnvironment({ tenantRoot, scope, purpose: 'destroy' });
+const deployConfig = validateDestroyPrerequisites(tenantRoot, { requireRemote: !options.dryRun });
+const state = loadDeployState(tenantRoot, deployConfig, { target });
+const expectedConfirmation = getExpectedConfirmation(deployConfig);
+if (!options.skipConfirmation) {
+    printDangerMessage(deployConfig, state, expectedConfirmation);
+    const confirmed = options.confirm !== null ? options.confirm === expectedConfirmation : await readConfirmation(expectedConfirmation);
+    if (!confirmed) {
+        console.error('Destroy aborted: confirmation text did not match.');
+        process.exit(1);
+    }
+}
+const result = destroyCloudflareResources(tenantRoot, {
+    dryRun: options.dryRun,
+    force: options.force,
+    target,
+});
+printDestroySummary(result);
+if (options.dryRun) {
+    console.log('Dry run: no remote resources were deleted.');
+    process.exit(0);
+}
+cleanupDestroyedState(tenantRoot, { target, removeBuildArtifacts: options.removeBuildArtifacts });
+console.log('Treeseed destroy completed and local deployment state was removed.');

package/dist/scripts/tenant-dev.js

@@ -0,0 +1,171 @@
+import { spawnSync } from 'node:child_process';
+import { corePackageRoot, packageScriptPath, spawnNodeBinary, resolveWranglerBin } from '../operations/services/runtime-tools.js';
+import { applyTreeseedEnvironmentToProcess, assertTreeseedCommandEnvironment } from '../operations/services/config-runtime.js';
+import { ensureGeneratedWranglerConfig } from '../operations/services/deploy.js';
+import { loadTreeseedDeployConfig } from '../platform/deploy/config.js';
+import { createTenantWatchEntries, isEditablePackageWorkspace, startPollingWatch, stopManagedProcess, writeDevReloadStamp, workspaceSdkRoot, } from '../operations/services/watch-dev.js';
+const tenantRoot = process.cwd();
+const cliArgs = process.argv.slice(2);
+const watchMode = cliArgs.includes('--watch');
+const wranglerArgs = cliArgs.filter((arg) => arg !== '--watch');
+let wranglerChild = null;
+let stopWatching = null;
+let isStoppingForRebuild = false;
+let shuttingDown = false;
+function shouldEnsureMailpit() {
+    if (process.env.TREESEED_DEV_FORCE_MAILPIT === '1') {
+        return true;
+    }
+    return loadTreeseedDeployConfig().smtp?.enabled === true;
+}
+function runStep(command, args, { cwd = tenantRoot, env = {}, fatal = true } = {}) {
+    const result = spawnSync(command, args, {
+        stdio: 'inherit',
+        cwd,
+        env: { ...process.env, ...env },
+    });
+    if (result.status !== 0 && fatal) {
+        process.exit(result.status ?? 1);
+    }
+    return result.status === 0;
+}
+function runNodeScript(scriptPath, args = [], options = {}) {
+    return runStep(process.execPath, [scriptPath, ...args], options);
+}
+function runTenantBuildCycle({ includePackageBuild = false, includeSdkBuild = false, fatal = true } = {}) {
+    const envOverrides = ['TREESEED_LOCAL_DEV_MODE=cloudflare'];
+    if (watchMode) {
+        envOverrides.push('TREESEED_PUBLIC_DEV_WATCH_RELOAD=true');
+    }
+    if (includeSdkBuild && isEditablePackageWorkspace()) {
+        const sdkRoot = workspaceSdkRoot();
+        if (sdkRoot) {
+            const sdkBuilt = runStep('npm', ['run', 'build:dist'], {
+                cwd: sdkRoot,
+                fatal,
+            });
+            if (!sdkBuilt) {
+                return false;
+            }
+        }
+    }
+    if (includePackageBuild && isEditablePackageWorkspace()) {
+        const distBuilt = runStep('npm', ['run', 'build:dist'], {
+            cwd: corePackageRoot,
+            fatal,
+        });
+        if (!distBuilt) {
+            return false;
+        }
+    }
+    const buildScripts = [
+        ['patch-starlight-content-path', []],
+        ['aggregate-book', []],
+        ['sync-dev-vars', envOverrides],
+        ['tenant-d1-migrate-local', []],
+    ];
+    if (shouldEnsureMailpit()) {
+        buildScripts.splice(2, 0, ['ensure-mailpit', []]);
+    }
+    for (const [scriptName, args] of buildScripts) {
+        const ok = runNodeScript(packageScriptPath(scriptName), args, { fatal });
+        if (!ok) {
+            return false;
+        }
+    }
+    ensureGeneratedWranglerConfig(tenantRoot);
+    if (watchMode) {
+        writeDevReloadStamp(tenantRoot);
+    }
+    const built = runNodeScript(packageScriptPath('tenant-build'), [], {
+        fatal,
+        env: watchMode ? { TREESEED_PUBLIC_DEV_WATCH_RELOAD: 'true' } : {},
+    });
+    if (!built) {
+        return false;
+    }
+    return true;
+}
+function startWrangler() {
+    const { wranglerPath } = ensureGeneratedWranglerConfig(tenantRoot);
+    const child = spawnNodeBinary(resolveWranglerBin(), ['dev', '--local', '--config', wranglerPath, ...wranglerArgs], {
+        cwd: tenantRoot,
+        env: watchMode ? { TREESEED_PUBLIC_DEV_WATCH_RELOAD: 'true' } : {},
+        detached: process.platform !== 'win32',
+    });
+    wranglerChild = child;
+    child.on('exit', (code, signal) => {
+        if (child !== wranglerChild) {
+            return;
+        }
+        wranglerChild = null;
+        if (isStoppingForRebuild || shuttingDown) {
+            return;
+        }
+        if (stopWatching) {
+            stopWatching();
+        }
+        if (signal) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exit(code ?? 0);
+    });
+}
+async function restartWranglerAfterBuild() {
+    if (wranglerChild) {
+        isStoppingForRebuild = true;
+        await stopManagedProcess(wranglerChild);
+        isStoppingForRebuild = false;
+    }
+    if (!shuttingDown) {
+        startWrangler();
+    }
+}
+async function shutdownAndExit(code = 0) {
+    shuttingDown = true;
+    if (stopWatching) {
+        stopWatching();
+    }
+    await stopManagedProcess(wranglerChild);
+    process.exit(code);
+}
+process.on('SIGINT', () => {
+    void shutdownAndExit(130);
+});
+process.on('SIGTERM', () => {
+    void shutdownAndExit(143);
+});
+process.env.TREESEED_LOCAL_DEV_MODE = process.env.TREESEED_LOCAL_DEV_MODE ?? 'cloudflare';
+applyTreeseedEnvironmentToProcess({ tenantRoot, scope: 'local', override: true });
+assertTreeseedCommandEnvironment({ tenantRoot, scope: 'local', purpose: 'dev' });
+runTenantBuildCycle({
+    includeSdkBuild: isEditablePackageWorkspace(),
+    includePackageBuild: isEditablePackageWorkspace(),
+    fatal: true,
+});
+startWrangler();
+if (watchMode) {
+    console.log('Starting unified Wrangler watch mode. Changes will rebuild the app and refresh the browser.');
+    stopWatching = startPollingWatch({
+        watchEntries: createTenantWatchEntries(tenantRoot),
+        onChange: async ({ changedPaths, packageChanged, sdkChanged }) => {
+            console.log(`Detected ${changedPaths.length} change${changedPaths.length === 1 ? '' : 's'}; rebuilding ${sdkChanged ? 'sdk, core, and tenant' : packageChanged ? 'core and tenant' : 'tenant'} output...`);
+            isStoppingForRebuild = true;
+            await stopManagedProcess(wranglerChild);
+            isStoppingForRebuild = false;
+            const ok = runTenantBuildCycle({
+                includeSdkBuild: sdkChanged,
+                includePackageBuild: packageChanged || sdkChanged,
+                fatal: false,
+            });
+            if (ok) {
+                startWrangler();
+                console.log('Rebuild complete. Wrangler restarted with the updated output.');
+            }
+            else {
+                console.error('Rebuild failed. Wrangler remains stopped until the next successful save.');
+            }
+        },
+    });
+}

package/dist/scripts/tenant-lint.js

@@ -0,0 +1,4 @@
+import { packageScriptPath, runNodeScript } from '../operations/services/runtime-tools.js';
+runNodeScript(packageScriptPath('cleanup-markdown'), ['--check'], {
+    cwd: process.cwd(),
+});

package/dist/scripts/tenant-test.js

@@ -0,0 +1,4 @@
+import { packageScriptPath, runNodeScript } from '../operations/services/runtime-tools.js';
+runNodeScript(packageScriptPath('tenant-check'), [], {
+    cwd: process.cwd(),
+});

package/dist/scripts/test-cloudflare-local.js

@@ -0,0 +1,212 @@
+import assert from 'node:assert/strict';
+import { mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { prepareCloudflareLocalRuntime, spawnProcess, startWranglerDev } from '../operations/services/local-dev.js';
+import { fixtureRoot, fixtureWranglerConfig } from '../operations/services/runtime-paths.js';
+const TEST_PORT = 8791;
+const BASE_URL = `http://127.0.0.1:${TEST_PORT}`;
+const RUN_ID = `${Date.now()}-${process.pid}`;
+const ipSeed = Date.now() + process.pid;
+const TEST_IP = `198.51.${(ipSeed >>> 8) % 250}.${ipSeed % 250}`;
+const TEST_EMAIL = `integration-subscriber-${RUN_ID}@localhost.test`;
+const PERSIST_TO = resolve(process.cwd(), '.local', 'cloudflare-integration', RUN_ID);
+const workerLogs = [];
+mkdirSync(PERSIST_TO, { recursive: true });
+function captureLogs(stream, label) {
+    if (!stream) {
+        return;
+    }
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        workerLogs.push(`[${label}] ${chunk}`);
+        if (workerLogs.length > 40) {
+            workerLogs.shift();
+        }
+    });
+}
+function readBody(message) {
+    return new Promise((resolve) => {
+        let body = '';
+        message.setEncoding('utf8');
+        message.on('data', (chunk) => {
+            body += chunk;
+        });
+        message.on('end', () => resolve(body));
+    });
+}
+function extractSetCookie(response) {
+    if (typeof response.headers.getSetCookie === 'function') {
+        return response.headers.getSetCookie();
+    }
+    const cookie = response.headers.get('set-cookie');
+    return cookie ? [cookie] : [];
+}
+async function waitForWorker(worker) {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+        if (worker.exitCode !== null) {
+            throw new Error(`Wrangler exited before the worker became ready (exit ${worker.exitCode}).\n${workerLogs.join('')}`);
+        }
+        try {
+            const response = await fetch(`${BASE_URL}/api/form/submit?formType=subscribe`, {
+                signal: AbortSignal.timeout(5000),
+                headers: {
+                    'x-forwarded-for': TEST_IP,
+                },
+            });
+            if (response.ok) {
+                return;
+            }
+        }
+        catch {
+            // Keep polling until the local worker is ready.
+        }
+        await delay(1000);
+    }
+    throw new Error(`Timed out waiting for local Wrangler dev to start.\n${workerLogs.join('')}`);
+}
+async function issueToken() {
+    const response = await fetch(`${BASE_URL}/api/form/submit?formType=subscribe`, {
+        signal: AbortSignal.timeout(10000),
+        headers: {
+            'x-forwarded-for': TEST_IP,
+        },
+    });
+    assert.equal(response.status, 200, 'token endpoint should return HTTP 200');
+    const payload = await response.json();
+    const cookies = extractSetCookie(response);
+    assert.equal(payload.ok, true, 'token payload should be ok');
+    assert.ok(payload.formToken, 'token endpoint should return a form token');
+    assert.ok(payload.sessionId, 'token endpoint should return a session id');
+    assert.ok(cookies.length > 0, 'token endpoint should set a session cookie');
+    return {
+        formToken: payload.formToken,
+        sessionId: payload.sessionId,
+        cookieHeader: cookies.map((cookie) => cookie.split(';', 1)[0]).join('; '),
+    };
+}
+async function submitSubscribeForm({ formToken, sessionId, cookieHeader }, email = TEST_EMAIL) {
+    const form = new FormData();
+    form.set('formType', 'subscribe');
+    form.set('name', 'Integration Test');
+    form.set('email', email);
+    form.set('formToken', formToken);
+    form.set('formSession', sessionId);
+    form.set('redirectTo', '/');
+    return fetch(`${BASE_URL}/api/form/submit`, {
+        method: 'POST',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(10000),
+        headers: {
+            cookie: cookieHeader,
+            origin: BASE_URL,
+            referer: `${BASE_URL}/`,
+            'x-forwarded-for': TEST_IP,
+        },
+        body: form,
+    });
+}
+async function querySubscribers() {
+    const query = `SELECT lookup_key AS email, status, json_extract(payload_json, '$.source') AS source FROM runtime_records WHERE record_type = 'subscription' AND lookup_key = '${TEST_EMAIL}'`;
+    const child = spawnProcess('wrangler', [
+        'd1',
+        'execute',
+        'karyon-docs-site-data',
+        '--local',
+        '--config',
+        fixtureWranglerConfig,
+        '--persist-to',
+        PERSIST_TO,
+        '--json',
+        '--command',
+        query,
+    ], { stdio: ['ignore', 'pipe', 'inherit'], cwd: fixtureRoot });
+    const stdout = await readBody(child.stdout);
+    const exitCode = await new Promise((resolve) => {
+        child.on('exit', resolve);
+    });
+    assert.equal(exitCode, 0, 'local D1 query should succeed');
+    const parsed = JSON.parse(stdout);
+    const results = Array.isArray(parsed) ? parsed : [parsed];
+    const rows = results.flatMap((entry) => entry.results ?? []);
+    return rows;
+}
+async function main() {
+    prepareCloudflareLocalRuntime({
+        persistTo: PERSIST_TO,
+        envOverrides: {
+            TREESEED_LOCAL_DEV_MODE: 'cloudflare',
+            TREESEED_FORMS_LOCAL_BYPASS_TURNSTILE: 'true',
+            TREESEED_PUBLIC_FORMS_LOCAL_BYPASS_TURNSTILE: 'true',
+            TREESEED_FORMS_LOCAL_BYPASS_CLOUDFLARE_GUARDS: 'false',
+            TREESEED_FORMS_LOCAL_USE_MAILPIT: 'true',
+            TREESEED_MAILPIT_SMTP_HOST: '127.0.0.1',
+            TREESEED_MAILPIT_SMTP_PORT: '1025',
+        },
+    });
+    const worker = startWranglerDev(['--port', String(TEST_PORT), '--persist-to', PERSIST_TO], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    captureLogs(worker.stdout, 'stdout');
+    captureLogs(worker.stderr, 'stderr');
+    const teardown = async () => {
+        if (worker.exitCode === null && !worker.killed) {
+            worker.kill('SIGTERM');
+            await Promise.race([
+                new Promise((resolve) => worker.once('exit', resolve)),
+                delay(5000),
+            ]);
+            if (worker.exitCode === null && !worker.killed) {
+                worker.kill('SIGKILL');
+                await Promise.race([
+                    new Promise((resolve) => worker.once('exit', resolve)),
+                    delay(5000),
+                ]);
+            }
+        }
+    };
+    process.on('SIGINT', async () => {
+        await teardown();
+        process.exit(130);
+    });
+    process.on('SIGTERM', async () => {
+        await teardown();
+        process.exit(143);
+    });
+    let shouldQuerySubscribers = false;
+    try {
+        await waitForWorker(worker);
+        const firstToken = await issueToken();
+        const firstResponse = await submitSubscribeForm(firstToken);
+        assert.equal(firstResponse.status, 303, 'subscribe submit should redirect');
+        assert.match(firstResponse.headers.get('location') ?? '', /\/\?formStatus=success&formCode=success#site-subscribe$/, 'subscribe success redirect should include success markers');
+        shouldQuerySubscribers = true;
+        const replayResponse = await submitSubscribeForm(firstToken);
+        assert.equal(replayResponse.status, 303, 'replayed submit should still redirect');
+        assert.match(replayResponse.headers.get('location') ?? '', /\/\?formStatus=error&formCode=token_replayed#site-subscribe$/, 'replayed token should be rejected by KV-backed nonce storage');
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const token = await issueToken();
+            const response = await submitSubscribeForm(token);
+            assert.equal(response.status, 303, 'pre-limit submissions should redirect');
+            assert.match(response.headers.get('location') ?? '', /\/\?formStatus=success&formCode=success#site-subscribe$/, 'pre-limit submissions should succeed');
+        }
+        const limitedToken = await issueToken();
+        const limitedResponse = await submitSubscribeForm(limitedToken);
+        assert.equal(limitedResponse.status, 303, 'rate-limited submit should redirect');
+        assert.match(limitedResponse.headers.get('location') ?? '', /\/\?formStatus=error&formCode=rate_limited#site-subscribe$/, 'local KV-backed rate limiting should reject the fourth submission');
+    }
+    finally {
+        await teardown();
+    }
+    if (shouldQuerySubscribers) {
+        const rows = await querySubscribers();
+        assert.equal(rows.length, 1, 'subscriber should be written to local D1');
+        assert.equal(rows[0].email, TEST_EMAIL, 'subscriber email should match the submitted address');
+        assert.equal(rows[0].status, 'active', 'subscriber should be active');
+        assert.equal(rows[0].source, 'footer', 'subscriber source should be tracked');
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});