@absolutejs/deploy 0.9.0 → 0.10.0

package/dist/preview.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Preview-deploys fleet for `@absolutejs/deploy`.
+ *
+ * A `PreviewFleet` is a tenant-aware orchestrator that creates,
+ * lists, and tears down ephemeral environments — one per PR /
+ * branch / commit. It composes the existing `Deployer` (release
+ * dirs + atomic symlink swap + rollback) with a `DnsProvider` and a
+ * persistent registry so a deploy bot can:
+ *
+ *   const url = await fleet.create({ previewId: 'pr-42', ... });
+ *
+ *   await fleet.teardown('pr-42');
+ *
+ *   await fleet.gc({ olderThanMs: 7 * 24 * 60 * 60 * 1000 });
+ *
+ * Substrate responsibilities:
+ *
+ *   - allocate a free port from a configurable pool
+ *   - build the hostname `<previewId>.<baseDomain>`
+ *   - upsert an A record for that hostname (DNS provider injected)
+ *   - call a caller-supplied `makeDeployer({ previewId, port,
+ *     hostname })` factory, then run `deployer.deploy()` so the
+ *     preview lands as a normal release on disk
+ *   - persist the preview registry so we can list / GC later
+ *   - on teardown, run a caller-supplied stop callback, remove the
+ *     DNS record, drop the registry entry
+ *
+ * Everything tenant-specific (secrets snapshotting, db seeding,
+ * stopping the process) is a caller-supplied hook. The fleet owns
+ * fleet bookkeeping, not application logic.
+ */
+import type { Deployer, DeployResult, ReleaseAnnotations } from './deployer';
+import type { DnsProvider } from './dns';
+export type PreviewRecord = {
+    previewId: string;
+    hostname: string;
+    url: string;
+    port: number;
+    dnsRecordId?: string;
+    releaseId: string;
+    commitSha?: string;
+    createdAt: number;
+    annotations?: ReleaseAnnotations;
+};
+export type PreviewStore = {
+    list: () => Promise<PreviewRecord[]>;
+    get: (previewId: string) => Promise<PreviewRecord | null>;
+    put: (record: PreviewRecord) => Promise<void>;
+    remove: (previewId: string) => Promise<void>;
+};
+export type PreviewDeployerContext = {
+    previewId: string;
+    port: number;
+    hostname: string;
+    url: string;
+};
+export type PreviewFleetOptions = {
+    /**
+     * Apex used to build preview hostnames: `<previewId>.<baseDomain>`.
+     * `previewId` is slugified before use (alphanumeric + `-`).
+     */
+    baseDomain: string;
+    /**
+     * Optional URL scheme. Defaults to `'https'`. Set `'http'` for
+     * local-loop previews behind a localhost proxy.
+     */
+    scheme?: 'http' | 'https';
+    /**
+     * DNS provider — `cloudflareProvider`, `route53Provider`, etc.
+     * Optional: when absent, `fleet.create` skips DNS work and the
+     * caller is responsible for routing requests at the hostname.
+     */
+    dns?: DnsProvider;
+    /**
+     * Public IPv4 the A record should point at. Required when `dns`
+     * is set. The fleet calls `dns.upsert({ name, type: 'A',
+     * content: ipv4 })`.
+     */
+    ipv4?: string;
+    /**
+     * TTL applied to created A records. Default 60s — previews come
+     * and go and we want low cache lifetime.
+     */
+    dnsTtl?: number;
+    /**
+     * Proxied flag (Cloudflare orange-cloud). Default `false` — most
+     * previews want a real IP, not a Cloudflare proxy.
+     */
+    dnsProxied?: boolean;
+    /**
+     * Port range that the fleet allocates from. Default `[3100, 3899]`
+     * (3000 squat is documented in memory).
+     */
+    portRange?: {
+        start: number;
+        end: number;
+    };
+    /** Override port allocation entirely (e.g. talk to a port-leaser). */
+    allocatePort?: (record: {
+        previewId: string;
+        hostname: string;
+    }) => Promise<number>;
+    /**
+     * REQUIRED. Build a `Deployer` for an individual preview. The
+     * factory receives the resolved id, port, hostname, and URL —
+     * use them to set the right env, processManager, and target.
+     */
+    makeDeployer: (ctx: PreviewDeployerContext) => Deployer | Promise<Deployer>;
+    /**
+     * Stop callback. Called by `teardown` BEFORE DNS removal so the
+     * preview process stops accepting connections before the record
+     * disappears. Use it to call `processManager.stop()`, kill the
+     * port, etc.
+     */
+    stop?: (record: PreviewRecord) => Promise<void> | void;
+    /**
+     * After-teardown callback. Called after DNS + registry removal —
+     * good place to delete the release directory, drop a tenant
+     * schema, clear secrets, etc.
+     */
+    afterTeardown?: (record: PreviewRecord) => Promise<void> | void;
+    /** Registry. Default = filesystem store at `<root>`. */
+    store?: PreviewStore;
+    /** Directory the file-based default store writes into. */
+    registryRoot?: string;
+    /** Override `Date.now()` for tests. */
+    clock?: () => number;
+};
+/**
+ * Single-file JSON registry. Reads + writes atomically (temp-file
+ * + rename). Adequate for a deploy bot on one host — swap in a
+ * Postgres-backed store for distributed deploy bots.
+ */
+export declare const createFilePreviewStore: (root: string) => PreviewStore;
+export declare const createMemoryPreviewStore: () => PreviewStore;
+export type CreatePreviewInput = {
+    previewId: string;
+    commitSha?: string;
+    annotations?: ReleaseAnnotations;
+    /**
+     * Override hostname. Default = `<slug(previewId)>.<baseDomain>`.
+     * Use this for previews with a vanity name that shouldn't echo
+     * the PR id directly.
+     */
+    hostname?: string;
+};
+export type CreatePreviewResult = {
+    record: PreviewRecord;
+    deploy: DeployResult;
+};
+export type PreviewFleet = {
+    /**
+     * Spin up a preview. Idempotent on `previewId` — if a record
+     * already exists, the fleet re-uses its port + DNS and runs a
+     * fresh `deployer.deploy()` (so PRs that push new commits roll
+     * forward).
+     */
+    create: (input: CreatePreviewInput) => Promise<CreatePreviewResult>;
+    /** Tear down a single preview (stop → DNS remove → registry remove → afterTeardown). */
+    teardown: (previewId: string) => Promise<void>;
+    /** List active previews. */
+    list: () => Promise<PreviewRecord[]>;
+    /** Get one preview by id. */
+    get: (previewId: string) => Promise<PreviewRecord | null>;
+    /**
+     * Tear down all previews older than `olderThanMs`. Returns the
+     * list of preview ids torn down. Failures on individual previews
+     * are swallowed and reported on `errors`.
+     */
+    gc: (options: {
+        olderThanMs: number;
+    }) => Promise<{
+        removed: string[];
+        errors: {
+            previewId: string;
+            error: Error;
+        }[];
+    }>;
+};
+export declare const createPreviewFleet: (options: PreviewFleetOptions) => PreviewFleet;

