@driggsby/deploy 0.0.1 → 0.2.1

package/dist/project-config.js

@@ -0,0 +1,145 @@
+// Reads and validates the project's driggsby.json. This is the one file that
+// names the app (slug) and what to publish (serve). Validation mirrors the
+// deploy API's slug rules so mistakes fail fast, locally, with the fix.
+import { readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join, relative, resolve, isAbsolute } from "node:path";
+import { DeployError } from "./errors.js";
+import { slugProblem } from "./limits.js";
+import { quotedForTerminal } from "./terminal-text.js";
+const MISSING_CONFIG_MESSAGE = "No driggsby.json found in this directory. Create one next to the files you\n" +
+    "want to deploy:\n\n" +
+    '  { "slug": "your-app-name", "serve": "." }\n\n' +
+    '"slug" names your app — the first deploy gives it a unique address like\n' +
+    'your-app-name-x7k2qf.driggsby.dev and saves that assigned name back into\n' +
+    'this file — and "serve" is the folder to publish, relative to\n' +
+    "driggsby.json.";
+export async function readProjectConfig(projectDirectory) {
+    const configPath = join(projectDirectory, "driggsby.json");
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch {
+        throw new DeployError(MISSING_CONFIG_MESSAGE);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new DeployError("driggsby.json isn't valid JSON. It should look like:\n\n" +
+            '  { "slug": "your-app-name", "serve": "." }');
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new DeployError('driggsby.json must be a JSON object with a "slug" field.');
+    }
+    const config = parsed;
+    const slug = config.slug;
+    if (typeof slug !== "string" || slug === "") {
+        throw new DeployError('driggsby.json is missing its "slug" field. Add one:\n\n' +
+            '  { "slug": "your-app-name", "serve": "." }');
+    }
+    const problem = slugProblem(slug);
+    if (problem !== null) {
+        throw new DeployError(`The "slug" in driggsby.json won't work: ${problem}.`);
+    }
+    // Only a genuinely absent "serve" defaults to "." — `?? "."` would let an
+    // explicit `"serve": null` silently publish the whole project root, while
+    // every other malformed value fails closed below.
+    const serve = config.serve === undefined ? "." : config.serve;
+    if (typeof serve !== "string" || serve === "") {
+        throw new DeployError('The "serve" field in driggsby.json must be a folder path relative to\n' +
+            'driggsby.json, like "." or "dist".');
+    }
+    const serveDirectory = await resolveServeDirectory(projectDirectory, serve);
+    // dev_command is attacker-controlled text from a cloned or generated
+    // driggsby.json. Nothing executes it today; any future consumer must spawn
+    // it without a shell and never let it reach one.
+    const devCommand = config.dev_command;
+    return {
+        slug,
+        serveDirectory,
+        serve,
+        devCommand: typeof devCommand === "string" && devCommand !== "" ? devCommand : null,
+    };
+}
+// Persists the server-assigned slug into driggsby.json, keeping every other
+// field as-is. This runs after the app is created and BEFORE any bytes
+// upload, so a deploy that dies mid-upload never strands an app whose name
+// the project forgot. A failed write aborts the deploy with the manual fix,
+// because deploying on without saving the name would create a second app on
+// the next run.
+export async function writeAssignedSlug(projectDirectory, assignedSlug) {
+    const configPath = join(projectDirectory, "driggsby.json");
+    let config;
+    try {
+        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("driggsby.json is not a JSON object");
+        }
+        config = parsed;
+        config.slug = assignedSlug;
+        // Temp-file-plus-rename, so a crash mid-write can never leave a
+        // truncated driggsby.json holding half of a name only the server knows.
+        // The temp name starts with a dot: the deploy walk excludes dotfiles at
+        // every depth, so a leftover from a crash between write and rename can
+        // never be swept into a later deploy and published.
+        const temporaryPath = join(projectDirectory, `.driggsby.json.${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+            await rename(temporaryPath, configPath);
+        }
+        catch (error) {
+            await rm(temporaryPath, { force: true });
+            throw error;
+        }
+    }
+    catch {
+        // The assigned slug came from the server, so it prints through
+        // quotedForTerminal like every other string this package did not author.
+        throw new DeployError(`Driggsby created your app as ${quotedForTerminal(assignedSlug, 80)}, but we couldn't save\n` +
+            'that name into driggsby.json. Update its "slug" field to exactly that\n' +
+            "value, then deploy again.");
+    }
+}
+const SERVE_ESCAPES_PROJECT_MESSAGE = 'The "serve" folder in driggsby.json must stay inside the project —\n' +
+    'a value like "." or "dist", not a path outside it.';
+// Everything under the serve folder is uploaded and served publicly, so the
+// stay-inside-the-project boundary must hold on real paths, not just the
+// written value: checking the string alone would let a serve folder that is
+// (or sits under) a symlink pointing outside the project leak outside files
+// into the deploy. A serve folder that doesn't exist yet skips the realpath
+// check — versions and rollback never read it, and the deploy walk reports
+// that case with its own message. The returned path stays as written (only
+// the check uses real paths), so paths shown to the user match their config.
+async function resolveServeDirectory(projectDirectory, serve) {
+    const projectRoot = resolve(projectDirectory);
+    const serveDirectory = resolve(projectRoot, serve);
+    if (escapesRoot(relative(projectRoot, serveDirectory))) {
+        throw new DeployError(SERVE_ESCAPES_PROJECT_MESSAGE);
+    }
+    let realProjectRoot;
+    let realServeDirectory;
+    try {
+        realProjectRoot = await realpath(projectRoot);
+        realServeDirectory = await realpath(serveDirectory);
+    }
+    catch (error) {
+        // Only "it doesn't exist yet" may skip the check; any other resolution
+        // failure (permissions, symlink loops) fails closed rather than walking
+        // an unverified path.
+        if (error.code === "ENOENT") {
+            return serveDirectory;
+        }
+        throw new DeployError('We couldn\'t check the "serve" folder named in driggsby.json. Check its\n' +
+            '"serve" value and try again.');
+    }
+    if (escapesRoot(relative(realProjectRoot, realServeDirectory))) {
+        throw new DeployError(SERVE_ESCAPES_PROJECT_MESSAGE);
+    }
+    return serveDirectory;
+}
+function escapesRoot(relativePath) {
+    return relativePath.startsWith("..") || isAbsolute(relativePath);
+}

