@astralarium/repo-deploy-release 0.0.0-stage → 0.2.0

package/dist/src/process.js

@@ -0,0 +1,68 @@
+/** Child processes, pauses and the exit status of one invocation. */
+import { spawn } from "node:child_process";
+import { setTimeout } from "node:timers/promises";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+/** Exit status after Ctrl-C. */
+export const INTERRUPT_EXIT = 130;
+/** Ctrl-C: exits `INTERRUPT_EXIT`. */
+export class Interrupted extends ExpectedError {
+    constructor() {
+        super("interrupted");
+        this.name = "Interrupted";
+    }
+}
+/** Children `run` has started that are still running. */
+const children = new Set();
+/** SIGKILLs every running child. */
+export function killChildren() {
+    for (const child of children)
+        child.kill("SIGKILL");
+}
+/** Logs `error` as the command's failure and sets the exit status:
+ *  `INTERRUPT_EXIT` after Ctrl-C, else 1. */
+export function reportFailure(error) {
+    log.error("deploy_release.failed", "deploy-release failed", {
+        exception: error,
+    });
+    process.exitCode = error instanceof Interrupted ? INTERRUPT_EXIT : 1;
+}
+/** Why `signal` aborted, as an error. */
+export const abortReason = (signal) => signal.reason instanceof Error ? signal.reason : new Interrupted();
+/** Runs `cmd` with `args` until it exits; resolves to its stdout when
+ *  captured. Throws on a nonzero exit, and with `signal`'s reason once it
+ *  aborts (killing the child). */
+export function run(cmd, args, signal, { cwd, env, input, capture = false, quiet = false } = {}) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            cwd,
+            env: { ...process.env, ...env },
+            signal,
+            stdio: [
+                input === undefined ? "inherit" : "pipe",
+                capture ? "pipe" : "inherit",
+                quiet ? "pipe" : "inherit",
+            ],
+        });
+        children.add(child);
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8").on("data", (d) => (stdout += d));
+        child.stderr?.setEncoding("utf8").on("data", (d) => (stderr += d));
+        child.stdin?.end(input);
+        child.on("error", (e) => reject(signal.aborted ? abortReason(signal) : e));
+        child.on("close", (code, killed) => {
+            children.delete(child);
+            if (signal.aborted)
+                reject(abortReason(signal));
+            else if (code === 0)
+                resolve(stdout);
+            else
+                reject(new ExpectedError(`${[cmd, ...args].join(" ")} ${killed ? `died of ${killed}` : `exited with ${code}`}${stderr ? `:\n${stderr.trim()}` : ""}`));
+        });
+    });
+}
+/** Resolves after `ms`; throws `signal`'s reason once it aborts. */
+export const sleep = (ms, signal) => setTimeout(ms, undefined, { signal }).catch(() => {
+    throw abortReason(signal);
+});

package/dist/src/prompt.d.ts

@@ -0,0 +1,5 @@
+/** True when the operator answers y or yes, any case, to `question`. */
+export declare function confirm(question: string, signal: AbortSignal): Promise<boolean>;
+/** Reads a line after `question`, hidden; Ctrl-C interrupts as SIGINT
+ *  does. */
+export declare function readSecret(question: string, signal: AbortSignal): Promise<string>;

package/dist/src/prompt.js