package/dist/preview.js

@@ -0,0 +1,195 @@
+// @bun
+// src/preview.ts
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { dirname, join } from "path";
+var createFilePreviewStore = (root) => {
+  const path = join(root, "previews.json");
+  const readAll = () => {
+    if (!existsSync(path))
+      return [];
+    try {
+      const raw = readFileSync(path, "utf8");
+      if (raw.trim() === "")
+        return [];
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed.previews) ? parsed.previews : [];
+    } catch {
+      return [];
+    }
+  };
+  const writeAll = (records) => {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify({ previews: records }, null, 2));
+    renameSync(tmp, path);
+  };
+  return {
+    get: async (previewId) => readAll().find((r) => r.previewId === previewId) ?? null,
+    list: async () => readAll(),
+    put: async (record) => {
+      const records = readAll().filter((r) => r.previewId !== record.previewId);
+      records.push(record);
+      writeAll(records);
+    },
+    remove: async (previewId) => {
+      const records = readAll().filter((r) => r.previewId !== previewId);
+      writeAll(records);
+    }
+  };
+};
+var createMemoryPreviewStore = () => {
+  const map = new Map;
+  return {
+    get: async (previewId) => map.get(previewId) ?? null,
+    list: async () => Array.from(map.values()),
+    put: async (record) => {
+      map.set(record.previewId, record);
+    },
+    remove: async (previewId) => {
+      map.delete(previewId);
+    }
+  };
+};
+var slugify = (id) => id.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 50);
+var defaultAllocatePort = (used, range) => {
+  for (let port = range.start;port <= range.end; port += 1) {
+    if (!used.has(port))
+      return port;
+  }
+  throw new Error(`preview-fleet: no free ports in [${range.start}, ${range.end}] (${used.size} in use)`);
+};
+var createPreviewFleet = (options) => {
+  const scheme = options.scheme ?? "https";
+  const portRange = options.portRange ?? { end: 3899, start: 3100 };
+  const dnsTtl = options.dnsTtl ?? 60;
+  const dnsProxied = options.dnsProxied ?? false;
+  const clock = options.clock ?? Date.now;
+  const store = options.store ?? createFilePreviewStore(options.registryRoot ?? join(process.cwd(), ".preview-fleet"));
+  if (options.dns !== undefined && options.ipv4 === undefined) {
+    throw new Error("preview-fleet: `ipv4` is required when `dns` is configured");
+  }
+  const ensureDns = async (hostname) => {
+    if (options.dns === undefined)
+      return;
+    const spec = {
+      content: options.ipv4,
+      name: hostname,
+      proxied: dnsProxied,
+      ttl: dnsTtl,
+      type: "A"
+    };
+    return await options.dns.upsert(spec);
+  };
+  const removeDns = async (record) => {
+    if (options.dns === undefined || record.dnsRecordId === undefined) {
+      return;
+    }
+    try {
+      await options.dns.delete(record.dnsRecordId);
+    } catch {}
+  };
+  const buildHostname = (previewId, override) => {
+    if (override !== undefined)
+      return override;
+    const slug = slugify(previewId);
+    if (slug === "") {
+      throw new Error(`preview-fleet: previewId ${JSON.stringify(previewId)} slugifies to empty`);
+    }
+    return `${slug}.${options.baseDomain}`;
+  };
+  const create = async (input) => {
+    const existing = await store.get(input.previewId);
+    const hostname = buildHostname(input.previewId, input.hostname);
+    const url = `${scheme}://${hostname}`;
+    let port;
+    if (existing !== null) {
+      port = existing.port;
+    } else if (options.allocatePort !== undefined) {
+      port = await options.allocatePort({ hostname, previewId: input.previewId });
+    } else {
+      const used = new Set((await store.list()).map((record2) => record2.port));
+      port = defaultAllocatePort(used, portRange);
+    }
+    const deployer = await options.makeDeployer({
+      hostname,
+      port,
+      previewId: input.previewId,
+      url
+    });
+    const deployOptions = input.annotations !== undefined ? { annotations: input.annotations } : input.commitSha !== undefined ? { annotations: { commitSha: input.commitSha } } : undefined;
+    const deployResult = await deployer.deploy(deployOptions);
+    const dnsRecord = await ensureDns(hostname);
+    const record = {
+      createdAt: existing?.createdAt ?? clock(),
+      hostname,
+      port,
+      previewId: input.previewId,
+      releaseId: deployResult.releaseId,
+      url,
+      ...dnsRecord !== undefined ? { dnsRecordId: dnsRecord.id } : {},
+      ...input.commitSha !== undefined ? { commitSha: input.commitSha } : {},
+      ...input.annotations !== undefined ? { annotations: input.annotations } : {}
+    };
+    await store.put(record);
+    return { deploy: deployResult, record };
+  };
+  const teardown = async (previewId) => {
+    const record = await store.get(previewId);
+    if (record === null)
+      return;
+    if (options.stop !== undefined) {
+      try {
+        await options.stop(record);
+      } catch {}
+    }
+    await removeDns(record);
+    await store.remove(previewId);
+    if (options.afterTeardown !== undefined) {
+      try {
+        await options.afterTeardown(record);
+      } catch {}
+    }
+  };
+  const gc = async ({
+    olderThanMs
+  }) => {
+    const cutoff = clock() - olderThanMs;
+    const all = await store.list();
+    const expired = all.filter((record) => record.createdAt < cutoff);
+    const removed = [];
+    const errors = [];
+    for (const record of expired) {
+      try {
+        await teardown(record.previewId);
+        removed.push(record.previewId);
+      } catch (e) {
+        errors.push({
+          error: e instanceof Error ? e : new Error(String(e)),
+          previewId: record.previewId
+        });
+      }
+    }
+    return { errors, removed };
+  };
+  return {
+    create,
+    gc,
+    get: (previewId) => store.get(previewId),
+    list: () => store.list(),
+    teardown
+  };
+};
+export {
+  createPreviewFleet,
+  createMemoryPreviewStore,
+  createFilePreviewStore
+};
+
+//# debugId=8E7013E55C0C6FB764756E2164756E21
+//# sourceMappingURL=preview.js.map

