@driggsby/deploy 0.0.1 → 0.2.1

package/dist/deploy.js

@@ -0,0 +1,188 @@
+// Runs one whole deploy against the API: offer the manifest, upload the
+// blobs the server doesn't have, finalize. Bounded concurrency, one retry on
+// a 503 upload, and one recovery round if finalize reports missing blobs —
+// then it stops and reports rather than looping.
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createApp, createVersion, finalizeVersion, uploadBlob, } from "./client.js";
+import { DeployApiError, DeployError } from "./errors.js";
+import {} from "./manifest.js";
+import { writeAssignedSlug } from "./project-config.js";
+import { quotedForTerminal } from "./terminal-text.js";
+const UPLOAD_CONCURRENCY = 4;
+// Deploys a project whose driggsby.json slug may not be an app yet. Apps
+// are created explicitly with a server-assigned slug (the readable name
+// plus a unique ending), so when the version post answers app_not_found,
+// this creates the app, persists the assigned slug into driggsby.json
+// BEFORE uploading anything (a deploy that dies mid-upload must never
+// strand an app the project forgot), and deploys to the assigned slug.
+export async function deployProjectFiles(api, projectDirectory, slug, collected, options) {
+    try {
+        const outcome = await deployCollectedFiles(api, slug, collected, options);
+        return { outcome, createdApp: null };
+    }
+    catch (error) {
+        if (!(error instanceof DeployApiError) || error.code !== "app_not_found") {
+            throw error;
+        }
+    }
+    const created = await createApp(api, slug, options.appName);
+    await writeAssignedSlug(projectDirectory, created.appSlug);
+    options.onAppCreated?.(created);
+    const outcome = await deployCollectedFiles(api, created.appSlug, collected, options);
+    return { outcome, createdApp: created };
+}
+export async function deployCollectedFiles(api, slug, collected, options) {
+    const created = await createVersion(api, slug, collected.files, options.appName);
+    const fileBySha = new Map();
+    for (const file of collected.files) {
+        if (!fileBySha.has(file.sha256)) {
+            fileBySha.set(file.sha256, file);
+        }
+    }
+    const uploadedShas = new Set();
+    let uploadedBytes = 0;
+    const uploadRound = async (shas) => {
+        // The server's missing-blob list is deduplicated defensively: a
+        // misbehaving server repeating one sha must not make the client re-PUT
+        // the same file over and over.
+        const toUpload = [...new Set(shas)].map((sha) => {
+            const file = fileBySha.get(sha);
+            if (file === undefined) {
+                throw new DeployError("The Driggsby deploy API asked for a file this deploy never offered.\n" +
+                    "Please deploy again from the start.");
+            }
+            return file;
+        });
+        await runWithConcurrencyLimit(toUpload, UPLOAD_CONCURRENCY, async (file, signal) => {
+            const bytes = await readFile(file.absolutePath);
+            assertUnchangedSinceHashing(file, bytes);
+            await uploadBlobWithOneRetry(api, file.sha256, bytes, signal);
+            if (!uploadedShas.has(file.sha256)) {
+                uploadedShas.add(file.sha256);
+                uploadedBytes += file.byteSize;
+            }
+        });
+    };
+    await uploadRound(created.missingBlobSha256s);
+    let outcome = await finalizeVersion(api, created.versionId, options.live);
+    if (outcome.kind === "blobs-missing") {
+        // The server can evict a pending blob between upload and finalize. One
+        // recovery round is enough for that; anything more means something is
+        // genuinely wrong and retrying would just loop.
+        await uploadRound(outcome.missingBlobSha256s);
+        outcome = await finalizeVersion(api, created.versionId, options.live);
+    }
+    if (outcome.kind === "blobs-missing") {
+        throw new DeployError("We uploaded this deploy's files, but the Driggsby deploy API kept\n" +
+            "reporting some as missing. Please deploy again in a minute.");
+    }
+    // Counted from what actually went over the wire, so blobs re-sent during
+    // the recovery round never read as "already on Driggsby".
+    const unchangedFileCount = collected.files.filter((file) => !uploadedShas.has(file.sha256)).length;
+    return {
+        appSlug: outcome.appSlug,
+        versionNumber: outcome.versionNumber,
+        live: outcome.live,
+        url: outcome.url,
+        fileCount: collected.files.length,
+        uploadedBlobCount: uploadedShas.size,
+        uploadedBytes,
+        unchangedFileCount,
+    };
+}
+// The manifest hashed this file during the walk; the upload re-reads it
+// from disk. If the bytes changed in between (a build still writing into
+// the serve folder), uploading them under the walk-time hash would publish
+// content nothing ever hashed — fail with the fix instead.
+function assertUnchangedSinceHashing(file, bytes) {
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (sha256 !== file.sha256) {
+        throw new DeployError(`${quotedForTerminal(file.path, 80)} changed while this deploy was running — a build may\n` +
+            "still have been writing into the serve folder. Let it finish and\n" +
+            "deploy again.");
+    }
+}
+// A 503 from blob storage is transient and the PUT is idempotent, so one
+// retry is safe. Without server guidance the retry waits a short default
+// pause, since an instant re-PUT usually lands on storage that is still
+// unhealthy and wastes the only retry the design allows. An explicit
+// Retry-After is taken at its word — including 0, the server saying "now" —
+// and capped so a bad header can't stall the deploy. A second 503 propagates
+// with the server's message.
+const DEFAULT_RETRY_DELAY_MS = 1_000;
+const MAX_RETRY_DELAY_MS = 5_000;
+export function retryDelayMs(error) {
+    if (error.retryAfterSeconds === null) {
+        return DEFAULT_RETRY_DELAY_MS;
+    }
+    return Math.min(error.retryAfterSeconds * 1_000, MAX_RETRY_DELAY_MS);
+}
+async function uploadBlobWithOneRetry(api, sha256, bytes, signal) {
+    try {
+        await uploadBlob(api, sha256, bytes, signal);
+    }
+    catch (error) {
+        if (error instanceof DeployApiError && error.status === 503 && signal?.aborted !== true) {
+            await sleep(retryDelayMs(error), signal);
+            await uploadBlob(api, sha256, bytes, signal);
+            return;
+        }
+        throw error;
+    }
+}
+// Resolves early if the signal aborts mid-pause — a worker sleeping out a
+// Retry-After must not keep the process alive after a sibling has already
+// failed the deploy. (The retry PUT after an early wake is refused
+// immediately by its aborted signal, so nothing extra reaches the wire.)
+function sleep(milliseconds, signal) {
+    if (milliseconds <= 0 || signal?.aborted === true) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        signal?.addEventListener("abort", finish, { once: true });
+    });
+}
+// A small worker pool: at most `limit` workers in flight, results in input
+// order, first failure rejects the whole run AND aborts the rest. Without
+// the abort, the failure's message would print while surviving uploads keep
+// running for minutes — a "deploy failed" line followed by a silent hang.
+// Workers receive the shared signal so they can cancel their in-flight
+// request; the pool itself also stops handing out new items once aborted.
+export async function runWithConcurrencyLimit(items, limit, worker) {
+    const results = new Array(items.length);
+    const queue = items.map((item, index) => ({ item, index }));
+    let cursor = 0;
+    const abort = new AbortController();
+    const runWorker = async () => {
+        for (;;) {
+            if (abort.signal.aborted) {
+                return;
+            }
+            const entry = queue[cursor];
+            if (entry === undefined) {
+                return;
+            }
+            cursor += 1;
+            try {
+                results[entry.index] = await worker(entry.item, abort.signal);
+            }
+            catch (error) {
+                abort.abort();
+                throw error;
+            }
+        }
+    };
+    const workerCount = Math.min(limit, items.length);
+    // Promise.all rejects with the FIRST failure — the real one — and it
+    // attaches handlers to every worker, so the aborted siblings' rejections
+    // are observed, not unhandled.
+    await Promise.all(Array.from({ length: workerCount }, () => runWorker()));
+    return results;
+}

