@astralarium/repo-dev 0.0.0-stage → 0.1.0

package/dist/testkit/env-template.d.ts

@@ -0,0 +1,8 @@
+import type { DevConfig } from "../config.ts";
+/** Sorted key differences between `file` and the keys the launcher reads for `app`. */
+export declare function overrideTemplateGaps(app: DevConfig, file?: string): {
+    /** Override keys absent from the template. */
+    missing: string[];
+    /** Template keys the launcher ignores. */
+    extra: string[];
+};

package/dist/testkit/env-template.js

@@ -0,0 +1,14 @@
+/** `.env.tmpl` coverage of the launcher's override keys. */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseEnv } from "node:util";
+import { overrideKeys } from "../launcher/launcher.js";
+/** Sorted key differences between `file` and the keys the launcher reads for `app`. */
+export function overrideTemplateGaps(app, file = resolve(app.root, ".env.tmpl")) {
+    const template = Object.keys(parseEnv(readFileSync(file, "utf8")));
+    const keys = overrideKeys(app);
+    return {
+        missing: keys.filter((key) => !template.includes(key)).sort(),
+        extra: template.filter((key) => !keys.includes(key)).sort(),
+    };
+}

package/dist/testkit/index.d.ts

@@ -0,0 +1,8 @@
+/** Test support: built-worker checks and suite, `.env.tmpl` coverage,
+ *  loopback ports, per-test temp dirs and turbo test caching. */
+export { type BuiltWorkerConfig, findInBundle, type FindInBundleOptions, readBuiltWorkerConfig, requiredSecrets, } from "./built-worker.ts";
+export * from "./env-template.ts";
+export * from "./ports.ts";
+export * from "./temp.ts";
+export * from "./test-cache.ts";
+export * from "./worker-build.ts";

package/dist/testkit/index.js

@@ -0,0 +1,8 @@
+/** Test support: built-worker checks and suite, `.env.tmpl` coverage,
+ *  loopback ports, per-test temp dirs and turbo test caching. */
+export { findInBundle, readBuiltWorkerConfig, requiredSecrets, } from "./built-worker.js";
+export * from "./env-template.js";
+export * from "./ports.js";
+export * from "./temp.js";
+export * from "./test-cache.js";
+export * from "./worker-build.js";

package/dist/testkit/ports.d.ts

@@ -0,0 +1,8 @@
+/** Loopback ports for allocation tests. */
+import { type Server } from "node:net";
+/** A loopback port held open by a server pushed onto `held`. */
+export declare function heldPort(held: Server[]): Promise<number>;
+/** A loopback port free at the time of the call. */
+export declare function freePort(): Promise<number>;
+/** Closes every server in `held`, emptying it. */
+export declare function releasePorts(held: Server[]): Promise<unknown>;

package/dist/testkit/ports.js

@@ -0,0 +1,20 @@
+/** Loopback ports for allocation tests. */
+import { createServer } from "node:net";
+/** A loopback port held open by a server pushed onto `held`. */
+export async function heldPort(held) {
+    const server = createServer();
+    held.push(server);
+    await new Promise((done) => server.listen(0, "127.0.0.1", done));
+    return server.address().port;
+}
+/** A loopback port free at the time of the call. */
+export async function freePort() {
+    const held = [];
+    const port = await heldPort(held);
+    await new Promise((done) => held[0].close(done));
+    return port;
+}
+/** Closes every server in `held`, emptying it. */
+export function releasePorts(held) {
+    return Promise.all(held.splice(0).map((server) => new Promise((done) => server.close(done))));
+}

package/dist/testkit/temp.d.ts

@@ -0,0 +1,2 @@
+/** A fresh directory under the OS temp dir, removed when the current test finishes. */
+export declare function tempDir(prefix: string): string;

package/dist/testkit/temp.js

@@ -0,0 +1,10 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { onTestFinished } from "vitest";
+/** A fresh directory under the OS temp dir, removed when the current test finishes. */
+export function tempDir(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
+    return dir;
+}

package/dist/testkit/test-cache.d.ts