@@ -0,0 +1,69 @@
+/** Operator prompts on stderr. */
+import { createInterface } from "node:readline/promises";
+import { abortReason, Interrupted } from "./process.js";
+/** Reads one line after `question`. */
+async function readLine(question, signal) {
+    // Terminal mode would echo piped input, a pasted token included.
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: false,
+    });
+    try {
+        return await rl.question(question, { signal });
+    }
+    catch (e) {
+        if (signal.aborted)
+            throw abortReason(signal);
+        // readline closes on Ctrl-C, rejecting with an AbortError.
+        throw e instanceof Error && e.name === "AbortError" ? new Interrupted() : e;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** True when the operator answers y or yes, any case, to `question`. */
+export async function confirm(question, signal) {
+    return /^y(?:es)?$/i.test((await readLine(question, signal)).trim());
+}
+/** Reads a line after `question`, hidden; Ctrl-C interrupts as SIGINT
+ *  does. */
+export function readSecret(question, signal) {
+    const { stdin, stderr } = process;
+    if (!stdin.isTTY)
+        return readLine(question, signal);
+    signal.throwIfAborted();
+    stderr.write(question);
+    stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.resume();
+    return new Promise((resolve, reject) => {
+        let text = "";
+        const finish = (settle) => {
+            stdin.off("data", onData);
+            signal.removeEventListener("abort", onAbort);
+            stdin.setRawMode(false);
+            stdin.pause();
+            stderr.write("\n");
+            settle();
+        };
+        const onAbort = () => finish(() => reject(abortReason(signal)));
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n")
+                    return finish(() => resolve(text));
+                if (ch === "\u0003")
+                    return finish(() => {
+                        process.kill(process.pid, "SIGINT");
+                        reject(new Interrupted());
+                    });
+                if (ch === "\u007f" || ch === "\b")
+                    text = text.slice(0, -1);
+                else if (ch >= " ")
+                    text += ch;
+            }
+        };
+        stdin.on("data", onData);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/src/provision.d.ts

@@ -0,0 +1,36 @@
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** One thing an env lacks, and how to supply it. */
+export interface Gap {
+    /** What it holds up: `config` commands deploying from its package's
+     *  config, `secrets` the `secrets` upload, `database` commands on the
+     *  deploy state; a `template` gap holds up the next operator's copy
+     *  alone. */
+    area: "config" | "secrets" | "database" | "template";
+    /** Workspace package whose wrangler config holds it; absent for a gap
+     *  of the env as a whole. */
+    package?: string;
+    /** File and field, or variable, holding it. */
+    where: string;
+    /** What is missing or unset there. */
+    problem: string;
+    /** The next step closing it. */
+    step: string;
+}
+/** `path` as messages show it: relative to the workspace root when
+ *  within it. */
+export declare function shown(path: string): string;
+/** Gaps of env block `block` (named `where`) in the bindings it declares:
+ *  a resource field malformed or left at `PLACEHOLDER`, and a binding of
+ *  config top level `top` it lacks. */
+export declare function bindingGaps(block: Readonly<Record<string, unknown>>, top: Readonly<Record<string, unknown>>, where: string): Gap[];
+/** Gaps of secrets file `file`'s `.tmpl` in naming `keys`: a missing
+ *  template, a key it lacks. */
+export declare function templateGaps(file: string, keys: readonly string[]): Gap[];
+/** Gaps of secrets file `file` in holding `keys`: a missing file, a key
+ *  unset, empty or at `SECRET_PLACEHOLDER`. */
+export declare function secretsGaps(file: string, keys: readonly string[]): Gap[];
+/** The gap of `env`'s database URL variable `variable`, unset. */
+export declare const databaseGap: (env: string, variable: string) => Gap;
+/** The refusal of a command on `env` while `gaps` hold it up, pointing at
+ *  `check` under `invocation`. */
+export declare function unprovisioned(invocation: string, env: string, gaps: readonly Gap[]): ExpectedError;

package/dist/src/provision.js

@@ -0,0 +1,230 @@
+/** Provisioning: what an env still needs before its commands run, each
+ *  gap with its next step. Reads files and the process environment only. */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { parseEnv } from "node:util";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { ownWorkspaceRoot } from "./workspace.js";
+/** `path` as messages show it: relative to the workspace root when
+ *  within it. */
+export function shown(path) {
+    const within = relative(ownWorkspaceRoot(), path);
+    return within.startsWith("..") || isAbsolute(within) ? path : within;
+}
+/** An unprovisioned resource id: its kind's shape with every digit zero
+ *  (`00000000000000000000000000000000`, a zero UUID, `0`). */
+const PLACEHOLDER = /^0+(?:-0+)*$/;
+/** A secret's value in a `.tmpl`, unset in a copy still holding it. */
+const SECRET_PLACEHOLDER = "xxxx";
+/** 32 lowercase hex digits: Hyperdrive and KV ids. */
+const HEX32 = /^[0-9a-f]{32}$/;
+/** A lowercase UUID: D1 database ids. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** A queue name. */
+const QUEUE = {
+    field: "queue",
+    shape: "queue name (1-63 lowercase letters, digits, hyphens)",
+    test: /^[a-z0-9][a-z0-9-]{0,62}$/,
+    placeholder: false,
+    step: () => "Name the queue here; create it with wrangler queues create <name>.",
+};
+/** `entry[field]` when a non-empty string, else `fallback`. */
+function named(entry, field, fallback) {
+    const value = entry[field];
+    return typeof value === "string" && value ? value : fallback;
+}
+/** Binding lists `bindingGaps` checks. */
+const BINDING_KINDS = [
+    {
+        path: ["hyperdrive"],
+        binding: "binding",
+        resource: {
+            field: "id",
+            shape: "Hyperdrive id (32 hex digits)",
+            test: HEX32,
+            placeholder: true,
+            step: () => "Create the Hyperdrive config (wrangler hyperdrive create <name> --connection-string <postgres url>); set its id here.",
+        },
+    },
+    {
+        path: ["d1_databases"],
+        binding: "binding",
+        resource: {
+            field: "database_id",
+            shape: "D1 database id (a UUID)",
+            test: UUID,
+            placeholder: true,
+            step: (e) => `Create the database (wrangler d1 create ${named(e, "database_name", "<name>")}); set its database_id here.`,
+        },
+    },
+    {
+        path: ["kv_namespaces"],
+        binding: "binding",
+        resource: {
+            field: "id",
+            shape: "KV namespace id (32 hex digits)",
+            test: HEX32,
+            placeholder: true,
+            step: (e) => `Create the namespace (wrangler kv namespace create ${named(e, "binding", "<name>")}); set its id here.`,
+        },
+    },
+    {
+        path: ["ratelimits"],
+        binding: "name",
+        resource: {
+            field: "namespace_id",
+            shape: "rate-limit namespace id (a positive integer)",
+            test: /^[1-9][0-9]*$/,
+            placeholder: true,
+            step: () => "Pick a positive integer no other rate limiter of the account uses; set it here.",
+        },
+    },
+    {
+        path: ["r2_buckets"],
+        binding: "binding",
+        resource: {
+            field: "bucket_name",
+            shape: "R2 bucket name (3-63 lowercase letters, digits, hyphens)",
+            test: /^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/,
+            placeholder: false,
+            step: () => "Name the bucket here; create it with wrangler r2 bucket create <name>.",
+        },
+    },
+    {
+        path: ["queues", "producers"],
+        binding: "binding",
+        resource: QUEUE,
+    },
+    {
+        path: ["queues", "consumers"],
+        resource: QUEUE,
+    },
+    { path: ["durable_objects", "bindings"], binding: "name" },
+    { path: ["services"], binding: "binding" },
+];
+/** True for a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The entries of the list at `path` in `block`. */
+function entriesAt(block, path) {
+    const list = path.reduce((value, key) => (isRecord(value) ? value[key] : undefined), block);
+    return Array.isArray(list) ? list.filter(isRecord) : [];
+}
+/** Gaps of env block `block` (named `where`) in the bindings it declares:
+ *  a resource field malformed or left at `PLACEHOLDER`, and a binding of
+ *  config top level `top` it lacks. */
+export function bindingGaps(block, top, where) {
+    const gaps = [];
+    for (const { path, binding, resource } of BINDING_KINDS) {
+        const list = path.join(".");
+        const entries = entriesAt(block, path);
+        const nameOf = (entry) => binding ? named(entry, binding, "") : "";
+        const names = entries.map(nameOf);
+        if (resource)
+            for (const [i, entry] of entries.entries()) {
+                const value = entry[resource.field];
+                const label = nameOf(entry) && ` (${nameOf(entry)})`;
+                const field = `${where} ${list}[${i}].${resource.field}${label}`;
+                const gap = (problem) => gaps.push({
+                    area: "config",
+                    where: field,
+                    problem,
+                    step: resource.step(entry),
+                });
+                if (resource.placeholder &&
+                    typeof value === "string" &&
+                    PLACEHOLDER.test(value))
+                    gap(`is a placeholder (${value})`);
+                else if (typeof value !== "string" || !resource.test.test(value))
+                    gap(`${JSON.stringify(value)} is not a ${resource.shape}`);
+            }
+        if (binding)
+            for (const entry of entriesAt(top, path)) {
+                const name = nameOf(entry);
+                if (name && !names.includes(name))
+                    gaps.push({
+                        area: "config",
+                        where: `${where} ${list}`,
+                        problem: `lacks ${name}, bound at the top level`,
+                        step: "Redeclare it here: bindings do not inherit into env blocks.",
+                    });
+            }
+    }
+    return gaps;
+}
+/** Keys of dotenv `file` with their values. */
+const readDotenv = (file) => parseEnv(readFileSync(file, "utf8"));
+/** Gaps of secrets file `file`'s `.tmpl` in naming `keys`: a missing
+ *  template, a key it lacks. */
+export function templateGaps(file, keys) {
+    if (!keys.length)
+        return [];
+    const tmpl = `${file}.tmpl`;
+    if (!existsSync(tmpl))
+        return [
+            {
+                area: "template",
+                where: shown(tmpl),
+                problem: "is missing",
+                step: `Write it naming each secret with ${SECRET_PLACEHOLDER} values: ${keys.join(", ")}.`,
+            },
+        ];
+    const template = readDotenv(tmpl);
+    const lacking = keys.filter((key) => !(key in template));
+    if (!lacking.length)
+        return [];
+    return [
+        {
+            area: "template",
+            where: shown(tmpl),
+            problem: `lacks ${lacking.join(", ")}`,
+            step: `Add ${lacking.map((key) => `${key}=${SECRET_PLACEHOLDER}`).join(", ")}.`,
+        },
+    ];
+}
+/** Gaps of secrets file `file` in holding `keys`: a missing file, a key
+ *  unset, empty or at `SECRET_PLACEHOLDER`. */
+export function secretsGaps(file, keys) {
+    if (!keys.length)
+        return [];
+    const tmpl = `${file}.tmpl`;
+    const listed = keys.join(", ");
+    if (!existsSync(file))
+        return [
+            {
+                area: "secrets",
+                where: shown(file),
+                problem: "is missing",
+                step: existsSync(tmpl)
+                    ? `Copy ${shown(tmpl)} to it; fill ${listed}.`
+                    : `Write it with values for ${listed}.`,
+            },
+        ];
+    const values = readDotenv(file);
+    const unset = keys.filter((key) => !values[key] || values[key] === SECRET_PLACEHOLDER);
+    if (!unset.length)
+        return [];
+    return [
+        {
+            area: "secrets",
+            where: shown(file),
+            problem: `lacks values for ${unset.join(", ")}`,
+            step: `Fill them in; empty and ${SECRET_PLACEHOLDER} count as unset.`,
+        },
+    ];
+}
+/** The gap of `env`'s database URL variable `variable`, unset. */
+export const databaseGap = (env, variable) => ({
+    area: "database",
+    where: `$${variable}`,
+    problem: "is unset",
+    step: `Export ${env}'s database URL as ${variable}.`,
+});
+/** The refusal of a command on `env` while `gaps` hold it up, pointing at
+ *  `check` under `invocation`. */
+export function unprovisioned(invocation, env, gaps) {
+    return new ExpectedError([
+        `${env} is unprovisioned:`,
+        ...gaps.map((g) => `  ${g.where} ${g.problem}`),
+        `${invocation} check --env ${env} lists each next step.`,
+    ].join("\n"));
+}

package/dist/src/schema.d.ts

@@ -0,0 +1,2 @@
+/** The `deploy` schema: deploy state and the lease; `reset.sql` refuses while a deploy command holds the lease. */
+export declare const deploySchema: import("@astralarium/repo-postgres/schema").SchemaModule;

package/dist/src/schema.js

@@ -0,0 +1,12 @@
+/** Deploy state as a schema module: `deploy.state` and the lease. */
+import { resolve } from "node:path";
+import { packageRoot } from "@astralarium/repo-package-files";
+import { defineSchemaModule } from "@astralarium/repo-postgres/schema";
+/** The `deploy` schema: deploy state and the lease; `reset.sql` refuses while a deploy command holds the lease. */
+export const deploySchema = defineSchemaModule({
+    name: "deploy",
+    root: resolve(packageRoot(import.meta.filename), "sql"),
+    files: ["schema.sql"],
+    beforeReset: "before-reset.sql",
+    scrub: "scrub.sql",
+});

package/dist/src/session.d.ts

@@ -0,0 +1,81 @@
+import type { DeployInfo } from "@astralarium/repo-deploy-info";
+import { type Sql } from "postgres";
+import { type ReleaseApp } from "./app.ts";
+import { type Needs } from "./check.ts";
+import { Cloudflare } from "./cloudflare.ts";
+import { type DeployOperation, Lease } from "./lease.ts";
+import { type RunOptions } from "./process.ts";
+import { type InPlaceTarget, type SlotTarget, type Target } from "./target.ts";
+/** Flags every session command takes. */
+export interface EnvFlags {
+    readonly env: string;
+}
+/** A command function running `fn` in a session against `--env`'s
+ *  target, held up by its gaps in `needs` (`provisionedTarget`); `fn`
+ *  resolves to the exit status, void is 0. Failures log as
+ *  `deploy_release.failed`. */
+export declare function inSession<F extends EnvFlags>(app: ReleaseApp, invocation: string, needs: Needs, fn: (flags: F, s: Session) => Promise<number | void>): (flags: F) => Promise<void>;
+/** `inSession` for a blue/green command: an in-place env refuses. */
+export declare function inSlots<F extends EnvFlags>(app: ReleaseApp, invocation: string, needs: Needs, fn: (flags: F, s: SlotSession) => Promise<number | void>): (flags: F) => Promise<void>;
+/** `s` against its blue/green target; throws for an in-place env,
+ *  naming its commands. */
+export declare function slotSession(s: Session): SlotSession;
+/** A session against a blue/green target. */
+export type SlotSession = Session<SlotTarget>;
+/** A session against an in-place target. */
+export type InPlaceSession = Session<InPlaceTarget>;
+/** Disposal drops the lease, closes the database and removes the scratch
+ *  dir. */
+export declare class Session<T extends Target = Target> implements AsyncDisposable {
+    #private;
+    readonly app: ReleaseApp;
+    /** Starts each printed command line: the program and its `--app`. */
+    readonly invocation: string;
+    readonly target: T;
+    readonly cf: Cloudflare;
+    /** The deployer is up with this session's code (`deployDeployer`). */
+    deployerDeployed: boolean;
+    constructor(app: ReleaseApp, invocation: string, target: T);
+    /** Aborts on Ctrl-C or a lost lease: children die, waits end. */
+    get signal(): AbortSignal;
+    /** Aborts with `reason`. */
+    abort(reason: unknown): void;
+    /** `command` as a runnable line for this target. */
+    cli(command: string): string;
+    /** Runs `cmd` with `args` until it exits, aborting with the session;
+     *  resolves to its stdout when captured. */
+    run(cmd: string, args: readonly string[], options?: RunOptions): Promise<string>;
+    /** `fetch` aborting with the session. */
+    fetch(input: URL | string, init?: RequestInit): Promise<Response>;
+    /** Pauses `ms`, aborting with the session. */
+    sleep(ms: number): Promise<void>;
+    /** Reads a hidden line from the operator after `question`. */
+    secret(question: string): Promise<string>;
+    /** True when the operator answers yes to `question`. */
+    confirm(question: string): Promise<boolean>;
+    /** Throws while the app checkout holds uncommitted or untracked
+     *  changes (the deployer bundles it). */
+    requireClean(): void;
+    /** Readies the checkouts for a build: throws while any holds
+     *  uncommitted or untracked changes (builds bundle them), then
+     *  fast-forwards the `pull` siblings. */
+    ready(): void;
+    /** Fresh deploy info for the target: a build id and each checkout's
+     *  commit; throws on a dirty checkout. */
+    mint(): DeployInfo;
+    /** Variable holding the target's database URL; throws for a target
+     *  without a database. */
+    get dbUrlVar(): string;
+    /** True while the target has a database and its URL is set. */
+    get hasDb(): boolean;
+    /** The target's database; throws while its URL is unset. */
+    get sql(): Sql;
+    /** Takes the deploy lease for `operation`; a held lease keeps its
+     *  operation. Throws while another command holds it. */
+    takeLease(operation: DeployOperation): Promise<Lease>;
+    /** The held lease. */
+    get lease(): Lease;
+    /** A scratch dir, removed at disposal. */
+    tmpDir(): Promise<string>;
+    [Symbol.asyncDispose](): Promise<void>;
+}