package/dist/terminal-text.d.ts

@@ -0,0 +1,4 @@
+export declare function sanitizeForTerminal(value: string): string;
+export declare function capForTerminal(value: string, maxChars: number): string;
+export declare function quotedForTerminal(value: string, maxChars: number): string;
+export declare function wrapProse(text: string, width?: number): string;

package/dist/terminal-text.js

@@ -0,0 +1,106 @@
+// File and folder names from the serve tree get echoed back in error
+// messages, and terminals interpret control bytes (ANSI/OSC escapes,
+// carriage returns, C1 controls), while bidi or zero-width characters can
+// visually reorder or hide parts of a line. Strip them before interpolating
+// any name this package did not author -- an agent-generated or cloned app
+// folder is a realistic path for such bytes to reach a terminal. This file
+// is the single home of these helpers: the driggsby CLI re-exports them
+// (this package itself ships with zero dependencies).
+//
+// The deliberate boundary of this defense: stripping stops untrusted text
+// from corrupting the terminal (escapes, control bytes) or hiding content
+// (zero-width, bidi, default-ignorable code points). It does NOT try to
+// stop a reader from trusting VISIBLE words inside a filename or server
+// string -- no output transform can, because the text is displayed either
+// way. Callers make provenance obvious instead: untrusted values print
+// inside quotes with a hard length cap (quotedForTerminal), so they read as
+// names, not as the CLI's own voice.
+// The strip set covers C0/DEL/C1 controls, U+061C ARABIC LETTER MARK (the
+// remaining Bidi_Control code point), zero-width joiners/marks, the
+// deprecated bidi embeddings/overrides, and the bidi isolates.
+// C0 whitespace (tab, newlines, carriage return) and the Unicode line and
+// paragraph separators (U+2028/U+2029, which some renderers break on)
+// become a space rather than vanishing: deleting a newline glues its
+// neighboring words together ("tryagain"), while a space keeps the text
+// readable and lets wrapProse re-flow it. The strip set also drops the
+// soft hyphen, the Mongolian vowel separator, the interlinear annotation
+// controls (U+FFF9-U+FFFB), the word joiner and invisible operators
+// (U+2060-U+2069, which also covers the bidi isolates), and U+FEFF
+// (ZWNBSP/BOM). The final pass strips Unicode's ENTIRE default-ignorable
+// set -- the Tags block, variation selectors, Mongolian selectors, musical
+// format controls, Hangul fillers, and friends -- because enumerated
+// blocks kept leaving smuggling channels for invisible instructions into
+// an agent's transcript; the property escape closes the whole class at
+// once. (This also strips U+FE0F, so emoji lose their explicit
+// presentation selector -- an acceptable cost.) Invisible or
+// renderer-dependent code points have no place in CLI output.
+export function sanitizeForTerminal(value) {
+    return (value
+        .replace(/[\t\n\v\f\r\u2028\u2029]/g, " ")
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001F\u007F-\u009F\u00AD\u061C\u180E\u200B-\u200F\u202A-\u202E\u2060-\u2069\uFEFF\uFFF9-\uFFFB]/g, "")
+        .replace(/\p{Default_Ignorable_Code_Point}/gu, ""));
+}
+// Sanitize plus a hard length bound, dropping an orphaned trailing high
+// surrogate so the cut never emits a lone half of a surrogate pair. For any
+// untrusted string headed to a terminal whose legitimate length is known.
+export function capForTerminal(value, maxChars) {
+    return sanitizeForTerminal(value).slice(0, maxChars).replace(/[\uD800-\uDBFF]$/, "");
+}
+// capForTerminal with the provenance quotes built in. The quotes are what
+// mark a value as untrusted, so the helper owns them: a double quote inside
+// the value (or one produced by capping) would close the quotation early and
+// let the rest of the payload read as the CLI's own sentence. Double quotes
+// become single quotes — lossless enough for a name — so the rendered value
+// always carries exactly one balanced pair. Every untrusted value printed
+// inside quotes goes through here, never through hand-placed quote marks.
+export function quotedForTerminal(value, maxChars) {
+    return `"${capForTerminal(value, maxChars).replaceAll('"', "'")}"`;
+}
+// Hard-wraps one paragraph of prose at the given width so lines built from
+// dynamic parts (server-supplied error descriptions) never overflow an
+// 80-column terminal. A single word longer than the width is hard-split at
+// the width -- a space-free server string must not become one overflowing
+// line. The input must be a single paragraph with no embedded newlines --
+// only U+0020 spaces are treated as break points.
+export function wrapProse(text, width = 76) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ").flatMap((long) => splitLongWord(long, width))) {
+        if (line === "") {
+            line = word;
+        }
+        else if (line.length + 1 + word.length <= width) {
+            line = `${line} ${word}`;
+        }
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line !== "") {
+        lines.push(line);
+    }
+    return lines.join("\n");
+}
+function splitLongWord(word, width) {
+    if (word.length <= width) {
+        return [word];
+    }
+    // Split by code point, not code unit: a surrogate pair (an emoji in a
+    // server error description) straddling the boundary must never be cut
+    // into two lone surrogates.
+    const pieces = [];
+    let piece = "";
+    for (const codePoint of word) {
+        if (piece.length + codePoint.length > width) {
+            pieces.push(piece);
+            piece = "";
+        }
+        piece += codePoint;
+    }
+    if (piece !== "") {
+        pieces.push(piece);
+    }
+    return pieces;
+}

package/package.json

@@ -1,10 +1,37 @@
 {
   "name": "@driggsby/deploy",
-  "version": "0.0.1",
-  "description": "Deploy static apps to Driggsby. This version is a name reservation; the real package arrives with the next release.",
-  "license": "MIT",
+  "version": "0.2.1",
+  "description": "Deploy static Driggsby apps: the deploy protocol client used by the driggsby CLI.",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/driggsby/driggsby.git"
+  },
+  "homepage": "https://driggsby.com",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "driggsby-deploy": "bin/driggsby-deploy.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "!dist/.tsbuildinfo",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build",
+    "test": "node --test \"src/**/*.test.ts\""
+  },
+  "engines": {
+    "node": ">=18"
   }
 }