@@ -0,0 +1,14 @@
+/** A workspace's turbo wiring under test. */
+export interface TestCachingOptions {
+    /** Root `turbo.json` text: `//#siblings:inputs`, `inputs`, `test` and
+     *  `db:image` tasks. */
+    rootTurbo: string;
+    /** `turbo.json` text of the app whose tests read the database image. */
+    appTurbo: string;
+    /** Package whose `db:image` writes `.turbo/db-image.json`. */
+    imagePackage: string;
+}
+/** Runs turbo over a fixture workspace wired by `options`, asserting each
+ *  test reruns exactly when its database image, sources or sibling assets
+ *  change; throws on the first miss. */
+export declare function assertTestCaching({ rootTurbo, appTurbo, imagePackage, }: TestCachingOptions): void;

package/dist/testkit/test-cache.js

@@ -0,0 +1,174 @@
+/** Turbo test caching over a fixture workspace: database image, sibling
+ *  sources and dependency edges invalidate exactly the tests they feed. */
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tempDir } from "./temp.js";
+const require = createRequire(import.meta.url);
+/** `@astralarium/repo-dev`, as the fixture's `siblings:inputs` imports it for
+ *  `writeSiblingInputs`. */
+const SIBLING_INPUTS = pathToFileURL(require.resolve("@astralarium/repo-dev")).href;
+/** Runs turbo over a fixture workspace wired by `options`, asserting each
+ *  test reruns exactly when its database image, sources or sibling assets
+ *  change; throws on the first miss. */
+export function assertTestCaching({ rootTurbo, appTurbo, imagePackage, }) {
+    const dir = tempDir("test-cache-");
+    const root = join(dir, "repo");
+    const upstream = join(dir, "upstream-image");
+    const assets = join(dir, "assets");
+    const write = (path, contents) => {
+        const target = join(root, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, contents);
+    };
+    write("package.json", JSON.stringify({
+        name: "cache-fixture",
+        private: true,
+        packageManager: "pnpm@10.18.1",
+        scripts: {
+            "siblings:inputs": "node siblings.cjs",
+        },
+    }));
+    write("pnpm-workspace.yaml", "packages:\n  - apps/*\n  - packages/*\n");
+    const sharedPackage = (consumesAssets) => {
+        write("packages/shared/package.json", JSON.stringify({
+            name: "@repo/new-assets-consumer",
+            scripts: { test: "node test.cjs" },
+            ...(consumesAssets
+                ? { dependencies: { "@repo/assets": "link:../../../assets" } }
+                : {}),
+        }));
+        write("pnpm-lock.yaml", `lockfileVersion: '9.0'
+importers:
+  .: {}
+  packages/image: {}
+  packages/unrelated: {}
+  packages/shared:${consumesAssets
+            ? `
+    dependencies:
+      '@repo/assets':
+        specifier: link:../../../assets
+        version: link:../../../assets`
+            : " {}"}
+  apps/web:
+    dependencies:
+      '${imagePackage}':
+        specifier: workspace:*
+        version: link:../../packages/image
+      '@repo/new-assets-consumer':
+        specifier: workspace:*
+        version: link:../../packages/shared
+`);
+    };
+    sharedPackage(false);
+    write(".gitignore", ".turbo/\n");
+    write("turbo.json", rootTurbo);
+    write("apps/web/turbo.json", appTurbo);
+    write("siblings.cjs", `import(${JSON.stringify(SIBLING_INPUTS)})
+  .then(({ writeSiblingInputs }) => writeSiblingInputs(process.cwd(), [
+    { package: "@repo/assets", dir: ${JSON.stringify(assets)}, sources: ["package.json", "runtime"] },
+  ]));
+`);
+    write("packages/image/package.json", JSON.stringify({
+        name: imagePackage,
+        scripts: { "db:image": "node image.cjs" },
+    }));
+    write("packages/image/image.cjs", `const fs = require('node:fs');
+const image = fs.readFileSync(${JSON.stringify(upstream)}, 'utf8');
+if (image === 'unavailable') process.exit(1);
+fs.mkdirSync('.turbo', { recursive: true });
+fs.writeFileSync('.turbo/db-image.json', JSON.stringify({ image }));
+fs.appendFileSync('.turbo/builds', 'build\\n');
+`);
+    write("packages/unrelated/package.json", JSON.stringify({
+        name: "@repo/unrelated",
+        scripts: { test: "node test.cjs" },
+    }));
+    for (const name of ["shared", "unrelated"])
+        write(`packages/${name}/test.cjs`, `const fs = require('node:fs');
+fs.mkdirSync('.turbo', { recursive: true });
+fs.appendFileSync('.turbo/executions', 'run\\n');
+`);
+    write("packages/shared/source.ts", "export const value = 1;\n");
+    write("apps/web/package.json", JSON.stringify({
+        name: "web",
+        dependencies: {
+            [imagePackage]: "workspace:*",
+            "@repo/new-assets-consumer": "workspace:*",
+        },
+        scripts: { test: "node test.cjs" },
+    }));
+    write("apps/web/test.cjs", `const fs = require('node:fs');
+const { image } = JSON.parse(fs.readFileSync('../../packages/image/.turbo/db-image.json', 'utf8'));
+fs.mkdirSync('.turbo', { recursive: true });
+fs.appendFileSync('.turbo/executions', image + '\\n');
+`);
+    execFileSync("git", ["init", "--quiet", root]);
+    mkdirSync(join(assets, "runtime"), { recursive: true });
+    execFileSync("git", ["init", "--quiet", assets]);
+    writeFileSync(join(assets, "package.json"), JSON.stringify({ name: "@repo/assets" }));
+    const assetSource = join(assets, "runtime/model.ts");
+    // The fixture's turbo owns its caching: an ambient `TURBO_FORCE`
+    // would rerun every task.
+    const env = { ...process.env };
+    for (const key of Object.keys(env))
+        if (key.startsWith("TURBO_"))
+            delete env[key];
+    const run = (args = []) => execFileSync(process.execPath, [
+        require.resolve("turbo"),
+        "run",
+        "test",
+        "--continue=dependencies-successful",
+        ...args,
+        "--cache=local:rw",
+        "--ui=stream",
+    ], { cwd: root, env, encoding: "utf8", stdio: "pipe", timeout: 60_000 });
+    const executions = () => readFileSync(join(root, "apps/web/.turbo/executions"), "utf8");
+    const sharedExecutions = () => readFileSync(join(root, "packages/shared/.turbo/executions"), "utf8");
+    const unrelatedExecutions = () => readFileSync(join(root, "packages/unrelated/.turbo/executions"), "utf8");
+    writeFileSync(upstream, "first");
+    writeFileSync(assetSource, "original-assets");
+    run();
+    run();
+    assert.equal(executions(), "first\n");
+    writeFileSync(upstream, "second");
+    run();
+    assert.equal(executions(), "first\nsecond\n");
+    write("packages/shared/source.ts", "export const value = 2;\n");
+    run();
+    assert.equal(executions(), "first\nsecond\nsecond\n");
+    sharedPackage(true);
+    run();
+    assert.equal(executions(), "first\nsecond\nsecond\nsecond\n");
+    const unrelatedBeforeAssets = unrelatedExecutions();
+    writeFileSync(assetSource, "changed-assets");
+    run(["--filter=@repo/new-assets-consumer"]);
+    assert.equal(sharedExecutions(), "run\n".repeat(4));
+    assert.equal(executions(), "first\n" + "second\n".repeat(3));
+    run();
+    assert.equal(executions(), "first\n" + "second\n".repeat(4));
+    assert.equal(sharedExecutions(), "run\n".repeat(4));
+    assert.equal(unrelatedExecutions(), unrelatedBeforeAssets);
+    rmSync(join(root, "packages/image/.turbo/db-image.json"));
+    rmSync(join(root, "packages/shared/.turbo/siblings.json"));
+    run();
+    assert.equal(executions(), "first\n" + "second\n".repeat(4));
+    sharedPackage(false);
+    run();
+    assert.equal(executions(), "first\n" + "second\n".repeat(4));
+    assert.equal(sharedExecutions(), "run\n".repeat(4));
+    const unrelatedAfterRemoval = unrelatedExecutions();
+    writeFileSync(assetSource, "assets-with-no-consumers");
+    run();
+    assert.equal(executions(), "first\n" + "second\n".repeat(4));
+    assert.equal(sharedExecutions(), "run\n".repeat(4));
+    assert.equal(unrelatedExecutions(), unrelatedAfterRemoval);
+    assert.equal(readFileSync(join(root, "packages/image/.turbo/builds"), "utf8"), "build\n".repeat(9));
+    writeFileSync(upstream, "unavailable");
+    write("packages/shared/source.ts", "export const value = 3;\n");
+    assert.throws(() => run());
+    assert.equal(executions(), "first\n" + "second\n".repeat(4));
+}

