rampway 0.3.0 → 0.4.0

package/build/src/velocious/controller.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Validates and canonicalizes the backend-owned worker bootstrap module.
+ *
+ * @param {unknown} value - Candidate module path.
+ * @returns {string} Immutable absolute module path.
+ */
+export function validateWorkerBootstrapPath(value: unknown): string;
+/**
+ * Creates a scheduler that launches Rampway's package-owned detached worker.
+ *
+ * @param {object} args - Scheduler dependencies.
+ * @param {any} args.configuration - Velocious configuration.
+ * @param {string} args.mountIdentifier - Stable mount identifier.
+ * @param {(payload: {context: string, error: unknown}) => void} [args.emitFrameworkError] - Failure reporter.
+ * @param {(file: string, args: string[], options: object) => import("node:child_process").ChildProcess} [args.spawnImpl] - Test seam.
+ * @param {string} args.workerBootstrapPath - Canonical backend bootstrap path.
+ * @param {string} [args.workerPath] - Canonical package worker entry path.
+ * @returns {(args: {onFailure?: (error: unknown) => Promise<void>, runId: string}) => Promise<void>} Detached scheduler.
+ */
+export function createDetachedExecution({ configuration, emitFrameworkError, mountIdentifier, spawnImpl, workerBootstrapPath, workerPath }: {
+    configuration: any;
+    mountIdentifier: string;
+    emitFrameworkError?: ((payload: {
+        context: string;
+        error: unknown;
+    }) => void) | undefined;
+    spawnImpl?: ((file: string, args: string[], options: object) => import("node:child_process").ChildProcess) | undefined;
+    workerBootstrapPath: string;
+    workerPath?: string | undefined;
+}): (args: {
+    onFailure?: (error: unknown) => Promise<void>;
+    runId: string;
+}) => Promise<void>;
+/** Immutable package worker entry path. */
+export const packageWorkerPath: string;
+/** Velocious HTTP adapter for Rampway's deployment control plane. */
+export default class RampwayDeploymentApiController extends Controller {
+    /** @returns {Record<string, any>} Mount options. */
+    _mountOptions(): Record<string, any>;
+    /** @returns {DeploymentRunStore} Store. */
+    _store(): DeploymentRunStore;
+    deploymentRunStore: DeploymentRunStore | undefined;
+    /** @returns {DeploymentControlPlane<DeploymentRunStore>} Control plane. */
+    _controlPlane(): DeploymentControlPlane<DeploymentRunStore>;
+    /** @param {{context: string, error: unknown}} args - Failure. @returns {void} */
+    _emitFrameworkError({ context, error }: {
+        context: string;
+        error: unknown;
+    }): void;
+    /** @returns {Promise<void>} */
+    create(): Promise<void>;
+    /** @returns {Promise<void>} */
+    show(): Promise<void>;
+}
+import Controller from "velocious/build/src/controller.js";
+import DeploymentRunStore from "./run-store.js";
+import { DeploymentControlPlane } from "./control-plane.js";
+//# sourceMappingURL=controller.d.ts.map

package/build/src/velocious/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/velocious/controller.js"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,mDAHW,OAAO,GACL,MAAM,CAYlB;AAED;;;;;;;;;;;GAWG;AACH,4IARG;IAAkB,aAAa,EAAvB,GAAG;IACU,eAAe,EAA5B,MAAM;IACsD,kBAAkB,cAApE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI;IACgD,SAAS,WAAtG,MAAM,QAAQ,MAAM,EAAE,WAAW,MAAM,KAAK,OAAO,oBAAoB,EAAE,YAAY;IAC/E,mBAAmB,EAAhC,MAAM;IACQ,UAAU;CAChC,GAAU,CAAC,IAAI,EAAE;IAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAkCnG;AAjED,2CAA2C;AAC3C,uCAAwG;AAkExG,qEAAqE;AACrE;IACE,oDAAoD;IACpD,iBADc,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAMhC;IAED,2CAA2C;IAC3C,UADc,kBAAkB,CAY/B;IARG,mDAKE;IAKN,2EAA2E;IAC3E,iBADc,sBAAsB,CAAC,kBAAkB,CAAC,CAYvD;IAED,iFAAiF;IACjF,wCADY;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAC,GAA4B,IAAI,CAQ5E;IAED,+BAA+B;IAC/B,UADc,OAAO,CAAC,IAAI,CAAC,CAO1B;IAED,+BAA+B;IAC/B,QADc,OAAO,CAAC,IAAI,CAAC,CAO1B;CACF;uBA1IsB,mCAAmC;+BAG3B,gBAAgB;uCADV,oBAAoB"}