package/dist/entrypoint.d.ts

@@ -0,0 +1,8 @@
+export interface EntrypointIo {
+    argv: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    out: (text: string) => void;
+    error: (text: string) => void;
+}
+export declare function runDeployEntrypoint(io: EntrypointIo): Promise<number>;

package/dist/entrypoint.js

@@ -0,0 +1,121 @@
+// The minimal `npx @driggsby/deploy` entrypoint for Node-only sandboxes:
+// deploy the current directory's driggsby.json project, authenticating with
+// the DRIGGSBY_TOKEN environment variable. The full experience (saved
+// sign-in, previews, rollback) lives in the driggsby CLI; this exists for
+// environments that can only run one command with an injected token.
+import { readFile } from "node:fs/promises";
+import { resolveBaseUrl } from "./base-url.js";
+import { deployProjectFiles } from "./deploy.js";
+import { DeployApiError, DeployError } from "./errors.js";
+import { collectDeployFiles, formatBytes } from "./manifest.js";
+import { readProjectConfig } from "./project-config.js";
+import { capForTerminal, quotedForTerminal, wrapProse } from "./terminal-text.js";
+// Server-supplied error text is bounded like every other string this bin did
+// not author (same cap as the driggsby CLI's deploy commands).
+const MAX_ERROR_DESCRIPTION_CHARS = 300;
+const USAGE = "Deploys the Driggsby app in the current directory, live.\n" +
+    "\n" +
+    "Usage:\n" +
+    "  npx @driggsby/deploy\n" +
+    "\n" +
+    "This is the whole interface: a bare invocation reads driggsby.json in the\n" +
+    'current directory, uploads its "serve" folder, and makes the result live\n' +
+    "at your app's address. It authenticates only through the DRIGGSBY_TOKEN\n" +
+    "environment variable.\n" +
+    "\n" +
+    "Previews, version history, rollback, and saved sign-in live in the full\n" +
+    "CLI:\n" +
+    "  npx driggsby@latest --help\n";
+export async function runDeployEntrypoint(io) {
+    // A bare invocation is the only one that deploys. Anything else — a help
+    // flag, a guessed --preview, a typo — must never trigger a live publish,
+    // because an agent probing an unfamiliar bin starts with `--help`.
+    if (io.argv.includes("-h") || io.argv.includes("--help")) {
+        io.out(USAGE);
+        return 0;
+    }
+    if (io.argv.includes("--version")) {
+        io.out(`${await packageVersion()}\n`);
+        return 0;
+    }
+    if (io.argv.length > 0) {
+        io.error(`Unrecognized argument: ${quotedForTerminal(io.argv[0] ?? "", 80)}\n` +
+            `Nothing was deployed.\n\n${USAGE}`);
+        return 2;
+    }
+    try {
+        const token = io.env.DRIGGSBY_TOKEN?.trim();
+        if (token === undefined || token === "") {
+            io.error("DRIGGSBY_TOKEN isn't set. This command authenticates only through that\n" +
+                "environment variable. On your own machine, use the full CLI instead:\n" +
+                "sign in once with npx driggsby@latest login, then run\n" +
+                "npx driggsby@latest deploy.\n");
+            return 1;
+        }
+        const baseUrl = resolveBaseUrl(io.env);
+        const config = await readProjectConfig(io.cwd);
+        const collected = await collectDeployFiles(config.serveDirectory);
+        const { outcome, createdApp } = await deployProjectFiles({ baseUrl, token }, io.cwd, config.slug, collected, { live: true });
+        if (createdApp !== null) {
+            // The assigned slug is server text, so it prints quoted and bounded
+            // like every other string this bin did not author; the whole sentence
+            // wraps because a maximum-length slug pushes it past 80 columns. The
+            // commit reminder matters most here: this bin targets ephemeral
+            // sandboxes, and a checkout that discards the rewritten driggsby.json
+            // creates a brand-new app at a new address on every run.
+            io.out(`${wrapProse(`Created your app as ${quotedForTerminal(createdApp.appSlug, 80)} — Driggsby assigns the final name (yours plus a unique ending) and saved it in driggsby.json. Commit that updated driggsby.json: it is the only record of your app's address, and without it the next deploy creates a second app.`)}\n`);
+        }
+        const uploadedNote = outcome.uploadedBlobCount === 0
+            ? "nothing new to upload — every file was already on Driggsby"
+            : `uploaded ${formatBytes(outcome.uploadedBytes)}`;
+        // The slug and URL come back from the server, so they are sanitized and
+        // length-bounded like every other string this bin did not author — and
+        // the slug prints quoted so it reads as a name, never as this bin's own
+        // sentence. The bounds never truncate legitimate values: a slug tops
+        // out at 63 characters and the app URL at 84.
+        io.out(`Deployed ${quotedForTerminal(outcome.appSlug, 80)} (v${outcome.versionNumber}, ${uploadedNote}).\n`);
+        if (outcome.url !== null) {
+            io.out(`Live at:\n\n  ${capForTerminal(outcome.url, 200)}\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof DeployApiError) {
+            // A 503's server description talks to the protocol client ("retry the
+            // same PUT"), so it gets copy written for the person or agent running
+            // this bin instead.
+            if (error.status === 503) {
+                io.error("Driggsby is briefly unavailable just now. Please run this command\n" +
+                    "again in a minute.\n");
+                return 1;
+            }
+            const description = capForTerminal(error.message, MAX_ERROR_DESCRIPTION_CHARS).trim();
+            io.error(description === ""
+                ? "The Driggsby deploy API refused this request without saying why.\nPlease try again in a minute.\n"
+                : `${wrapProse(description)}\n`);
+            return 1;
+        }
+        if (error instanceof DeployError) {
+            // Locally-authored message; any interpolated filesystem names were
+            // already sanitized where the message was built.
+            io.error(`${error.message}\n`);
+            return 1;
+        }
+        io.error("We weren't able to finish this deploy. Please try again in a minute.\n");
+        return 1;
+    }
+}
+// --version runs outside the deploy try block, so a failure here would
+// escape as a raw stack trace; an unreadable own-package.json — or one
+// missing its version field (an impossible install, effectively) — degrades
+// to "unknown" instead.
+async function packageVersion() {
+    try {
+        const raw = await readFile(new URL("../package.json", import.meta.url), "utf8");
+        const version = JSON.parse(raw).version;
+        return typeof version === "string" ? version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class DeployError extends Error {
+}
+export declare class DeployApiError extends DeployError {
+    readonly status: number;
+    readonly code: string;
+    readonly description: string;
+    readonly retryAfterSeconds: number | null;
+    constructor(status: number, code: string, description: string, retryAfterSeconds?: number | null);
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// Error types the deploy package throws. Messages are written to be shown to
+// a person or agent as-is: plain English, naming the fix, no internal detail.
+// A local problem (bad driggsby.json, an undeployable file) is a DeployError;
+// a response the deploy API refused is a DeployApiError carrying the server's
+// own user-facing description.
+import { quotedForTerminal } from "./terminal-text.js";
+export class DeployError extends Error {
+}
+export class DeployApiError extends DeployError {
+    status;
+    code;
+    description;
+    // Whole seconds from the response's Retry-After header, when it sent one.
+    retryAfterSeconds;
+    constructor(status, code, description, retryAfterSeconds = null) {
+        // The code is a server-supplied string, so the fallback message quotes
+        // and bounds it like every other text this package did not author (a
+        // real code is a short snake_case word).
+        super(description === ""
+            ? `The Driggsby deploy API refused this request (${quotedForTerminal(code, 40)}).`
+            : description);
+        this.status = status;
+        this.code = code;
+        this.description = description;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { DeployApiError, DeployError } from "./errors.ts";
+export { PUBLIC_BASE_URL, isLoopbackBaseUrl, resolveBaseUrl } from "./base-url.ts";
+export { MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_PATH_LENGTH, MAX_TOTAL_BYTES, slugProblem, } from "./limits.ts";
+export { type ProjectConfig, readProjectConfig, writeAssignedSlug } from "./project-config.ts";
+export { type CollectedDeploy, type DeployFile, collectDeployFiles, formatBytes, } from "./manifest.ts";
+export { type BlobsMissing, type CreatedApp, type CreatedVersion, type DeployApi, type FinalizedVersion, type ManifestFile, type VersionList, type VersionSummary, createApp, createVersion, finalizeVersion, listVersions, setLiveVersion, uploadBlob, } from "./client.ts";
+export { type DeployOptions, type DeployOutcome, type ProjectDeployOptions, type ProjectDeployResult, deployCollectedFiles, deployProjectFiles, } from "./deploy.ts";
+export { capForTerminal, quotedForTerminal, sanitizeForTerminal, wrapProse, } from "./terminal-text.ts";

package/dist/index.js

@@ -0,0 +1,17 @@
+// @driggsby/deploy: the Driggsby deploy protocol as a typed library.
+// The driggsby CLI's deploy/rollback/versions commands build on these
+// exports; Node-only sandboxes can use them directly.
+export { DeployApiError, DeployError } from "./errors.js";
+// The base-URL policy: which origin the token travels to, and what
+// DRIGGSBY_BASE_URL may override it with. One implementation for both this
+// package's bin and the driggsby CLI.
+export { PUBLIC_BASE_URL, isLoopbackBaseUrl, resolveBaseUrl } from "./base-url.js";
+export { MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_PATH_LENGTH, MAX_TOTAL_BYTES, slugProblem, } from "./limits.js";
+export { readProjectConfig, writeAssignedSlug } from "./project-config.js";
+export { collectDeployFiles, formatBytes, } from "./manifest.js";
+export { createApp, createVersion, finalizeVersion, listVersions, setLiveVersion, uploadBlob, } from "./client.js";
+export { deployCollectedFiles, deployProjectFiles, } from "./deploy.js";
+// Terminal-safety helpers for anything that echoes untrusted text (file
+// names, server strings) into CLI output. See terminal-text.ts for what the
+// sanitizer strips and the deliberate boundary of that defense.
+export { capForTerminal, quotedForTerminal, sanitizeForTerminal, wrapProse, } from "./terminal-text.js";

package/dist/limits.d.ts

@@ -0,0 +1,8 @@
+export declare const MAX_FILE_BYTES = 26214400;
+export declare const MAX_TOTAL_BYTES = 52428800;
+export declare const MAX_FILE_COUNT = 2000;
+export declare const MAX_PATH_LENGTH = 512;
+export declare const PATH_SEGMENT_PATTERN: RegExp;
+export declare const SLUG_PATTERN: RegExp;
+export declare const SLUG_PUNYCODE_PATTERN: RegExp;
+export declare function slugProblem(slug: string): string | null;

package/dist/limits.js

@@ -0,0 +1,28 @@
+// Server-enforced deploy limits, mirrored client-side so a bad deploy fails
+// fast with a clear local message instead of a round trip. Values match the
+// Driggsby deploy API; the server remains the authority.
+export const MAX_FILE_BYTES = 26_214_400; // 25 MiB per file (prints as 26.2 MB)
+export const MAX_TOTAL_BYTES = 52_428_800; // 50 MiB per version (prints as 52.4 MB)
+export const MAX_FILE_COUNT = 2_000;
+export const MAX_PATH_LENGTH = 512;
+// A path segment the deploy API accepts: ASCII letters, digits, dot, dash,
+// underscore. No spaces, no path tricks, nothing percent-encoded.
+export const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+// App slugs: 3-63 chars, lowercase letters/digits/dashes, no leading or
+// trailing dash, and no "xn--"-style label (dashes in positions 3 and 4).
+// There is no reserved-name list to mirror: Driggsby assigns every app's
+// final address by adding a unique ending to the name you pick, so any
+// readable name works and names never collide.
+export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/;
+export const SLUG_PUNYCODE_PATTERN = /^..--/;
+// Returns a human-readable problem with the slug, or null when it is valid.
+export function slugProblem(slug) {
+    if (!SLUG_PATTERN.test(slug)) {
+        return ("an app slug must be 3-63 characters of lowercase letters, digits, and\n" +
+            "dashes, and must start and end with a letter or digit");
+    }
+    if (SLUG_PUNYCODE_PATTERN.test(slug)) {
+        return "an app slug can't have dashes in its third and fourth characters";
+    }
+    return null;
+}

package/dist/manifest.d.ts

@@ -0,0 +1,21 @@
+export interface DeployFile {
+    path: string;
+    absolutePath: string;
+    byteSize: number;
+    sha256: string;
+}
+export interface CollectedDeploy {
+    files: DeployFile[];
+    totalBytes: number;
+    skippedSymlinks: string[];
+    skippedNodeModules: string[];
+}
+export interface CollectOptions {
+    limitOverridesForTests?: {
+        maxFileBytes?: number;
+        maxTotalBytes?: number;
+        maxFileCount?: number;
+    };
+}
+export declare function collectDeployFiles(serveDirectory: string, options?: CollectOptions): Promise<CollectedDeploy>;
+export declare function formatBytes(bytes: number): string;

package/dist/manifest.js

@@ -0,0 +1,181 @@
+// Walks the serve directory into the deploy manifest: every deployable file
+// with its SHA-256 and byte size. The exclusions here are a safety boundary,
+// not tidiness — the deploy API serves whatever it is given, so dotfiles
+// (.env, .git) at any depth and the serve root's own driggsby.json must
+// never leave this machine. (A nested driggsby.json is an ordinary file: it
+// belongs to whatever subfolder carries it, not to this deploy.)
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { DeployError } from "./errors.js";
+import { quotedForTerminal } from "./terminal-text.js";
+import { MAX_FILE_BYTES, MAX_FILE_COUNT, MAX_PATH_LENGTH, MAX_TOTAL_BYTES, PATH_SEGMENT_PATTERN, } from "./limits.js";
+export async function collectDeployFiles(serveDirectory, options = {}) {
+    const maxFileBytes = options.limitOverridesForTests?.maxFileBytes ?? MAX_FILE_BYTES;
+    const maxTotalBytes = options.limitOverridesForTests?.maxTotalBytes ?? MAX_TOTAL_BYTES;
+    const maxFileCount = options.limitOverridesForTests?.maxFileCount ?? MAX_FILE_COUNT;
+    const files = [];
+    const skippedSymlinks = [];
+    const skippedNodeModules = [];
+    // Count and total-size limits are enforced INSIDE the walk, before each
+    // file is hashed — a limit must fail as soon as it is crossed, not after
+    // reading and SHA-256ing hundreds of megabytes that were never going to
+    // deploy.
+    const limits = { maxFileBytes, maxTotalBytes, maxFileCount };
+    // silentlySkippedCount covers the entries the walk drops without reporting
+    // them to the caller (dotfiles, dot-directories, the top-level
+    // driggsby.json) — the empty-folder message below must still know they
+    // were there.
+    const tally = { totalBytes: 0, silentlySkippedCount: 0 };
+    await walkDirectory(serveDirectory, [], files, {
+        skippedSymlinks,
+        skippedNodeModules,
+        limits,
+        tally,
+    });
+    files.sort((a, b) => (a.path < b.path ? -1 : 1));
+    if (files.length === 0) {
+        // When the folder isn't actually empty, saying "has no files" would
+        // contradict what the user sees in front of them — name what happened.
+        if (skippedSymlinks.length > 0 ||
+            skippedNodeModules.length > 0 ||
+            tally.silentlySkippedCount > 0) {
+            throw new DeployError("There's nothing to deploy — everything in the serve folder was\n" +
+                "skipped (symlinks, node_modules, dotfiles, and driggsby.json itself\n" +
+                "never deploy). Add your app's files (starting with index.html) and\n" +
+                "deploy again.");
+        }
+        throw new DeployError("There's nothing to deploy — the serve folder has no files. Add your\n" +
+            "app's files (starting with index.html) and deploy again.");
+    }
+    requireIndexHtml(files);
+    const totalBytes = files.reduce((sum, file) => sum + file.byteSize, 0);
+    return { files, totalBytes, skippedSymlinks, skippedNodeModules };
+}
+async function walkDirectory(absoluteDirectory, segments, files, state) {
+    let entries;
+    try {
+        entries = await readdir(absoluteDirectory, { withFileTypes: true });
+    }
+    catch {
+        throw new DeployError(segments.length === 0
+            ? 'We couldn\'t read the serve folder named in driggsby.json. Check its\n"serve" value and try again.'
+            : `We couldn't read the folder ${quotedForTerminal(segments.join("/"), 80)} inside the\nserve folder. Check it and try again.`);
+    }
+    for (const entry of entries) {
+        // Dotfiles and dot-directories never deploy: they are where secrets and
+        // repo internals live (.env, .git), and the deployed app serves every
+        // uploaded file to the internet.
+        if (entry.name.startsWith(".")) {
+            state.tally.silentlySkippedCount += 1;
+            continue;
+        }
+        if (segments.length === 0 && entry.name === "driggsby.json") {
+            state.tally.silentlySkippedCount += 1;
+            continue;
+        }
+        const relativePath = [...segments, entry.name].join("/");
+        // Symlinks never deploy: following one would publish content from
+        // outside the serve folder. (Hard links are indistinguishable from
+        // regular files and deploy normally — build tools legitimately
+        // hard-link outputs, and anyone able to create one inside this folder
+        // could just as well copy the file here.)
+        if (entry.isSymbolicLink()) {
+            state.skippedSymlinks.push(relativePath);
+            continue;
+        }
+        if (entry.isDirectory()) {
+            // node_modules never deploys: Driggsby apps are served as static
+            // files, so a dependency tree is dev-machine clutter that would blow
+            // the file-count limit — and its scoped-package folders (@types, ...)
+            // would otherwise trip the character check with a "rename it" message
+            // that is exactly wrong for the most common first-run mistake
+            // (pointing "serve" at a project root).
+            if (entry.name === "node_modules") {
+                state.skippedNodeModules.push(relativePath);
+                continue;
+            }
+            validateSegment(entry.name, relativePath, segments.length === 0);
+            await walkDirectory(join(absoluteDirectory, entry.name), [...segments, entry.name], files, state);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        validateSegment(entry.name, relativePath, segments.length === 0);
+        if (relativePath.length > MAX_PATH_LENGTH) {
+            throw new DeployError(`One file's path is too long to deploy (over ${MAX_PATH_LENGTH} characters):\n` +
+                `${quotedForTerminal(relativePath, 80)}...\nShorten the folder or file names and deploy again.`);
+        }
+        const absolutePath = join(absoluteDirectory, entry.name);
+        const info = await stat(absolutePath);
+        if (info.size > state.limits.maxFileBytes) {
+            throw new DeployError(`${quotedForTerminal(relativePath, 80)} is ${formatBytes(info.size)}, and a single file can\n` +
+                `be at most ${formatBytes(state.limits.maxFileBytes)}. Shrink or remove it and deploy again.`);
+        }
+        if (files.length >= state.limits.maxFileCount) {
+            throw new DeployError(`This deploy has more than ${state.limits.maxFileCount} files, and that's as many as a\n` +
+                "Driggsby app can hold. Remove what the app doesn't need and deploy\nagain.");
+        }
+        state.tally.totalBytes += info.size;
+        if (state.tally.totalBytes > state.limits.maxTotalBytes) {
+            throw new DeployError(`This deploy is over ${formatBytes(state.limits.maxTotalBytes)} in total, and that's as much as a\n` +
+                "Driggsby app can hold. Slim it down and deploy again.");
+        }
+        files.push({
+            path: relativePath,
+            absolutePath,
+            byteSize: info.size,
+            sha256: await sha256File(absolutePath),
+        });
+    }
+}
+function validateSegment(name, relativePath, isTopLevel) {
+    // "-" is a valid character but a reserved top-level name: Driggsby serves
+    // its own pages under the app's /-/ namespace. Deeper down, "-" is an
+    // ordinary name the deploy API accepts.
+    if (isTopLevel && name === "-") {
+        throw new DeployError(`${quotedForTerminal(relativePath, 80)} can't be deployed: "-" is a name Driggsby reserves\n` +
+            "for its own pages on your app's address. Rename it and deploy again.");
+    }
+    if (!PATH_SEGMENT_PATTERN.test(name) || name === "." || name === "..") {
+        throw new DeployError(`${quotedForTerminal(relativePath, 80)} can't be deployed: file and folder names may only\n` +
+            "use letters, digits, dots, dashes, and underscores (no spaces). Rename\n" +
+            "it and deploy again.");
+    }
+}
+function requireIndexHtml(files) {
+    if (files.some((file) => file.path === "index.html")) {
+        return;
+    }
+    const hasPackageJson = files.some((file) => file.path === "package.json");
+    const buildHint = hasPackageJson
+        ? "\n\nThis looks like a project that needs a build step. Run your build, then\n" +
+            'point "serve" in driggsby.json at the build output folder (often "dist"\n' +
+            'or "build") — Driggsby apps deploy as static files.'
+        : "";
+    throw new DeployError("The serve folder has no index.html at its top level, so the deployed app\n" +
+        "would show an empty page. Add an index.html (or point \"serve\" in\n" +
+        `driggsby.json at the folder that has one) and deploy again.${buildHint}`);
+}
+async function sha256File(absolutePath) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(absolutePath), hash);
+    return hash.digest("hex");
+}
+export function formatBytes(bytes) {
+    if (bytes < 1_000) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1_000_000) {
+        return `${trimmedFixed(bytes / 1_000)} KB`;
+    }
+    return `${trimmedFixed(bytes / 1_000_000)} MB`;
+}
+// 6.2, but 42 (not 42.0) — one decimal only when it says something.
+function trimmedFixed(value) {
+    const rounded = value >= 100 ? Math.round(value).toString() : value.toFixed(1);
+    return rounded.endsWith(".0") ? rounded.slice(0, -2) : rounded;
+}

package/dist/project-config.d.ts

@@ -0,0 +1,8 @@
+export interface ProjectConfig {
+    slug: string;
+    serveDirectory: string;
+    serve: string;
+    devCommand: string | null;
+}
+export declare function readProjectConfig(projectDirectory: string): Promise<ProjectConfig>;
+export declare function writeAssignedSlug(projectDirectory: string, assignedSlug: string): Promise<void>;