package/dist/testkit/worker-build.d.ts

@@ -0,0 +1,26 @@
+/** A client of a running worker: its answer to a GET of `path`. */
+export type WorkerRequester = (path: string) => Promise<{
+    status: number;
+    body: {
+        cancel(): Promise<void>;
+    } | null;
+}>;
+/** What `testWorkerBuild` runs against. */
+export interface WorkerBuildSuite {
+    /** App directory: source `wrangler.jsonc`, the deployment worker built
+     *  in `dist/server/`, the prerender worker in `dist/prerender/`. */
+    root: string;
+    /** Wrangler env the build targets; top level when absent. Env blocks
+     *  replace bindings. */
+    env?: string;
+    /** Text only dev servers carry; absent from the deployment bundle. */
+    devOnly: readonly string[];
+    /** The built prerender worker: a client of it running with inherited
+     *  connection settings, and a database-backed page. */
+    prerender?: {
+        request: WorkerRequester;
+        databasePath: string;
+    };
+}
+/** Tests of an app's built workers against its source wrangler config. */
+export declare function testWorkerBuild({ root, env, devOnly, prerender, }: WorkerBuildSuite): void;

package/dist/testkit/worker-build.js

@@ -0,0 +1,46 @@
+/** Test suite of an app's built workers: the deployment worker keeps
+ *  what its wrangler config declares; the prerender worker runs without
+ *  bindings or secrets. */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import JSON5 from "json5";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { BuiltWorkerConfig, findInBundle, readBuiltWorkerConfig, } from "./built-worker.js";
+/** The declarations of a wrangler config block a build must keep. */
+const Declarations = BuiltWorkerConfig.omit({ vars: true });
+/** A source wrangler config: top-level block and named envs. */
+const SourceConfig = Declarations.extend({
+    env: z.record(z.string(), Declarations).default({}),
+});
+/** Tests of an app's built workers against its source wrangler config. */
+export function testWorkerBuild({ root, env, devOnly, prerender, }) {
+    const source = join(root, "wrangler.jsonc");
+    const deployment = join(root, "dist/server");
+    describe("worker build", () => {
+        test("the deployment worker keeps the Hyperdrive bindings and required secrets its wrangler config declares", async () => {
+            const config = SourceConfig.parse(JSON5.parse(await readFile(source, "utf8")));
+            const declared = env ? config.env[env] : config;
+            if (!declared)
+                throw new Error(`${source} declares no env.${env}`);
+            const built = await readBuiltWorkerConfig(deployment);
+            expect(built.hyperdrive.map(({ binding }) => binding)).toEqual(expect.arrayContaining(declared.hyperdrive.map(({ binding }) => binding)));
+            expect(built.secrets.required).toEqual(expect.arrayContaining(declared.secrets.required));
+        });
+        test.each(devOnly)("the deployment worker bundle omits dev-only %s", async (needle) => {
+            expect(await findInBundle(deployment, needle)).toEqual([]);
+        });
+        if (!prerender)
+            return;
+        test("the prerender worker declares no Hyperdrive bindings or required secrets", async () => {
+            const built = await readBuiltWorkerConfig(join(root, "dist/prerender"));
+            expect(built.hyperdrive).toEqual([]);
+            expect(built.secrets.required).toEqual([]);
+        });
+        test("the prerender worker refuses database-backed pages despite inherited connection settings", async () => {
+            const response = await prerender.request(prerender.databasePath);
+            expect(response.status).toBe(500);
+            await response.body?.cancel();
+        });
+    });
+}