package/dist/preview.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/preview.ts"],
+  "sourcesContent": [
+    "/**\n * Preview-deploys fleet for `@absolutejs/deploy`.\n *\n * A `PreviewFleet` is a tenant-aware orchestrator that creates,\n * lists, and tears down ephemeral environments — one per PR /\n * branch / commit. It composes the existing `Deployer` (release\n * dirs + atomic symlink swap + rollback) with a `DnsProvider` and a\n * persistent registry so a deploy bot can:\n *\n *   const url = await fleet.create({ previewId: 'pr-42', ... });\n *\n *   await fleet.teardown('pr-42');\n *\n *   await fleet.gc({ olderThanMs: 7 * 24 * 60 * 60 * 1000 });\n *\n * Substrate responsibilities:\n *\n *   - allocate a free port from a configurable pool\n *   - build the hostname `<previewId>.<baseDomain>`\n *   - upsert an A record for that hostname (DNS provider injected)\n *   - call a caller-supplied `makeDeployer({ previewId, port,\n *     hostname })` factory, then run `deployer.deploy()` so the\n *     preview lands as a normal release on disk\n *   - persist the preview registry so we can list / GC later\n *   - on teardown, run a caller-supplied stop callback, remove the\n *     DNS record, drop the registry entry\n *\n * Everything tenant-specific (secrets snapshotting, db seeding,\n * stopping the process) is a caller-supplied hook. The fleet owns\n * fleet bookkeeping, not application logic.\n */\n\nimport {\n\texistsSync,\n\tmkdirSync,\n\treadFileSync,\n\trenameSync,\n\twriteFileSync\n} from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport type {\n\tDeployer,\n\tDeployResult,\n\tReleaseAnnotations\n} from './deployer';\nimport type { DnsProvider, DnsRecord, DnsRecordSpec } from './dns';\n\n// =============================================================================\n// Registry shape\n// =============================================================================\n\nexport type PreviewRecord = {\n\tpreviewId: string;\n\thostname: string;\n\turl: string;\n\tport: number;\n\tdnsRecordId?: string;\n\treleaseId: string;\n\tcommitSha?: string;\n\tcreatedAt: number;\n\tannotations?: ReleaseAnnotations;\n};\n\nexport type PreviewStore = {\n\tlist: () => Promise<PreviewRecord[]>;\n\tget: (previewId: string) => Promise<PreviewRecord | null>;\n\tput: (record: PreviewRecord) => Promise<void>;\n\tremove: (previewId: string) => Promise<void>;\n};\n\n// =============================================================================\n// Hooks + options\n// =============================================================================\n\nexport type PreviewDeployerContext = {\n\tpreviewId: string;\n\tport: number;\n\thostname: string;\n\turl: string;\n};\n\nexport type PreviewFleetOptions = {\n\t/**\n\t * Apex used to build preview hostnames: `<previewId>.<baseDomain>`.\n\t * `previewId` is slugified before use (alphanumeric + `-`).\n\t */\n\tbaseDomain: string;\n\t/**\n\t * Optional URL scheme. Defaults to `'https'`. Set `'http'` for\n\t * local-loop previews behind a localhost proxy.\n\t */\n\tscheme?: 'http' | 'https';\n\t/**\n\t * DNS provider — `cloudflareProvider`, `route53Provider`, etc.\n\t * Optional: when absent, `fleet.create` skips DNS work and the\n\t * caller is responsible for routing requests at the hostname.\n\t */\n\tdns?: DnsProvider;\n\t/**\n\t * Public IPv4 the A record should point at. Required when `dns`\n\t * is set. The fleet calls `dns.upsert({ name, type: 'A',\n\t * content: ipv4 })`.\n\t */\n\tipv4?: string;\n\t/**\n\t * TTL applied to created A records. Default 60s — previews come\n\t * and go and we want low cache lifetime.\n\t */\n\tdnsTtl?: number;\n\t/**\n\t * Proxied flag (Cloudflare orange-cloud). Default `false` — most\n\t * previews want a real IP, not a Cloudflare proxy.\n\t */\n\tdnsProxied?: boolean;\n\t/**\n\t * Port range that the fleet allocates from. Default `[3100, 3899]`\n\t * (3000 squat is documented in memory).\n\t */\n\tportRange?: { start: number; end: number };\n\t/** Override port allocation entirely (e.g. talk to a port-leaser). */\n\tallocatePort?: (record: {\n\t\tpreviewId: string;\n\t\thostname: string;\n\t}) => Promise<number>;\n\t/**\n\t * REQUIRED. Build a `Deployer` for an individual preview. The\n\t * factory receives the resolved id, port, hostname, and URL —\n\t * use them to set the right env, processManager, and target.\n\t */\n\tmakeDeployer: (\n\t\tctx: PreviewDeployerContext\n\t) => Deployer | Promise<Deployer>;\n\t/**\n\t * Stop callback. Called by `teardown` BEFORE DNS removal so the\n\t * preview process stops accepting connections before the record\n\t * disappears. Use it to call `processManager.stop()`, kill the\n\t * port, etc.\n\t */\n\tstop?: (record: PreviewRecord) => Promise<void> | void;\n\t/**\n\t * After-teardown callback. Called after DNS + registry removal —\n\t * good place to delete the release directory, drop a tenant\n\t * schema, clear secrets, etc.\n\t */\n\tafterTeardown?: (record: PreviewRecord) => Promise<void> | void;\n\t/** Registry. Default = filesystem store at `<root>`. */\n\tstore?: PreviewStore;\n\t/** Directory the file-based default store writes into. */\n\tregistryRoot?: string;\n\t/** Override `Date.now()` for tests. */\n\tclock?: () => number;\n};\n\n// =============================================================================\n// File-based PreviewStore (default)\n// =============================================================================\n\n/**\n * Single-file JSON registry. Reads + writes atomically (temp-file\n * + rename). Adequate for a deploy bot on one host — swap in a\n * Postgres-backed store for distributed deploy bots.\n */\nexport const createFilePreviewStore = (root: string): PreviewStore => {\n\tconst path = join(root, 'previews.json');\n\n\tconst readAll = (): PreviewRecord[] => {\n\t\tif (!existsSync(path)) return [];\n\t\ttry {\n\t\t\tconst raw = readFileSync(path, 'utf8');\n\t\t\tif (raw.trim() === '') return [];\n\t\t\tconst parsed = JSON.parse(raw) as { previews?: PreviewRecord[] };\n\t\t\treturn Array.isArray(parsed.previews) ? parsed.previews : [];\n\t\t} catch {\n\t\t\treturn [];\n\t\t}\n\t};\n\n\tconst writeAll = (records: PreviewRecord[]): void => {\n\t\tmkdirSync(dirname(path), { recursive: true });\n\t\tconst tmp = `${path}.tmp-${process.pid}-${Date.now()}`;\n\t\twriteFileSync(tmp, JSON.stringify({ previews: records }, null, 2));\n\t\trenameSync(tmp, path);\n\t};\n\n\treturn {\n\t\tget: async (previewId) =>\n\t\t\treadAll().find((r) => r.previewId === previewId) ?? null,\n\t\tlist: async () => readAll(),\n\t\tput: async (record) => {\n\t\t\tconst records = readAll().filter(\n\t\t\t\t(r) => r.previewId !== record.previewId\n\t\t\t);\n\t\t\trecords.push(record);\n\t\t\twriteAll(records);\n\t\t},\n\t\tremove: async (previewId) => {\n\t\t\tconst records = readAll().filter((r) => r.previewId !== previewId);\n\t\t\twriteAll(records);\n\t\t}\n\t};\n};\n\n// =============================================================================\n// In-memory store (for tests + ephemeral fleets)\n// =============================================================================\n\nexport const createMemoryPreviewStore = (): PreviewStore => {\n\tconst map = new Map<string, PreviewRecord>();\n\treturn {\n\t\tget: async (previewId) => map.get(previewId) ?? null,\n\t\tlist: async () => Array.from(map.values()),\n\t\tput: async (record) => {\n\t\t\tmap.set(record.previewId, record);\n\t\t},\n\t\tremove: async (previewId) => {\n\t\t\tmap.delete(previewId);\n\t\t}\n\t};\n};\n\n// =============================================================================\n// Helpers\n// =============================================================================\n\nconst slugify = (id: string): string =>\n\tid\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9-]+/g, '-')\n\t\t.replace(/^-+|-+$/g, '')\n\t\t.slice(0, 50);\n\nconst defaultAllocatePort = (\n\tused: Set<number>,\n\trange: { start: number; end: number }\n): number => {\n\tfor (let port = range.start; port <= range.end; port += 1) {\n\t\tif (!used.has(port)) return port;\n\t}\n\tthrow new Error(\n\t\t`preview-fleet: no free ports in [${range.start}, ${range.end}] (${used.size} in use)`\n\t);\n};\n\n// =============================================================================\n// Fleet\n// =============================================================================\n\nexport type CreatePreviewInput = {\n\tpreviewId: string;\n\tcommitSha?: string;\n\tannotations?: ReleaseAnnotations;\n\t/**\n\t * Override hostname. Default = `<slug(previewId)>.<baseDomain>`.\n\t * Use this for previews with a vanity name that shouldn't echo\n\t * the PR id directly.\n\t */\n\thostname?: string;\n};\n\nexport type CreatePreviewResult = {\n\trecord: PreviewRecord;\n\tdeploy: DeployResult;\n};\n\nexport type PreviewFleet = {\n\t/**\n\t * Spin up a preview. Idempotent on `previewId` — if a record\n\t * already exists, the fleet re-uses its port + DNS and runs a\n\t * fresh `deployer.deploy()` (so PRs that push new commits roll\n\t * forward).\n\t */\n\tcreate: (input: CreatePreviewInput) => Promise<CreatePreviewResult>;\n\t/** Tear down a single preview (stop → DNS remove → registry remove → afterTeardown). */\n\tteardown: (previewId: string) => Promise<void>;\n\t/** List active previews. */\n\tlist: () => Promise<PreviewRecord[]>;\n\t/** Get one preview by id. */\n\tget: (previewId: string) => Promise<PreviewRecord | null>;\n\t/**\n\t * Tear down all previews older than `olderThanMs`. Returns the\n\t * list of preview ids torn down. Failures on individual previews\n\t * are swallowed and reported on `errors`.\n\t */\n\tgc: (options: { olderThanMs: number }) => Promise<{\n\t\tremoved: string[];\n\t\terrors: { previewId: string; error: Error }[];\n\t}>;\n};\n\nexport const createPreviewFleet = (\n\toptions: PreviewFleetOptions\n): PreviewFleet => {\n\tconst scheme = options.scheme ?? 'https';\n\tconst portRange = options.portRange ?? { end: 3899, start: 3100 };\n\tconst dnsTtl = options.dnsTtl ?? 60;\n\tconst dnsProxied = options.dnsProxied ?? false;\n\tconst clock = options.clock ?? Date.now;\n\tconst store =\n\t\toptions.store ??\n\t\tcreateFilePreviewStore(\n\t\t\toptions.registryRoot ?? join(process.cwd(), '.preview-fleet')\n\t\t);\n\n\tif (options.dns !== undefined && options.ipv4 === undefined) {\n\t\tthrow new Error(\n\t\t\t'preview-fleet: `ipv4` is required when `dns` is configured'\n\t\t);\n\t}\n\n\tconst ensureDns = async (\n\t\thostname: string\n\t): Promise<DnsRecord | undefined> => {\n\t\tif (options.dns === undefined) return undefined;\n\t\tconst spec: DnsRecordSpec = {\n\t\t\tcontent: options.ipv4!,\n\t\t\tname: hostname,\n\t\t\tproxied: dnsProxied,\n\t\t\tttl: dnsTtl,\n\t\t\ttype: 'A'\n\t\t};\n\t\treturn await options.dns.upsert(spec);\n\t};\n\n\tconst removeDns = async (record: PreviewRecord): Promise<void> => {\n\t\tif (options.dns === undefined || record.dnsRecordId === undefined) {\n\t\t\treturn;\n\t\t}\n\t\ttry {\n\t\t\tawait options.dns.delete(record.dnsRecordId);\n\t\t} catch {\n\t\t\t// Idempotent teardown — the record may already be gone. Don't\n\t\t\t// block the rest of teardown on a stale id.\n\t\t}\n\t};\n\n\tconst buildHostname = (previewId: string, override?: string): string => {\n\t\tif (override !== undefined) return override;\n\t\tconst slug = slugify(previewId);\n\t\tif (slug === '') {\n\t\t\tthrow new Error(\n\t\t\t\t`preview-fleet: previewId ${JSON.stringify(previewId)} slugifies to empty`\n\t\t\t);\n\t\t}\n\t\treturn `${slug}.${options.baseDomain}`;\n\t};\n\n\tconst create = async (\n\t\tinput: CreatePreviewInput\n\t): Promise<CreatePreviewResult> => {\n\t\tconst existing = await store.get(input.previewId);\n\t\tconst hostname = buildHostname(input.previewId, input.hostname);\n\t\tconst url = `${scheme}://${hostname}`;\n\n\t\t// Allocate a port — reuse existing if we're re-deploying.\n\t\tlet port: number;\n\t\tif (existing !== null) {\n\t\t\tport = existing.port;\n\t\t} else if (options.allocatePort !== undefined) {\n\t\t\tport = await options.allocatePort({ hostname, previewId: input.previewId });\n\t\t} else {\n\t\t\tconst used = new Set(\n\t\t\t\t(await store.list()).map((record) => record.port)\n\t\t\t);\n\t\t\tport = defaultAllocatePort(used, portRange);\n\t\t}\n\n\t\tconst deployer = await options.makeDeployer({\n\t\t\thostname,\n\t\t\tport,\n\t\t\tpreviewId: input.previewId,\n\t\t\turl\n\t\t});\n\n\t\tconst deployOptions =\n\t\t\tinput.annotations !== undefined\n\t\t\t\t? { annotations: input.annotations }\n\t\t\t\t: input.commitSha !== undefined\n\t\t\t\t\t? { annotations: { commitSha: input.commitSha } }\n\t\t\t\t\t: undefined;\n\t\tconst deployResult = await deployer.deploy(deployOptions);\n\n\t\t// DNS only after the deploy succeeded — no point flipping the\n\t\t// record at a half-baked release.\n\t\tconst dnsRecord = await ensureDns(hostname);\n\n\t\tconst record: PreviewRecord = {\n\t\t\tcreatedAt: existing?.createdAt ?? clock(),\n\t\t\thostname,\n\t\t\tport,\n\t\t\tpreviewId: input.previewId,\n\t\t\treleaseId: deployResult.releaseId,\n\t\t\turl,\n\t\t\t...(dnsRecord !== undefined ? { dnsRecordId: dnsRecord.id } : {}),\n\t\t\t...(input.commitSha !== undefined ? { commitSha: input.commitSha } : {}),\n\t\t\t...(input.annotations !== undefined\n\t\t\t\t? { annotations: input.annotations }\n\t\t\t\t: {})\n\t\t};\n\n\t\tawait store.put(record);\n\t\treturn { deploy: deployResult, record };\n\t};\n\n\tconst teardown = async (previewId: string): Promise<void> => {\n\t\tconst record = await store.get(previewId);\n\t\tif (record === null) return;\n\n\t\tif (options.stop !== undefined) {\n\t\t\ttry {\n\t\t\t\tawait options.stop(record);\n\t\t\t} catch {\n\t\t\t\t// Don't block DNS removal on a stop failure. The caller\n\t\t\t\t// can see the error via afterTeardown by re-querying.\n\t\t\t}\n\t\t}\n\n\t\tawait removeDns(record);\n\t\tawait store.remove(previewId);\n\n\t\tif (options.afterTeardown !== undefined) {\n\t\t\ttry {\n\t\t\t\tawait options.afterTeardown(record);\n\t\t\t} catch {\n\t\t\t\t// Caller's own teardown errors are their problem; the\n\t\t\t\t// substrate has already removed the record + DNS.\n\t\t\t}\n\t\t}\n\t};\n\n\tconst gc = async ({\n\t\tolderThanMs\n\t}: {\n\t\tolderThanMs: number;\n\t}): Promise<{\n\t\tremoved: string[];\n\t\terrors: { previewId: string; error: Error }[];\n\t}> => {\n\t\tconst cutoff = clock() - olderThanMs;\n\t\tconst all = await store.list();\n\t\tconst expired = all.filter((record) => record.createdAt < cutoff);\n\t\tconst removed: string[] = [];\n\t\tconst errors: { previewId: string; error: Error }[] = [];\n\t\tfor (const record of expired) {\n\t\t\ttry {\n\t\t\t\tawait teardown(record.previewId);\n\t\t\t\tremoved.push(record.previewId);\n\t\t\t} catch (e) {\n\t\t\t\terrors.push({\n\t\t\t\t\terror: e instanceof Error ? e : new Error(String(e)),\n\t\t\t\t\tpreviewId: record.previewId\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t\treturn { errors, removed };\n\t};\n\n\treturn {\n\t\tcreate,\n\t\tgc,\n\t\tget: (previewId) => store.get(previewId),\n\t\tlist: () => store.list(),\n\t\tteardown\n\t};\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "8E7013E55C0C6FB764756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/deploy",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Generic Bun-project deploy pipeline. A Target (localTarget / sshTarget) is anywhere you can exec + upload — DigitalOcean droplets, Linode, Hetzner, Vultr, your own boxes. Bundled pipeline: prepare → upload → install → build → link → restart → verify. Atomic symlink swap, release history, prune, hooks. SSH shells out to system ssh/rsync — zero ssh2 deps.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "release"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/digitalocean.ts src/hetzner.ts src/linode.ts src/vultr.ts src/dns.ts src/cloudflare.ts src/digitaloceanDns.ts src/hetznerDns.ts src/route53.ts src/tls.ts src/env.ts --outdir dist --root src --sourcemap --target=bun && tsc --project tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/digitalocean.ts src/hetzner.ts src/linode.ts src/vultr.ts src/dns.ts src/cloudflare.ts src/digitaloceanDns.ts src/hetznerDns.ts src/route53.ts src/tls.ts src/env.ts src/preview.ts --outdir dist --root src --sourcemap --target=bun && tsc --project tsconfig.build.json",
     "test": "bun test tests/",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write \"./**/*.{ts,json,md}\"",
@@ -101,6 +101,11 @@
       "types": "./dist/route53.d.ts",
       "import": "./dist/route53.js",
       "default": "./dist/route53.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "import": "./dist/preview.js",
+      "default": "./dist/preview.js"
     }
   },
   "files": ["dist", "README.md"]