package/build/src/velocious/controller.js

@@ -0,0 +1,143 @@
+// @ts-check
+import { fileURLToPath, URL } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn as nodeSpawn } from "node:child_process";
+import Controller from "velocious/build/src/controller.js";
+import { DeploymentControlPlane } from "./control-plane.js";
+import DeploymentRunStore from "./run-store.js";
+import { getDeploymentMount } from "./registry.js";
+/** Immutable package worker entry path. */
+export const packageWorkerPath = fs.realpathSync(fileURLToPath(new URL("./worker.js", import.meta.url)));
+/**
+ * Validates and canonicalizes the backend-owned worker bootstrap module.
+ *
+ * @param {unknown} value - Candidate module path.
+ * @returns {string} Immutable absolute module path.
+ */
+export function validateWorkerBootstrapPath(value) {
+    if (typeof value !== "string" || !path.isAbsolute(value))
+        throw new Error("Rampway worker bootstrap path must be absolute");
+    let resolved;
+    try {
+        resolved = fs.realpathSync(value);
+    }
+    catch (error) {
+        throw new Error(`Rampway worker bootstrap module is unavailable: ${value}`, { cause: error });
+    }
+    if (!fs.statSync(resolved).isFile())
+        throw new Error(`Rampway worker bootstrap path is not a file: ${value}`);
+    return resolved;
+}
+/**
+ * Creates a scheduler that launches Rampway's package-owned detached worker.
+ *
+ * @param {object} args - Scheduler dependencies.
+ * @param {any} args.configuration - Velocious configuration.
+ * @param {string} args.mountIdentifier - Stable mount identifier.
+ * @param {(payload: {context: string, error: unknown}) => void} [args.emitFrameworkError] - Failure reporter.
+ * @param {(file: string, args: string[], options: object) => import("node:child_process").ChildProcess} [args.spawnImpl] - Test seam.
+ * @param {string} args.workerBootstrapPath - Canonical backend bootstrap path.
+ * @param {string} [args.workerPath] - Canonical package worker entry path.
+ * @returns {(args: {onFailure?: (error: unknown) => Promise<void>, runId: string}) => Promise<void>} Detached scheduler.
+ */
+export function createDetachedExecution({ configuration, emitFrameworkError = () => { }, mountIdentifier, spawnImpl = nodeSpawn, workerBootstrapPath, workerPath = packageWorkerPath }) {
+    return async ({ onFailure, runId }) => {
+        if (typeof runId !== "string" || runId.length === 0 || runId.length > 128)
+            throw new Error("Invalid detached deployment run identifier");
+        if (typeof mountIdentifier !== "string" || mountIdentifier.length !== 64)
+            throw new Error("Invalid detached deployment mount identifier");
+        const child = spawnImpl(process.execPath, [workerPath, workerBootstrapPath, mountIdentifier, runId], {
+            cwd: configuration.getDirectory(),
+            detached: true,
+            stdio: ["ignore", "ignore", "ignore"]
+        });
+        child.once("exit", (code, signal) => {
+            if (code !== 0) {
+                const failure = new Error(`Rampway deployment worker exited before completion (${signal ?? `code ${code}`})`);
+                if (onFailure)
+                    onFailure(failure).catch((/** @type {unknown} */ error) => emitFrameworkError({ context: "rampway-deployment-api-worker-failure", error }));
+            }
+        });
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const fail = (/** @type {unknown} */ error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error);
+            };
+            child.once("error", fail);
+            child.once("spawn", () => {
+                if (settled)
+                    return;
+                settled = true;
+                child.unref();
+                resolve(undefined);
+            });
+        });
+    };
+}
+/** Velocious HTTP adapter for Rampway's deployment control plane. */
+export default class RampwayDeploymentApiController extends Controller {
+    /** @returns {Record<string, any>} Mount options. */
+    _mountOptions() {
+        const at = /** @type {string} */ (this.params().rampwayDeploymentMountAt);
+        const options = getDeploymentMount(this.getConfiguration(), at);
+        if (!options)
+            throw new Error(`No Rampway deployment API mount registered at ${at}`);
+        return options;
+    }
+    /** @returns {DeploymentRunStore} Store. */
+    _store() {
+        if (!this.deploymentRunStore) {
+            const options = this._mountOptions();
+            this.deploymentRunStore = new DeploymentRunStore({
+                configuration: this.getConfiguration(),
+                databaseIdentifier: options.databaseIdentifier,
+                mountIdentifier: options.mountIdentifier,
+                staleRunTimeoutMs: options.staleRunTimeoutMs
+            });
+        }
+        return this.deploymentRunStore;
+    }
+    /** @returns {DeploymentControlPlane<DeploymentRunStore>} Control plane. */
+    _controlPlane() {
+        const options = /** @type {import('./control-plane.js').DeploymentMountOptions & {databaseIdentifier: string, executor: import('./executor.js').RampwayDeploymentExecutor}} */ (this._mountOptions());
+        const configuration = this.getConfiguration();
+        const emitFrameworkError = (/** @type {{context: string, error: unknown}} */ { context, error }) => this._emitFrameworkError({ context, error });
+        return new DeploymentControlPlane({
+            detachedExecution: createDetachedExecution({ configuration, mountIdentifier: options.mountIdentifier, workerBootstrapPath: options.workerBootstrapPath, workerPath: options.workerPath }),
+            emitFrameworkError,
+            executor: options.executor,
+            options,
+            store: this._store()
+        });
+    }
+    /** @param {{context: string, error: unknown}} args - Failure. @returns {void} */
+    _emitFrameworkError({ context, error }) {
+        const events = this.getConfiguration().getErrorEvents();
+        // Never attach the request: it retains the bearer header and would make
+        // unsafe framework reporters capable of serializing the credential.
+        const payload = { context, error };
+        events.emit("framework-error", payload);
+        events.emit("all-error", { ...payload, errorType: "framework-error" });
+    }
+    /** @returns {Promise<void>} */
+    async create() {
+        const response = await this._controlPlane().create({
+            authorization: this.request().header("authorization"),
+            input: this.params()
+        });
+        await this.render({ json: response.body, status: response.status });
+    }
+    /** @returns {Promise<void>} */
+    async show() {
+        const response = await this._controlPlane().show({
+            authorization: this.request().header("authorization"),
+            id: /** @type {string} */ (this.params().id)
+        });
+        await this.render({ json: response.body, status: response.status });
+    }
+}
+//# sourceMappingURL=controller.js.map