package/dist/vite.d.ts

@@ -0,0 +1,96 @@
+import { type ConfigEnv, type Plugin, type UserConfig } from "vite";
+/**
+ * Listener of a launched app (`listenerEnv`): dev servers serve on
+ * `SITE_ORIGIN`'s port, over HTTPS with `SSL_KEY` / `SSL_CERT`; every
+ * server binds `DEV_SERVER_HOST` (default `localhost`) on a strict port
+ * and allows the `LOCAL_ORIGINS` hostnames. Config comes from process env:
+ * Vite reads no dot-env file.
+ */
+export declare function devListener({ command, isPreview, mode }: ConfigEnv, env?: NodeJS.ProcessEnv): Pick<UserConfig, "envDir" | "server">;
+/** `@cloudflare/vite-plugin` options `cloudflareDevOptions` sets. */
+interface CloudflareDevOptions {
+    persistState?: false;
+    inspectorPort?: number | false;
+}
+/**
+ * Cloudflare Vite plugin options of a launched app: a `testEnv` build
+ * (`CLOUDFLARE_ENV`, the Vitest fixtures') keeps no state and opens no
+ * inspector; other servers open `DEV_INSPECTOR_PORT` (`listenerEnv`), or
+ * none when it is blank or unset.
+ */
+export declare function cloudflareDevOptions({ testEnv, env, }?: {
+    /** Wrangler environment of Vitest fixture builds. */
+    testEnv?: string;
+    env?: NodeJS.ProcessEnv;
+}): CloudflareDevOptions;
+/**
+ * Fails a build shipping dev files or test support, or server-only
+ * modules in a client environment (`isDevFile`, `isTestFile`,
+ * `isServerFile` from `@astralarium/repo-package-files`). Dev assets never inline,
+ * so they emit and fail; library builds inline every asset, skipping
+ * the check.
+ */
+export declare function buildGuard(): Plugin;
+/**
+ * Keeps dev classes out of built CSS: appends `@source not` for each
+ * workspace package's dev folders (`isDevFile`) to every Tailwind entry
+ * (CSS importing `tailwindcss`). Precedes `tailwindcss()`. Skips
+ * `?url`/`?raw`, which wrap the CSS as JS.
+ */
+export declare function tailwindDevSources(): Plugin;
+/**
+ * Reuses the compiled SSR bundle inside an isolated prerender worker: the
+ * prerender environment's `entry` re-exports the SSR build's
+ * `wrangler.json` `main`, emitted under `runtime/`. Requires the Cloudflare
+ * Vite plugin: its entry worker builds as the `ssr` environment (TanStack
+ * Start's server) and writes `wrangler.json`; its
+ * `experimental.prerenderWorker` builds as `environment`.
+ */
+export declare function prerenderRuntime({ entry, environment, }: {
+    /** Server entry module, relative to the Vite root. */
+    entry: string;
+    /** Prerender worker's Vite environment. */
+    environment?: string;
+}): Plugin;
+/** The Cloudflare Vite plugin's built entry worker, as its
+ *  `prerenderWorker.config` callback receives it. */
+interface PrerenderEntryWorker {
+    main: string | undefined;
+    compatibility_date: string;
+    compatibility_flags: string[];
+    vars: Readonly<Record<string, unknown>>;
+}
+/** Prerender worker config: the entry worker's bundle and public `vars`. */
+interface PrerenderWorker {
+    name: string;
+    main: string | undefined;
+    compatibility_date: string;
+    compatibility_flags: string[];
+    /** Empty: wrangler reads only declared vars and required secrets from
+     *  `.dev.vars`, `.env` and process env. */
+    secrets: {
+        required: [];
+    };
+    vars: Record<string, string>;
+}
+/**
+ * Isolates the prerender worker from runtime bindings and secrets: the
+ * Cloudflare Vite plugin's `experimental.prerenderWorker.config`. The
+ * worker runs the entry worker's bundle (`main`, compatibility date and
+ * flags) with `vars` as its whole environment; the entry worker's
+ * bindings, other vars, and required secrets stay behind.
+ */
+export declare function prerenderWorkerConfig({ name, vars, }: {
+    /** Worker name. */
+    name: string;
+    /** Public vars, from the entry worker's `vars`; throws on an invalid one. */
+    vars: (entryVars: Readonly<Record<string, unknown>>) => Record<string, string>;
+}): (config: unknown, context: {
+    entryWorkerConfig: PrerenderEntryWorker;
+}) => PrerenderWorker;
+/**
+ * Re-transforms a deleted file's importers, so a rename reaches them.
+ * Vite soft-invalidates them: their code keeps the deleted import path.
+ */
+export declare function renameRecovery(): Plugin;
+export {};