@constructive-io/site-deploy 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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

@@ -0,0 +1,165 @@
+# @constructive-io/site-deploy
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@constructive-io/site-deploy"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Fsite-deploy%2Fpackage.json"/></a>
+</p>
+
+Deploy a static build as an immutable Constructive release.
+
+A deploy is **bytes plus one manifest**: every file's bytes go to the site's
+bucket at `cas/sha256/<hash>`, and one `siteRelease` row maps logical paths to
+those hashes. Writing that row commits the manifest into the site's own merkle
+store, so the returned commit id *is* the release — publishing, rolling back and
+previewing are pointer moves the server owns.
+
+This package is the client half of that, which every consumer would otherwise
+write itself: walk, hash, upload only what is missing, and commit one manifest.
+
+## Usage
+
+```typescript
+import { deploySite } from '@constructive-io/site-deploy';
+
+const result = await deploySite({
+  api,                     // GraphQL executor for the tenant API
+  siteId,
+  databaseId,              // required on a site's first deploy
+  bucketKey: 'site-docs',
+  source: './dist',        // a directory, or the files themselves
+  publish: true,           // move site.activeCommitId when it lands
+});
+
+console.log(result.commitId, result.uploaded, result.skipped);
+```
+
+Deploy a branch preview instead of going live:
+
+```typescript
+const { previewUrl } = await deploySite({
+  api,
+  siteId,
+  bucketKey: 'site-docs',
+  source: './dist',
+  preview: 'pr-42',              // → preview/pr-42
+  previewApex: 'preview.example.com',  // provisions pr-42--<site>.preview.example.com
+});
+```
+
+Roll back — the same pointer move, to an older commit:
+
+```typescript
+import { deployNames, publishCommit } from '@constructive-io/site-deploy';
+
+await publishCommit(api, deployNames(), siteId, previousCommitId);
+```
+
+## What it does
+
+1. **Walks and hashes** the build, normalizing paths to POSIX and including
+   dotfiles (`.well-known/…` ships); exclude explicitly with `ignore`.
+2. **Detects content types** by extension, falling back to
+   `application/octet-stream` rather than guessing. Override with `contentTypes`.
+3. **Registers the bytes** in batches (`batchSize`, default 100) and PUTs only
+   the files the server reports as *not* deduplicated, with bounded concurrency
+   and retries — so a one-file change re-uploads one file.
+4. **Verifies** every returned key is the `cas/sha256/<hash>` it asked for.
+5. **Writes the manifest**: creates the site's release row on the first deploy,
+   patches it after, and asserts the trigger stamped a `commitId`/`storeId`.
+6. **Optionally publishes** and/or points `preview/<name>` at the new commit, as
+   separate steps.
+
+Ordering is the contract: bytes land before the manifest names them, and the
+manifest lands before anything points at it. A failure anywhere throws a
+`DeployError` with a `code` and leaves the live site untouched — an upload
+failure never becomes a published manifest with holes in it.
+
+Pass `onProgress` for `hashed` / `diffed` / `uploaded` / `manifest` / `preview` /
+`published` events, `dryRun` to hash and diff only, and `skipIfUnchanged` to
+reuse the live release when the tree already matches it.
+
+## Related
+
+- [`@constructive-io/upload-client`](../upload-client) — the generic presigned
+  upload primitives this builds on.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/cas-upload.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Content-addressed bulk upload.
+ *
+ * The generic pieces come from `@constructive-io/upload-client` (a presigned
+ * PUT); what is added here is the part a static release needs: many files in
+ * one round trip, explicit `cas/sha256/<hash>` keys, and skipping every file
+ * the server already has. That skip is the whole incremental-deploy win — a
+ * one-file change re-uploads one file however large the site is.
+ */
+import type { HashedFile } from './manifest';
+import type { GraphQLExecutor, PutObject } from './types';
+export interface UploadCasOptions {
+    /** Executor for the storage target. */
+    storage: GraphQLExecutor;
+    /** Bulk upload mutation field name, e.g. `uploadFiles`. */
+    mutation: string;
+    /** Bucket key of the site's bucket. */
+    bucketKey: string;
+    /** Files per mutation call. */
+    batchSize: number;
+    /** Parallel PUTs. */
+    concurrency: number;
+    /** Retries per PUT. */
+    retries: number;
+    putObject?: PutObject;
+    signal?: AbortSignal;
+    onUploaded?: (file: HashedFile) => void;
+}
+export interface UploadCasResult {
+    uploaded: number;
+    skipped: number;
+    bytesUploaded: number;
+}
+/** The bytes the server does not have yet, as told by the bulk mutation. */
+export interface CasDiff {
+    /** Files whose bytes must be PUT, paired with their presigned URL. */
+    missing: {
+        file: HashedFile;
+        uploadUrl: string;
+    }[];
+    /** Files the server already had. */
+    deduplicated: HashedFile[];
+}
+/**
+ * Register every file and learn which bytes are missing.
+ *
+ * Batched because the server caps files per call; one failed batch fails the
+ * whole diff rather than leaving a half-registered release.
+ */
+export declare function diffCas(files: HashedFile[], options: UploadCasOptions): Promise<CasDiff>;
+/**
+ * PUT the missing bytes.
+ *
+ * Any file that cannot be uploaded after its retries aborts the deploy: a
+ * manifest written over a partial upload is a site with holes in it.
+ */
+export declare function uploadMissing(diff: CasDiff, options: UploadCasOptions): Promise<UploadCasResult>;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function errorMessage(err: unknown): string;