package/build/src/velocious/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../../src/velocious/controller.js"],"names":[],"mappings":"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"}

package/build/src/velocious/executor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Reads bounded live state using Rampway's existing release layout.
+ *
+ * @param {{stage: import('#types').StageConfig, transport: import('#types').Transport}} args - Context.
+ * @returns {Promise<Record<string, any>>} Live state.
+ */
+export function readDeploymentStatus({ stage, transport }: {
+    stage: import("#types").StageConfig;
+    transport: import("#types").Transport;
+}): Promise<Record<string, any>>;
+/**
+ * Creates the executor that translates a bounded target into Rampway's normal
+ * deploy, rollback, and status functions. Dependency overrides are test-only.
+ *
+ * @param {object} [deps] - Overrides.
+ * @param {typeof defaultCommandContext} [deps.commandContext] - Context loader.
+ * @param {typeof runDeploy} [deps.deploy] - Deploy lifecycle.
+ * @param {typeof readDeploymentStatus} [deps.readDeploymentStatus] - Status reader.
+ * @param {typeof runRollback} [deps.rollback] - Rollback lifecycle.
+ * @returns {RampwayDeploymentExecutor} Executor.
+ */
+export function createRampwayDeploymentExecutor({ commandContext, deploy, readDeploymentStatus: statusReader, rollback }?: {
+    commandContext?: typeof defaultCommandContext | undefined;
+    deploy?: typeof runDeploy | undefined;
+    readDeploymentStatus?: typeof readDeploymentStatus | undefined;
+    rollback?: typeof runRollback | undefined;
+}): RampwayDeploymentExecutor;
+export type RampwayDeploymentTarget = {
+    configPath: string;
+    releaseBranch: string;
+};
+export type RampwayDeploymentExecutor = {
+    validateRevision: (args: {
+        project: string;
+        revision: string;
+        stage: string;
+        target: RampwayDeploymentTarget;
+    }) => Promise<boolean>;
+    deploy: (args: {
+        project: string;
+        revision: string;
+        runId: string;
+        stage: string;
+        target: RampwayDeploymentTarget;
+    }) => Promise<Record<string, any>>;
+    readStatus: (args: {
+        project: string;
+        stage: string;
+        target: RampwayDeploymentTarget;
+    }) => Promise<Record<string, any>>;
+};
+import { commandContext as defaultCommandContext } from "../commands/context.js";
+import { deploy as runDeploy } from "../core/deploy-runner.js";
+import { rollback as runRollback } from "../core/deploy-runner.js";
+//# sourceMappingURL=executor.d.ts.map

