@astralarium/repo-dev 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astralarium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# `@astralarium/repo-dev`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local dev launcher.
+Apps declare one `DevConfig` (`defineDevConfig`).
+
+Needs [live](https://github.com/astralarium/live), mkcert,
+and Podman or Docker for an app with a database.
+
+```sh
+pnpm dev [start|stop|build|certs|reset]
+```
+
+Rerun `start` to apply config changes.
+Checkouts get a database, ports and hostname:
+`<worktree>.<domain>.localhost` for a git worktree.
+`DEV_LAN=1` also serves `<stem>.local` over mDNS.
+
+Logs: `live ps`, `live tail -n 60 <server>`.

package/dist/allocation.d.ts

@@ -0,0 +1,15 @@
+import { type DatabaseAllocation } from "./config.ts";
+/** Generated per-checkout dev state: `<root>/.local/`. */
+export declare function localDir(root: string): string;
+/** Per-checkout dev resources, persisted in `<localDir>/dev.json`. */
+export interface Allocation {
+    /** The dev database; absent for an app without one. */
+    database?: DatabaseAllocation;
+    /** Dev server port by `live` session name. */
+    ports: Record<string, number>;
+    /** Debugger port by `live` session name, for servers declaring one. */
+    inspectorPorts: Record<string, number>;
+}
+/** Saved allocation in `<local>/dev.json`; missing or invalid content
+ *  counts as none. */
+export declare function readAllocation(local: string): Partial<Allocation>;

package/dist/allocation.js

@@ -0,0 +1,28 @@
+/** Per-checkout dev resources the launcher allocates. */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { z } from "zod";
+import { PORT } from "./config.js";
+/** Generated per-checkout dev state: `<root>/.local/`. */
+export function localDir(root) {
+    return resolve(root, ".local");
+}
+/** `dev.json` as saved: any field may be missing. */
+const savedAllocation = z
+    .object({
+    database: z.object({ name: z.string().min(1), port: PORT }),
+    ports: z.record(z.string(), PORT),
+    inspectorPorts: z.record(z.string(), PORT),
+})
+    .partial();
+/** Saved allocation in `<local>/dev.json`; missing or invalid content
+ *  counts as none. */
+export function readAllocation(local) {
+    try {
+        const result = savedAllocation.safeParse(JSON.parse(readFileSync(resolve(local, "dev.json"), "utf8")));
+        return result.success ? result.data : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/bin/db-image.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/db-image.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/** `db-image --app <module>`: writes the database image manifest test
+ *  runs select with `DB_TEST_IMAGE` to `.turbo/db-image.json` in the app
+ *  module's package. */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { appArgs } from "@astralarium/repo-deploy-info/server";
+import { nearestPackage } from "@astralarium/repo-package-files";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { loadDevConfig } from "../load-config.js";
+/** `.turbo/db-image.json` of the package holding `app`. */
+function imageManifest(app) {
+    const file = resolve(app);
+    const pkg = nearestPackage(file);
+    if (!pkg)
+        throw new ExpectedError(`${app}: outside a package`);
+    return pathToFileURL(resolve(pkg.dir, ".turbo/db-image.json"));
+}
+try {
+    const { app } = appArgs(process.argv.slice(2), "Usage: db-image --app <module>", { positionals: 0 });
+    const { database } = await loadDevConfig(app);
+    if (!database)
+        throw new ExpectedError(`${app}: dev config declares no database`);
+    database.writeTestImage(imageManifest(app));
+}
+catch (exception) {
+    log.error("db_image.failed", "db-image failed", { exception });
+    process.exitCode = 1;
+}

package/dist/bin/run-dev.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/run-dev.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/** `run-dev --app <module> [command]`: the launcher over the app module's
+ *  `dev` config; `--help` lists its commands. */
+import { appArgs } from "@astralarium/repo-deploy-info/server";
+import { log } from "@astralarium/repo-telemetry";
+import { main } from "../launcher/launcher.js";
+import { loadDevConfig } from "../load-config.js";
+try {
+    const { app, argv } = appArgs(process.argv.slice(2), "Usage: run-dev --app <module> [command] [options]");
+    await main(await loadDevConfig(app), argv);
+}
+catch (exception) {
+    log.error("run_dev.failed", "run-dev failed", { exception });
+    process.exitCode = 1;
+}

package/dist/bin/siblings-inputs.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/siblings-inputs.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/** `siblings-inputs --app <module>`: refreshes each workspace package's
+ *  sibling fingerprints (`.turbo/siblings.json`) before turbo hashes. */
+import { resolve } from "node:path";
+import { appArgs, loadCheckouts } from "@astralarium/repo-deploy-info/server";
+import { workspaceRoot } from "@astralarium/repo-package-files";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { writeSiblingInputs } from "../sibling-inputs.js";
+try {
+    const { app } = appArgs(process.argv.slice(2), "Usage: siblings-inputs --app <module>", { positionals: 0 });
+    const checkouts = await loadCheckouts(app);
+    const workspace = workspaceRoot(resolve(app));
+    if (!workspace)
+        throw new ExpectedError(`${app}: outside a pnpm workspace`);
+    writeSiblingInputs(workspace, Object.values(checkouts.siblings));
+}
+catch (exception) {
+    log.error("siblings_inputs.failed", "siblings-inputs failed", { exception });
+    process.exitCode = 1;
+}

package/dist/config.d.ts

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import type { ResourceScope } from "./resources.ts";
+/** Everything the shared dev tooling varies per app. */
+export interface DevConfig<Database extends DatabaseProvider | undefined = DatabaseProvider | undefined> {
+    /**
+     * Workspace root: the `pnpm-workspace.yaml` directory. Holds `.local/`
+     * and `pnpm-lock.yaml`; labels the resources this checkout owns.
+     */
+    root: string;
+    /** Command developers run the launcher as, for usage and hints: `pnpm dev`. */
+    program: string;
+    /** Hostname label every checkout serves under: `app` →
+     *  `app.localhost`, `feature-x.app.localhost`. */
+    domain: string;
+    /** The app's database; absent for an app without one. */
+    database?: Database;
+    /** Dev servers the launcher runs under `live`; names and ports unique. */
+    servers: readonly DevServerConfig[];
+    /** Keys a developer may set in `<root>/.env` or the shell, besides
+     *  `DEV_LAN`. */
+    overrideKeys: readonly string[];
+    /**
+     * Process environment per server name, derived from one allocation. The
+     * launcher adds the listener settings each server opts into
+     * (`listenerEnv`) under it.
+     */
+    environment(input: DevEnvironmentInput<Database>): Record<string, Record<string, string>>;
+    /** What `reset` deletes, as the usage text names it: "users, decks". */
+    data: string;
+}
+/**
+ * Database the launcher and the test harness provision; `@astralarium/repo-postgres/provision`
+ * implements Postgres. Instances are named per checkout; a test run gets a
+ * disposable one.
+ */
+export interface DatabaseProvider<Instance extends TestDatabase = TestDatabase> {
+    /** Default instance and image base name; `DB_NAME` and `--db-name` override it. */
+    name: string;
+    /**
+     * Claims the checkout's dev instance: `saved` while it still holds for
+     * `owner` (name claimable, port held by the owned running instance or
+     * free), else the next free name (`<base>-2`, …) and port.
+     */
+    allocate(input: DatabaseAllocationInput): Promise<DatabaseAllocation>;
+    /**
+     * Dev instance on persistent storage, schema current and the app's data
+     * loaded. `resources` stops an instance this call started; a running one
+     * is left alone.
+     */
+    ensure(resources: ResourceScope, options: EnsureDatabaseOptions): Promise<void>;
+    /** Deletes dev instance `name` and its data, then rebuilds `image` from refreshed bases. */
+    reset(name: string, image: string): void;
+    /** Stops dev instance `name` when `owner` may claim it; a missing runtime is fine. */
+    stop(name: string, owner: string): void;
+    /** Rebuilds `image` from refreshed bases. */
+    build(image: string): void;
+    /**
+     * Disposable instance on the current schema in the foreground, loaded
+     * from `snapshot` when given; prints its connection, resolves once
+     * removed.
+     */
+    runDisposable(options: DisposableDatabaseOptions): Promise<void>;
+    /** Writes a full dump of the source database, migrated onto the
+     *  current schema, to stdout; everything else goes to stderr. */
+    upgradeDump(options: UpgradeDumpOptions): Promise<void>;
+    /** The app's connection string to the dev instance. */
+    connectionString(allocation: DatabaseAllocation): string;
+    /** Disposable seeded instance for one test run; `resources` removes it. */
+    startTestInstance(resources: ResourceScope, name: string): Promise<Instance>;
+    /** Writes the image manifest test runs select with `DB_TEST_IMAGE`. */
+    writeTestImage(file: URL): void;
+}
+/** What `DatabaseProvider.allocate` chooses from. */
+export interface DatabaseAllocationInput {
+    /** Requested instance base name. */
+    base: string;
+    /** Owning checkout: `DevConfig.root`. */
+    owner: string;
+    /** Previous allocation of this checkout. */
+    saved: Partial<DatabaseAllocation>;
+}
+/** The checkout's dev instance. */
+export interface DatabaseAllocation {
+    /** Instance name; persistent storage derives from it. */
+    name: string;
+    /** Published loopback port. */
+    port: number;
+}
+/** What `DatabaseProvider.ensure` starts. */
+export interface EnsureDatabaseOptions {
+    allocation: DatabaseAllocation;
+    /** Image base name. */
+    image: string;
+    /** Owning checkout, labeled on the instance. */
+    owner: string;
+    /** `DevConfig.program`, for hints naming a launcher command. */
+    program: string;
+}
+/** What a disposable instance command runs beside. */
+interface DisposableCommandOptions {
+    /** The checkout's dev instance: names derive from it; its port stays free. */
+    allocation: DatabaseAllocation;
+    /** Image base name. */
+    image: string;
+    /** Stops the command; its instances go. */
+    signal: AbortSignal;
+}
+/** What `DatabaseProvider.runDisposable` serves. */
+export interface DisposableDatabaseOptions extends DisposableCommandOptions {
+    /** Server arguments appended to the image command. */
+    serverArgs: readonly string[];
+    /** Dump loaded before the instance accepts connections. */
+    snapshot?: {
+        /** Absolute path of a full dump. */
+        dump: string;
+        /** Runs each schema module's scrub after the load. */
+        scrub: boolean;
+    };
+}
+/** What `DatabaseProvider.upgradeDump` migrates. */
+export interface UpgradeDumpOptions extends DisposableCommandOptions {
+    /** Absolute paths of migrate files, run on a copy of the source. */
+    migrations: readonly string[];
+}
+/** A test run's seeded instance: a database per Vitest project. */
+export interface TestDatabase {
+    /**
+     * Creates the project's private database from the seeded template;
+     * duplicate names fail without dropping data. Returns the app's
+     * connection string.
+     */
+    createDatabase(name: string): Promise<string>;
+    /** Administrative connection to the project's database. */
+    adminConnectionString(name: string): string;
+    /** Container running the instance, for fixtures that run tools inside it. */
+    readonly container?: TestContainer;
+}
+/** Container running a test instance. */
+export interface TestContainer {
+    /** Container runtime binary. */
+    runtime: string;
+    /** Container name. */
+    name: string;
+}
+/** The dev database as `DevConfig.environment` receives it. */
+export interface DevDatabase extends DatabaseAllocation {
+    /** `DatabaseProvider.connectionString` of the allocation. */
+    connectionString: string;
+}
+/** One dev server under `live`. */
+export interface DevServerConfig {
+    /** `live` session name. */
+    name: string;
+    /** App directory relative to `DevConfig.root`; runs `pnpm dev --port <port>`. */
+    dir: string;
+    /** Preferred port; a taken one moves to the next free port up. */
+    port: number;
+    /** Preferred debugger port, allocated like `port`; `servers[name].inspectorPort`. */
+    inspectorPort?: number;
+    /** Browser-facing: serves on the checkout hostname and binds
+     *  `DEV_SERVER_HOST` (every interface with `DEV_LAN`, else `localhost`). */
+    host?: boolean;
+    /** Listens over HTTPS with the launcher's certificates. */
+    https?: boolean;
+    /** Readiness: every probe passes through the actual listener. */
+    ready: readonly ReadyProbe[];
+}
+/** Expected response of one readiness request. */
+export interface ReadyProbe {
+    /** Path on the server's origin. */
+    path: string;
+    /** Expected status; 200 by default. */
+    status?: number;
+    /** Exact expected body; any body by default. */
+    body?: string;
+}
+/** Present override values; empty strings dropped. */
+export type Overrides = Partial<Record<string, string>>;
+/** The checkout's hostnames and certificate paths. */
+export interface LocalHosts {
+    /** Loopback hostname: `<stem>.localhost`. */
+    hostname: string;
+    /** mDNS hostname: `<stem>.local`. */
+    lanHostname: string;
+    /** Hostnames `host` servers answer on: `hostname`, plus `lanHostname`
+     *  with `DEV_LAN`. */
+    hostnames: readonly string[];
+    /** `DEV_LAN` set: `host` servers listen on every interface. */
+    lan: boolean;
+    /** TLS key path: `<localDir>/certs/<hostname>-key.pem`. */
+    sslKey: string;
+    /** TLS certificate path: `<localDir>/certs/<hostname>.pem`; covers
+     *  `localhost`, `hostname` and `lanHostname`. */
+    sslCert: string;
+}
+/** One dev server's allocation. */
+export interface DevServerAllocation {
+    /** Allocated listener port. */
+    port: number;
+    /** Origin on `port`: the checkout hostname for a `host` server
+     *  (`https://app.localhost:<port>`), else `localhost`. */
+    origin: string;
+    /** Every origin on `port`: one per `LocalHosts.hostnames` entry for a
+     *  `host` server, else `[origin]`. */
+    origins: readonly string[];
+    /** Allocated debugger port; present when the server declares one. */
+    inspectorPort?: number;
+}
+/** What `DevConfig.environment` derives the server environments from. */
+export interface DevEnvironmentInput<Database extends DatabaseProvider | undefined = DatabaseProvider | undefined> {
+    /** Generated per-checkout state: `<root>/.local/`. */
+    localDir: string;
+    /** `DevConfig.overrideKeys` and `DEV_LAN` from the shell over
+     *  `<root>/.env`. */
+    overrides: Overrides;
+    /** Hostnames and certificate paths. */
+    hosts: LocalHosts;
+    /** Per-checkout auth signing secret, generated once under `localDir`. */
+    authSecret: string;
+    /** The dev database; `undefined` for an app without one. */
+    database: Database extends DatabaseProvider ? DevDatabase : undefined;
+    /** Allocation by server name. */
+    servers: Record<string, DevServerAllocation>;
+}
+/** `DB_NAME` from the environment; empty or unset ⇒ `database.name`. */
+export declare function envDbName(database: Pick<DatabaseProvider, "name">): string;
+/** Instance, image and volume names: lowercase letters, digits, `_` and
+ *  `-`. Container runtimes accept them. */
+export declare const RESOURCE_NAME: RegExp;
+/** Environment variable name. */
+export declare const ENV_KEY: RegExp;
+/** Absolute path of an existing directory. */
+export declare function isDirectory(path: string): boolean;
+/** TCP port number. */
+export declare const PORT: z.ZodInt;
+/** Validates the declaration, keeping the declared `database` type. */
+export declare function defineDevConfig<Database extends DatabaseProvider | undefined = undefined>(config: DevConfig<Database>): DevConfig<Database> & {
+    database: Database;
+};
+export {};

package/dist/config.js

@@ -0,0 +1,90 @@
+/**
+ * App-side dev configuration: what the launcher and the test harness vary
+ * per app. The app owns one `DevConfig` and passes it to the shared entry
+ * points; `defineDevConfig` validates it.
+ */
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+/** `DB_NAME` from the environment; empty or unset ⇒ `database.name`. */
+export function envDbName(database) {
+    const name = process.env.DB_NAME;
+    return name === undefined || name === "" ? database.name : name;
+}
+/** Instance, image and volume names: lowercase letters, digits, `_` and
+ *  `-`. Container runtimes accept them. */
+export const RESOURCE_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** One DNS label. */
+const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/** Environment variable name. */
+export const ENV_KEY = /^[A-Z_][A-Z0-9_]*$/;
+/** Absolute path of an existing directory. */
+export function isDirectory(path) {
+    try {
+        return isAbsolute(path) && statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** `path` is an existing directory at or below `root`, symlinks
+ *  resolved. */
+function isDirectoryUnder(root, path) {
+    if (!isDirectory(path))
+        return false;
+    const inside = relative(realpathSync(root), realpathSync(path));
+    return !inside.startsWith("..") && !isAbsolute(inside);
+}
+const unique = (items) => new Set(items).size === items.length;
+/** TCP port number. */
+export const PORT = z.int().min(1).max(65535);
+const probe = z.object({
+    path: z.string().startsWith("/"),
+    status: z.int().min(100).max(599).optional(),
+    body: z.string().optional(),
+});
+const server = z.object({
+    name: z.string().min(1),
+    dir: z.string().min(1),
+    port: PORT,
+    inspectorPort: PORT.optional(),
+    host: z.boolean().optional(),
+    https: z.boolean().optional(),
+    ready: z.array(probe),
+});
+const provider = z.custom((value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.name === "string" &&
+    typeof value.ensure === "function", { error: "database must be a DatabaseProvider" });
+const devConfig = z
+    .object({
+    root: z
+        .string()
+        .refine(isDirectory, { error: "root must be an existing directory" })
+        .refine((root) => existsSync(resolve(root, "pnpm-workspace.yaml")), {
+        error: "root must hold pnpm-workspace.yaml",
+    }),
+    program: z.string().min(1),
+    domain: z.string().regex(DNS_LABEL),
+    database: provider.optional(),
+    servers: z
+        .array(server)
+        .refine((servers) => unique(servers.map(({ name }) => name)), {
+        error: "server names must be unique",
+    })
+        .refine((servers) => unique(servers.flatMap(({ port, inspectorPort }) => inspectorPort === undefined ? [port] : [port, inspectorPort])), { error: "server ports must be unique" }),
+    overrideKeys: z
+        .array(z.string().regex(ENV_KEY))
+        .refine(unique, { error: "overrideKeys must be unique" }),
+    environment: z.custom((value) => typeof value === "function", { error: "environment must be a function" }),
+    data: z.string().min(1),
+})
+    .refine(({ root, servers }) => servers.every(({ dir }) => isDirectoryUnder(root, resolve(root, dir))), { error: "every server dir must be an existing directory under root" });
+/** Validates the declaration, keeping the declared `database` type. */
+export function defineDevConfig(config) {
+    const result = devConfig.safeParse(config);
+    if (!result.success)
+        throw new ExpectedError(`invalid dev config:\n${z.prettifyError(result.error)}`);
+    return config;
+}

package/dist/environment.d.ts

@@ -0,0 +1,19 @@
+/** Child-process runtime settings, independent of app bindings. */
+import type { DevServerConfig, LocalHosts } from "./config.ts";
+/** Listener settings `server` opts into: the bind address when `host`,
+ *  certificates when `https`, the debugger port when allocated. */
+export declare function listenerEnv(hosts: LocalHosts, server: Pick<DevServerConfig, "host" | "https">, inspectorPort?: number): Record<string, string>;
+/** Runtime options of a launched app process. */
+export interface ProcessEnvironmentOptions {
+    /**
+     * App execution mode: `dev` runs with development semantics,
+     * `build` reads no dot-env; every other mode is production.
+     */
+    mode: string;
+    /** Named Wrangler environment; omitted selects local development. */
+    cloudflareEnv?: string;
+    /** Explicit Node flags; never inherited from the shell. */
+    nodeOptions?: string;
+}
+/** Minimal host paths plus explicit app bindings and runtime options. */
+export declare function appProcessEnv(env: Record<string, string>, options: ProcessEnvironmentOptions): NodeJS.ProcessEnv;

package/dist/environment.js

@@ -0,0 +1,45 @@
+/**
+ * Listener settings of a launched server, the contract between the
+ * launcher and the app's Vite or wrangler config (`@astralarium/repo-dev/vite`
+ * `devListener`, `cloudflareDevOptions`): `DEV_SERVER_HOST` (a `host`
+ * server's bind address: `::` with `DEV_LAN`, else `localhost`), `SSL_KEY`
+ * and `SSL_CERT` (an `https` server's certificate paths),
+ * `DEV_INSPECTOR_PORT` (the allocated debugger port). `appProcessEnv`
+ * blanks them all, so a dot-env file supplies none.
+ */
+const LISTENER_KEYS = [
+    "DEV_SERVER_HOST",
+    "SSL_KEY",
+    "SSL_CERT",
+    "DEV_INSPECTOR_PORT",
+];
+/** Listener settings `server` opts into: the bind address when `host`,
+ *  certificates when `https`, the debugger port when allocated. */
+export function listenerEnv(hosts, server, inspectorPort) {
+    return {
+        ...(server.host && { DEV_SERVER_HOST: hosts.lan ? "::" : "localhost" }),
+        ...(server.https && { SSL_KEY: hosts.sslKey, SSL_CERT: hosts.sslCert }),
+        ...(inspectorPort !== undefined && {
+            DEV_INSPECTOR_PORT: String(inspectorPort),
+        }),
+    };
+}
+/** Minimal host paths plus explicit app bindings and runtime options. */
+export function appProcessEnv(env, options) {
+    const host = {};
+    for (const key of ["PATH", "HOME", "TMPDIR"]) {
+        const value = process.env[key];
+        if (value !== undefined)
+            host[key] = value;
+    }
+    return {
+        ...host,
+        // Empty overrides block Vite's app-local .env fallback.
+        ...Object.fromEntries(LISTENER_KEYS.map((key) => [key, ""])),
+        ...env,
+        NODE_ENV: options.mode === "dev" ? "development" : "production",
+        NODE_OPTIONS: options.nodeOptions,
+        CLOUDFLARE_ENV: options.cloudflareEnv,
+        CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV: options.mode === "build" ? "false" : "true",
+    };
+}

package/dist/exec.d.ts

@@ -0,0 +1,4 @@
+/** Exit status 0. */
+export declare function succeeds(command: string, args: string[]): boolean;
+/** Trimmed stdout, or null on non-zero exit. */
+export declare function output(command: string, args: string[]): string | null;

package/dist/exec.js

@@ -0,0 +1,14 @@
+/** Synchronous command probes; a missing binary counts as failure. */
+import { spawnSync } from "node:child_process";
+/** Exit status 0. */
+export function succeeds(command, args) {
+    return spawnSync(command, args, { stdio: "ignore" }).status === 0;
+}
+/** Trimmed stdout, or null on non-zero exit. */
+export function output(command, args) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/** Dev configuration, child processes, readiness and turbo fingerprints. */
+export * from "./allocation.ts";
+export { type DatabaseAllocation, type DatabaseAllocationInput, type DatabaseProvider, defineDevConfig, type DevConfig, type DevDatabase, type DevEnvironmentInput, type DevServerAllocation, type DevServerConfig, type DisposableDatabaseOptions, type EnsureDatabaseOptions, envDbName, isDirectory, type LocalHosts, type Overrides, type ReadyProbe, RESOURCE_NAME, type TestContainer, type TestDatabase, type UpgradeDumpOptions, } from "./config.ts";
+export { appProcessEnv, type ProcessEnvironmentOptions, } from "./environment.ts";
+export * from "./exec.ts";
+export * from "./load-config.ts";
+export * from "./ports.ts";
+export * from "./process.ts";
+export * from "./resources.ts";
+export * from "./sibling-inputs.ts";
+export * from "./source-hash.ts";
+export { isPortOpen, READY_TIMEOUT_MS, waitFor } from "./wait.ts";

package/dist/index.js

@@ -0,0 +1,12 @@
+/** Dev configuration, child processes, readiness and turbo fingerprints. */
+export * from "./allocation.js";
+export { defineDevConfig, envDbName, isDirectory, RESOURCE_NAME, } from "./config.js";
+export { appProcessEnv, } from "./environment.js";
+export * from "./exec.js";
+export * from "./load-config.js";
+export * from "./ports.js";
+export * from "./process.js";
+export * from "./resources.js";
+export * from "./sibling-inputs.js";
+export * from "./source-hash.js";
+export { isPortOpen, READY_TIMEOUT_MS, waitFor } from "./wait.js";

package/dist/launcher/hosts.d.ts

@@ -0,0 +1,26 @@
+import type { DevConfig, LocalHosts, Overrides } from "../config.ts";
+/** `name` as a DNS label: lowercase, runs outside `[a-z0-9-]` as `-`,
+ *  `-<suffix>` appended, at most 63 characters with `suffix` intact;
+ *  empty when nothing of `name` survives. */
+export declare function dnsLabel(name: string, suffix?: string): string;
+/** Temp directories, real paths: `os.tmpdir()`, macOS's per-user temp
+ *  directory (independent of `TMPDIR`), `/tmp`, `/var/tmp`. */
+export declare function tempRoots(): string[];
+/**
+ * The checkout's hostname stem: `<domain>` for a repository's main
+ * worktree, `<name>.<domain>` for a linked worktree (git's worktree name)
+ * or a checkout under a temp directory (its first directory below it,
+ * plus a hash of its path when deeper: `copy-1-ab12cd`). The temp-directory
+ * rule wins over git's worktree name.
+ */
+export declare function checkoutStem(app: Pick<DevConfig, "root" | "domain">, temps?: readonly string[]): string;
+/** Hostnames and certificate paths of hostname stem `stem`. */
+export declare function localHosts(local: string, overrides: Overrides, stem: string): LocalHosts;
+/** IPv4 address `DEV_LAN` advertises: the default route interface's.
+ *  Throws `ExpectedError` without `dns-sd` or a default route. */
+export declare function lanAddress(): string;
+/** Stops the checkout's mDNS advertisement; a missing session is fine. */
+export declare function stopAdvertising(root: string): void;
+/** Advertises `hosts.lanHostname` → `address` over mDNS (`dns-sd`)
+ *  under `live`, replacing a running advertisement. */
+export declare function advertiseHost(root: string, hosts: LocalHosts, address: string, port: number): void;