package/cas-upload.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Content-addressed bulk upload.
+ *
+ * The generic pieces come from `@constructive-io/upload-client` (a presigned
+ * PUT); what is added here is the part a static release needs: many files in
+ * one round trip, explicit `cas/sha256/<hash>` keys, and skipping every file
+ * the server already has. That skip is the whole incremental-deploy win — a
+ * one-file change re-uploads one file however large the site is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCas = diffCas;
+exports.uploadMissing = uploadMissing;
+exports.throwIfAborted = throwIfAborted;
+exports.errorMessage = errorMessage;
+const upload_client_1 = require("@constructive-io/upload-client");
+const documents_1 = require("./documents");
+const manifest_1 = require("./manifest");
+const types_1 = require("./types");
+/**
+ * Register every file and learn which bytes are missing.
+ *
+ * Batched because the server caps files per call; one failed batch fails the
+ * whole diff rather than leaving a half-registered release.
+ */
+async function diffCas(files, options) {
+    const mutation = (0, documents_1.buildBulkUploadMutation)(options.mutation);
+    const missing = [];
+    const deduplicated = [];
+    for (let offset = 0; offset < files.length; offset += options.batchSize) {
+        throwIfAborted(options.signal);
+        const batch = files.slice(offset, offset + options.batchSize);
+        const data = await options.storage(mutation, {
+            input: {
+                bucketKey: options.bucketKey,
+                files: batch.map((file) => ({
+                    contentHash: file.hash,
+                    contentType: file.contentType,
+                    size: file.size,
+                    filename: file.path.slice(file.path.lastIndexOf('/') + 1),
+                    key: file.key,
+                })),
+            },
+        });
+        const payload = (data[options.mutation] ?? null);
+        const results = payload?.files;
+        if (!results || results.length !== batch.length) {
+            throw new types_1.DeployError('UPLOAD_FAILED', `${options.mutation} returned ${results?.length ?? 0} results for ${batch.length} files`);
+        }
+        results.forEach((result, index) => {
+            const file = batch[index];
+            // The server does not enforce the CAS key form yet, so a mismatch here
+            // would publish a manifest pointing at bytes nobody can serve.
+            if (result.key !== file.key || !manifest_1.CAS_KEY_PATTERN.test(result.key)) {
+                throw new types_1.DeployError('KEY_MISMATCH', `Expected key "${file.key}" for "${file.path}", server returned "${result.key}"`);
+            }
+            if (result.deduplicated) {
+                deduplicated.push(file);
+                return;
+            }
+            if (!result.uploadUrl) {
+                throw new types_1.DeployError('UPLOAD_FAILED', `No upload URL for "${file.path}" and deduplicated=false`);
+            }
+            missing.push({ file, uploadUrl: result.uploadUrl });
+        });
+    }
+    return { missing, deduplicated };
+}
+/**
+ * PUT the missing bytes.
+ *
+ * Any file that cannot be uploaded after its retries aborts the deploy: a
+ * manifest written over a partial upload is a site with holes in it.
+ */
+async function uploadMissing(diff, options) {
+    const put = options.putObject ?? defaultPut;
+    let bytesUploaded = 0;
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            throwIfAborted(options.signal);
+            const index = next++;
+            if (index >= diff.missing.length)
+                return;
+            const { file, uploadUrl } = diff.missing[index];
+            await withRetries(() => put(uploadUrl, file.bytes, file.contentType, options.signal), options.retries, file.path, options.signal);
+            bytesUploaded += file.size;
+            options.onUploaded?.(file);
+        }
+    };
+    const workers = Math.max(1, Math.min(options.concurrency, diff.missing.length));
+    await Promise.all(Array.from({ length: workers }, worker));
+    return {
+        uploaded: diff.missing.length,
+        skipped: diff.deduplicated.length,
+        bytesUploaded,
+    };
+}
+const defaultPut = async (url, body, contentType, signal) => {
+    // A fresh copy: putToPresignedUrl takes a BodyInit, and a Uint8Array view
+    // over a pooled Buffer would send the whole pool.
+    const buffer = body.slice().buffer;
+    await (0, upload_client_1.putToPresignedUrl)(url, buffer, contentType, signal);
+};
+async function withRetries(attempt, retries, path, signal) {
+    let lastError;
+    for (let tries = 0; tries <= retries; tries++) {
+        throwIfAborted(signal);
+        try {
+            await attempt();
+            return;
+        }
+        catch (err) {
+            lastError = err;
+            if (tries === retries)
+                break;
+            await delay(2 ** tries * 250);
+        }
+    }
+    throw new types_1.DeployError('UPLOAD_FAILED', `Upload of "${path}" failed after ${retries + 1} attempt(s): ${errorMessage(lastError)}`, lastError);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new types_1.DeployError('ABORTED', 'Deploy was cancelled');
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/content-type.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extension → MIME mapping for static builds.
+ *
+ * Deliberately small: it covers what a site generator emits. Anything else
+ * falls back to `application/octet-stream` rather than being guessed — the
+ * manifest's `content_type` is what the edge serves verbatim.
+ */
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Resolve the content type of a logical path.
+ *
+ * @param path - Logical path (`assets/app.js`)
+ * @param overrides - Extra or overriding mappings, keyed without the dot
+ */
+export declare function contentTypeFor(path: string, overrides?: Record<string, string>): string;

package/content-type.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Extension → MIME mapping for static builds.
+ *
+ * Deliberately small: it covers what a site generator emits. Anything else
+ * falls back to `application/octet-stream` rather than being guessed — the
+ * manifest's `content_type` is what the edge serves verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONTENT_TYPE = void 0;
+exports.contentTypeFor = contentTypeFor;
+exports.DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+const CONTENT_TYPES = {
+    avif: 'image/avif',
+    css: 'text/css; charset=utf-8',
+    csv: 'text/csv; charset=utf-8',
+    eot: 'application/vnd.ms-fontobject',
+    gif: 'image/gif',
+    htm: 'text/html; charset=utf-8',
+    html: 'text/html; charset=utf-8',
+    ico: 'image/x-icon',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    js: 'text/javascript; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    map: 'application/json; charset=utf-8',
+    md: 'text/markdown; charset=utf-8',
+    mjs: 'text/javascript; charset=utf-8',
+    mp3: 'audio/mpeg',
+    mp4: 'video/mp4',
+    otf: 'font/otf',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    svg: 'image/svg+xml',
+    ttf: 'font/ttf',
+    txt: 'text/plain; charset=utf-8',
+    wasm: 'application/wasm',
+    webm: 'video/webm',
+    webmanifest: 'application/manifest+json',
+    webp: 'image/webp',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    xml: 'application/xml',
+    yaml: 'text/yaml; charset=utf-8',
+    yml: 'text/yaml; charset=utf-8',
+    zip: 'application/zip',
+};
+/**
+ * Resolve the content type of a logical path.
+ *
+ * @param path - Logical path (`assets/app.js`)
+ * @param overrides - Extra or overriding mappings, keyed without the dot
+ */
+function contentTypeFor(path, overrides) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0)
+        return exports.DEFAULT_CONTENT_TYPE;
+    const ext = base.slice(dot + 1).toLowerCase();
+    return overrides?.[ext] ?? CONTENT_TYPES[ext] ?? exports.DEFAULT_CONTENT_TYPE;
+}

package/deploy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The deploy pipeline.
+ *
+ * Everything below the manifest is server-owned: writing the release row fires
+ * the trigger that commits the manifest into the site's own merkle store, so
+ * the commit id this returns *is* the release — history, time travel and
+ * rollback are then pointer moves, not client bookkeeping.
+ *
+ * Ordering is the contract: bytes land before the manifest names them, and the
+ * manifest lands before anything points at it. A failure anywhere leaves the
+ * live site exactly as it was.
+ */
+import type { DeploySiteOptions, DeploySiteResult, GraphQLExecutor, SiteDeployNames } from './types';
+/**
+ * Deploy a build as an immutable release.
+ *
+ * Hashes every file, uploads only the bytes the server does not already have,
+ * writes one manifest — and optionally publishes it or points a preview ref at
+ * it.
+ */
+export declare function deploySite(options: DeploySiteOptions): Promise<DeploySiteResult>;
+/** Move `site.activeCommitId` — the go-live and the rollback are one thing. */
+export declare function publishCommit(api: GraphQLExecutor, names: SiteDeployNames, siteId: string, commitId: string): Promise<void>;