package/build/src/velocious/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/velocious/executor.js"],"names":[],"mappings":"AAuBA;;;;;GAKG;AACH,2DAHW;IAAC,KAAK,EAAE,OAAO,QAAQ,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,OAAO,QAAQ,EAAE,SAAS,CAAA;CAAC,GAC1E,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAaxC;AAED;;;;;;;;;;GAUG;AACH,2HANG;IAA4C,cAAc;IAC1B,MAAM;IACK,oBAAoB;IAC7B,QAAQ;CAC1C,GAAU,yBAAyB,CAiGrC;sCAtIY;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC;;sBAE1C,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAC,KAAK,OAAO,CAAC,OAAO,CAAC;YAC/G,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAC1I,CAAC,IAAI,EAAE;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;;wDAbjE,wBAAwB;oCACnB,0BAA0B;wCAA1B,0BAA0B"}

package/build/src/velocious/executor.js

@@ -0,0 +1,142 @@
+// @ts-check
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { commandContext as defaultCommandContext } from "../commands/context.js";
+import { deploy as runDeploy, rollback as runRollback } from "../core/deploy-runner.js";
+import { deployPaths } from "../core/paths.js";
+import { currentReleaseId, previousRelease } from "../core/release-manager.js";
+import { remoteGitRepoLabel } from "../core/git-source.js";
+import { Reporter } from "../core/reporter.js";
+import { shellQuote } from "../transports/ssh-transport.js";
+/**
+ * @typedef {{configPath: string, releaseBranch: string}} RampwayDeploymentTarget
+ * @typedef {object} RampwayDeploymentExecutor
+ * @property {(args: {project: string, revision: string, stage: string, target: RampwayDeploymentTarget}) => Promise<boolean>} validateRevision
+ * @property {(args: {project: string, revision: string, runId: string, stage: string, target: RampwayDeploymentTarget}) => Promise<Record<string, any>>} deploy
+ * @property {(args: {project: string, stage: string, target: RampwayDeploymentTarget}) => Promise<Record<string, any>>} readStatus
+ */
+const quietReporter = () => new Reporter({ lifecycle: false, streamCommands: false });
+/**
+ * Reads bounded live state using Rampway's existing release layout.
+ *
+ * @param {{stage: import('#types').StageConfig, transport: import('#types').Transport}} args - Context.
+ * @returns {Promise<Record<string, any>>} Live state.
+ */
+export async function readDeploymentStatus({ stage, transport }) {
+    const currentRelease = await currentReleaseId(transport, stage);
+    const previous = await previousRelease(transport, stage, currentRelease);
+    let activeRevision = null;
+    if (currentRelease) {
+        const revisionPath = path.join(deployPaths(stage).releasesPath, currentRelease, "REVISION");
+        if (await transport.exists(revisionPath))
+            activeRevision = (await transport.readFile(revisionPath)).trim();
+    }
+    return { activeRevision, currentRelease, previousRelease: previous ?? null };
+}
+/**
+ * Creates the executor that translates a bounded target into Rampway's normal
+ * deploy, rollback, and status functions. Dependency overrides are test-only.
+ *
+ * @param {object} [deps] - Overrides.
+ * @param {typeof defaultCommandContext} [deps.commandContext] - Context loader.
+ * @param {typeof runDeploy} [deps.deploy] - Deploy lifecycle.
+ * @param {typeof readDeploymentStatus} [deps.readDeploymentStatus] - Status reader.
+ * @param {typeof runRollback} [deps.rollback] - Rollback lifecycle.
+ * @returns {RampwayDeploymentExecutor} Executor.
+ */
+export function createRampwayDeploymentExecutor({ commandContext = defaultCommandContext, deploy = runDeploy, readDeploymentStatus: statusReader = readDeploymentStatus, rollback = runRollback } = {}) {
+    /**
+     * @param {RampwayDeploymentTarget} target - Allowlisted target.
+     * @param {string} stageName - Allowlisted stage.
+     * @returns {Promise<{stage: import('#types').StageConfig, transport: import('#types').Transport}>} Rampway context.
+     */
+    async function contextFor(target, stageName) {
+        const context = await commandContext({ config: target.configPath }, stageName, { reporter: quietReporter() });
+        if (context.stage.strategy !== "remote-git") {
+            throw new Error(`Callable deployment target ${context.stage.application}/${stageName} must use the remote-git strategy`);
+        }
+        if (!context.stage.repo)
+            throw new Error(`Callable deployment target ${context.stage.application}/${stageName} requires a repository`);
+        return context;
+    }
+    return {
+        async validateRevision({ revision, stage, target }) {
+            const { stage: rampwayStage, transport } = await contextFor(target, stage);
+            const checkPath = path.join(rampwayStage.deployTo, `.rampway-revision-check-${randomUUID()}`);
+            const repository = /** @type {string} */ (rampwayStage.repo);
+            await transport.mkdirp(rampwayStage.deployTo);
+            try {
+                try {
+                    await transport.run(`git init ${shellQuote(checkPath)}`);
+                    await transport.run(`git -C ${shellQuote(checkPath)} remote add origin ${shellQuote(repository)}`);
+                    await transport.run(`git -C ${shellQuote(checkPath)} fetch --no-tags origin ${shellQuote(`refs/heads/${target.releaseBranch}`)}`);
+                }
+                catch {
+                    throw new Error(`Could not fetch approved branch ${target.releaseBranch} from ${remoteGitRepoLabel(repository)} for revision validation`);
+                }
+                try {
+                    await transport.run(`git -C ${shellQuote(checkPath)} merge-base --is-ancestor ${shellQuote(revision)} FETCH_HEAD`);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            finally {
+                await transport.rm(checkPath);
+            }
+        },
+        async deploy({ revision, stage, target }) {
+            const { stage: rampwayStage, transport } = await contextFor(target, stage);
+            const before = await statusReader({ stage: rampwayStage, transport });
+            try {
+                return /** @type {Record<string, any>} */ (await deploy({
+                    branch: target.releaseBranch,
+                    force: false,
+                    reporter: quietReporter(),
+                    revision,
+                    stage: rampwayStage,
+                    transport
+                }));
+            }
+            catch (error) {
+                const failure = error instanceof Error ? error : new Error(String(error));
+                /** @type {Record<string, any>} */
+                let recovery;
+                try {
+                    const after = await statusReader({ stage: rampwayStage, transport });
+                    const changed = after.currentRelease !== before.currentRelease;
+                    if (changed && after.activeRevision === revision && before.currentRelease) {
+                        const rollbackReport = await rollback({ stage: rampwayStage, to: before.currentRelease, transport });
+                        recovery = {
+                            activeRevision: before.activeRevision ?? null,
+                            currentRelease: before.currentRelease ?? null,
+                            restored: true,
+                            rollback: rollbackReport
+                        };
+                    }
+                    else {
+                        recovery = {
+                            activeRevision: after.activeRevision ?? null,
+                            currentRelease: after.currentRelease ?? null,
+                            restored: !changed
+                        };
+                    }
+                }
+                catch (recoveryError) {
+                    recovery = {
+                        message: recoveryError instanceof Error ? recoveryError.message : String(recoveryError),
+                        restored: false
+                    };
+                }
+                /** @type {Error & {recovery?: Record<string, any>}} */ (failure).recovery = recovery;
+                throw failure;
+            }
+        },
+        async readStatus({ stage, target }) {
+            const context = await contextFor(target, stage);
+            return await statusReader(context);
+        }
+    };
+}
+//# sourceMappingURL=executor.js.map

package/build/src/velocious/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/velocious/executor.js"],"names":[],"mappings":"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"}

package/build/src/velocious/index.d.ts

@@ -0,0 +1,31 @@
+/** Mountable Rampway-owned deployment control plane for Velocious routes. */
+export default class RampwayVelociousDeploymentApi {
+    /**
+     * @param {object} args - Mount options.
+     * @param {unknown} args.accessTokens - Backend-held bearer tokens.
+     * @param {string} args.at - Route prefix.
+     * @param {any} args.configuration - Velocious configuration.
+     * @param {string} [args.databaseIdentifier] - Persistence database.
+     * @param {unknown} args.projects - Project/stage/config/branch allowlist.
+     * @param {number} [args.staleRunTimeoutMs] - Ownership lease.
+     * @param {string} args.workerBootstrapPath - Absolute backend module that reconstructs Velocious in a worker.
+     * @returns {void}
+     */
+    static mountInto({ accessTokens, at, configuration, databaseIdentifier, projects, staleRunTimeoutMs, workerBootstrapPath }: {
+        accessTokens: unknown;
+        at: string;
+        configuration: any;
+        databaseIdentifier?: string | undefined;
+        projects: unknown;
+        staleRunTimeoutMs?: number | undefined;
+        workerBootstrapPath: string;
+    }): void;
+}
+import { constantTimeEqual } from "./auth.js";
+import { DeploymentControlPlane } from "./control-plane.js";
+import { matchDeploymentApiPath } from "./path-matcher.js";
+import { sanitizeAdapterValue } from "./sanitize.js";
+import { sanitizeErrorPayload } from "./sanitize.js";
+import { validateWorkerBootstrapPath } from "./controller.js";
+export { constantTimeEqual, DeploymentControlPlane, matchDeploymentApiPath, sanitizeAdapterValue, sanitizeErrorPayload, validateWorkerBootstrapPath };
+//# sourceMappingURL=index.d.ts.map

package/build/src/velocious/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/velocious/index.js"],"names":[],"mappings":"AA2GA,6EAA6E;AAC7E;IACE;;;;;;;;;;OAUG;IACH,4HATG;QAAsB,YAAY,EAA1B,OAAO;QACM,EAAE,EAAf,MAAM;QACI,aAAa,EAAvB,GAAG;QACW,kBAAkB;QAClB,QAAQ,EAAtB,OAAO;QACO,iBAAiB;QAClB,mBAAmB,EAAhC,MAAM;KACd,GAAU,IAAI,CA6BhB;CACF;kCAhJ+B,WAAW;uCACN,oBAAoB;uCAGE,mBAAmB;qCAErB,eAAe;qCAAf,eAAe;4CAJqB,iBAAiB"}

package/build/src/velocious/index.js

@@ -0,0 +1,144 @@
+// @ts-check
+import path from "node:path";
+import { constantTimeEqual } from "./auth.js";
+import { DeploymentControlPlane } from "./control-plane.js";
+import RampwayDeploymentApiController, { packageWorkerPath, validateWorkerBootstrapPath } from "./controller.js";
+import { createRampwayDeploymentExecutor } from "./executor.js";
+import { matchDeploymentApiPath, normalizeMountPrefix } from "./path-matcher.js";
+import { deploymentMountIdentifier, registerDeploymentMount } from "./registry.js";
+import { sanitizeAdapterValue, sanitizeErrorPayload } from "./sanitize.js";
+const IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+const BRANCH_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*(\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/;
+const MAX_IDENTIFIER_LENGTH = 64;
+const DEFAULT_STALE_RUN_TIMEOUT_MS = 60000;
+/**
+ * Applies Git's branch-ref safety rules without deferring failure to deploy.
+ *
+ * @param {unknown} value - Configured release branch.
+ * @returns {value is string} Whether the branch is a valid heads ref.
+ */
+function isValidReleaseBranch(value) {
+    if (typeof value !== "string" || !BRANCH_PATTERN.test(value))
+        return false;
+    const ref = `refs/heads/${value}`;
+    return !ref.includes("..")
+        && !ref.includes("@{")
+        && !ref.endsWith(".")
+        && !ref.split("/").some(component => component.endsWith(".lock"))
+        && !/[\u0000-\u0020\u007f~^:?*\\]/u.test(ref)
+        && !ref.includes("[");
+}
+/**
+ * @param {unknown} value - Value.
+ * @param {string} name - Label.
+ * @returns {string} Identifier.
+ */
+function validateIdentifier(value, name) {
+    if (typeof value !== "string" || value.length > MAX_IDENTIFIER_LENGTH || !IDENTIFIER_PATTERN.test(value)) {
+        throw new Error(`Invalid ${name} identifier: ${String(value)}`);
+    }
+    return value;
+}
+/**
+ * @param {unknown} tokens - Tokens.
+ * @returns {string[]} Validated copy.
+ */
+function validateAccessTokens(tokens) {
+    if (!Array.isArray(tokens) || tokens.length === 0 || tokens.some(token => typeof token !== "string" || token.length === 0)) {
+        throw new Error("Rampway deployment API requires at least one non-empty access token");
+    }
+    return [...tokens];
+}
+/**
+ * @param {unknown} rawProjects - Allowlist.
+ * @returns {Record<string, any>} Normalized allowlist.
+ */
+function validateProjects(rawProjects) {
+    if (!rawProjects || typeof rawProjects !== "object" || Array.isArray(rawProjects)) {
+        throw new Error("Rampway deployment API requires a projects allowlist");
+    }
+    /** @type {Record<string, any>} */
+    const projects = Object.create(null);
+    for (const [project, rawProject] of Object.entries(rawProjects)) {
+        validateIdentifier(project, "project");
+        const stagesValue = rawProject && typeof rawProject === "object" ? /** @type {Record<string, any>} */ (rawProject).stages : null;
+        if (!stagesValue || typeof stagesValue !== "object" || Array.isArray(stagesValue) || Object.keys(stagesValue).length === 0) {
+            throw new Error(`Project ${project} must allowlist at least one stage`);
+        }
+        /** @type {Record<string, any>} */
+        const stages = Object.create(null);
+        for (const [stage, rawTarget] of Object.entries(stagesValue)) {
+            validateIdentifier(stage, "stage");
+            const target = rawTarget && typeof rawTarget === "object" ? /** @type {Record<string, unknown>} */ (rawTarget) : {};
+            if (typeof target.configPath !== "string" || !path.isAbsolute(target.configPath)) {
+                throw new Error(`Rampway config path for ${project}/${stage} must be absolute`);
+            }
+            if (!isValidReleaseBranch(target.releaseBranch)) {
+                throw new Error(`Invalid release branch for ${project}/${stage}: ${String(target.releaseBranch)}`);
+            }
+            stages[stage] = { configPath: target.configPath, releaseBranch: target.releaseBranch };
+        }
+        projects[project] = { stages };
+    }
+    if (Object.keys(projects).length === 0)
+        throw new Error("Rampway deployment API requires at least one allowlisted project");
+    return projects;
+}
+/**
+ * @param {unknown} value - Timeout.
+ * @returns {number} Timeout.
+ */
+function validateStaleRunTimeout(value) {
+    if (value === undefined)
+        return DEFAULT_STALE_RUN_TIMEOUT_MS;
+    if (!Number.isSafeInteger(value) || /** @type {number} */ (value) < 4) {
+        throw new Error("Rampway deployment API staleRunTimeoutMs must be an integer of at least 4");
+    }
+    return /** @type {number} */ (value);
+}
+/** Mountable Rampway-owned deployment control plane for Velocious routes. */
+export default class RampwayVelociousDeploymentApi {
+    /**
+     * @param {object} args - Mount options.
+     * @param {unknown} args.accessTokens - Backend-held bearer tokens.
+     * @param {string} args.at - Route prefix.
+     * @param {any} args.configuration - Velocious configuration.
+     * @param {string} [args.databaseIdentifier] - Persistence database.
+     * @param {unknown} args.projects - Project/stage/config/branch allowlist.
+     * @param {number} [args.staleRunTimeoutMs] - Ownership lease.
+     * @param {string} args.workerBootstrapPath - Absolute backend module that reconstructs Velocious in a worker.
+     * @returns {void}
+     */
+    static mountInto({ accessTokens, at, configuration, databaseIdentifier = "default", projects, staleRunTimeoutMs, workerBootstrapPath }) {
+        if (!configuration || typeof configuration.addRouteResolverHook !== "function")
+            throw new Error("No Velocious configuration given");
+        if (typeof databaseIdentifier !== "string" || databaseIdentifier.length === 0) {
+            throw new Error("Rampway deployment API databaseIdentifier must be a non-empty string");
+        }
+        const prefix = normalizeMountPrefix(at);
+        const options = {
+            accessTokens: validateAccessTokens(accessTokens),
+            databaseIdentifier,
+            executor: createRampwayDeploymentExecutor(),
+            mountIdentifier: deploymentMountIdentifier(prefix),
+            projects: validateProjects(projects),
+            staleRunTimeoutMs: validateStaleRunTimeout(staleRunTimeoutMs),
+            workerBootstrapPath: validateWorkerBootstrapPath(workerBootstrapPath),
+            workerPath: packageWorkerPath
+        };
+        registerDeploymentMount(configuration, prefix, options);
+        configuration.addRouteResolverHook((/** @type {{currentPath: string, request: {httpMethod: () => string}}} */ { currentPath, request }) => {
+            const match = matchDeploymentApiPath({ method: request.httpMethod(), path: currentPath, prefix });
+            if (!match)
+                return null;
+            return {
+                action: match.action,
+                controller: "rampwayDeploymentApi",
+                controllerClass: RampwayDeploymentApiController,
+                params: { ...match.params, rampwayDeploymentMountAt: prefix }
+            };
+        });
+    }
+}
+export { constantTimeEqual, DeploymentControlPlane, matchDeploymentApiPath, sanitizeAdapterValue, sanitizeErrorPayload, validateWorkerBootstrapPath };
+//# sourceMappingURL=index.js.map

package/build/src/velocious/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/velocious/index.js"],"names":[],"mappings":"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"}

package/build/src/velocious/path-matcher.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @param {string} at - Mount path.
+ * @returns {string} Normalized path.
+ */
+export function normalizeMountPrefix(at: string): string;
+/**
+ * @param {{prefix: string, path: string, method: string}} args - Request data.
+ * @returns {{action: string, params: Record<string, string>}|null} Match.
+ */
+export function matchDeploymentApiPath({ prefix, path, method }: {
+    prefix: string;
+    path: string;
+    method: string;
+}): {
+    action: string;
+    params: Record<string, string>;
+} | null;
+//# sourceMappingURL=path-matcher.d.ts.map

package/build/src/velocious/path-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-matcher.d.ts","sourceRoot":"","sources":["../../../src/velocious/path-matcher.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,yCAHW,MAAM,GACJ,MAAM,CAQlB;AAaD;;;GAGG;AACH,iEAHW;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GAC5C;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAC,GAAC,IAAI,CAmBjE"}