@vizamodo/viza-dispatcher 1.3.28

package/README.md

@@ -0,0 +1 @@
+// TODO: implement

package/dist/artifacts/downloader.d.ts

@@ -0,0 +1,22 @@
+import { ArtifactRef } from "./types";
+export interface DownloadArtifactOptions {
+    /**
+     * Maximum allowed artifact size in bytes.
+     * Default: 50 MB
+     */
+    maxSizeBytes?: number;
+}
+/**
+ * Download artifact from a presigned URL with safety guards.
+ *
+ * This function:
+ *  - validates HTTP status
+ *  - enforces size limits
+ *  - validates content-type (if provided)
+ *
+ * It does NOT:
+ *  - retry
+ *  - log
+ *  - exit process
+ */
+export declare function downloadArtifact(ref: ArtifactRef, options?: DownloadArtifactOptions): Promise<Buffer>;

package/dist/artifacts/downloader.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadArtifact = downloadArtifact;
+/**
+ * Download artifact from a presigned URL with safety guards.
+ *
+ * This function:
+ *  - validates HTTP status
+ *  - enforces size limits
+ *  - validates content-type (if provided)
+ *
+ * It does NOT:
+ *  - retry
+ *  - log
+ *  - exit process
+ */
+async function downloadArtifact(ref, options = {}) {
+    const { maxSizeBytes = 50 * 1024 * 1024 } = options;
+    if (!ref?.url) {
+        throw new Error("Invalid artifact reference: missing url");
+    }
+    const res = await fetch(ref.url);
+    if (!res.ok) {
+        throw new Error(`Failed to download artifact: HTTP ${res.status} ${res.statusText}`);
+    }
+    const contentType = res.headers.get("content-type") || undefined;
+    if (ref.contentType && contentType && !contentType.includes(ref.contentType)) {
+        throw new Error(`Artifact content-type mismatch: expected ${ref.contentType}, got ${contentType}`);
+    }
+    const contentLengthHeader = res.headers.get("content-length");
+    if (contentLengthHeader) {
+        const size = Number(contentLengthHeader);
+        if (!Number.isNaN(size) && size > maxSizeBytes) {
+            throw new Error(`Artifact too large: ${size} bytes exceeds limit ${maxSizeBytes}`);
+        }
+    }
+    const reader = res.body?.getReader();
+    if (!reader) {
+        throw new Error("Response body is not readable");
+    }
+    const chunks = [];
+    let received = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            received += value.byteLength;
+            if (received > maxSizeBytes) {
+                throw new Error(`Artifact too large: received ${received} bytes exceeds limit ${maxSizeBytes}`);
+            }
+            chunks.push(value);
+        }
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}

package/dist/artifacts/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Artifact reference returned by the gateway or dispatcher.
+ * This is a pure data contract (no logic).
+ */
+export interface ArtifactRef {
+    /**
+     * Presigned download URL.
+     * Must be an absolute HTTPS URL.
+     */
+    url: string;
+    /**
+     * Optional expected content-type substring.
+     * Example: "application/zip", "application/json".
+     *
+     * If provided, downloader must validate it.
+     */
+    contentType?: string;
+    /**
+     * Optional human-readable artifact name.
+     * Used only for diagnostics or UI, never for logic.
+     */
+    name?: string;
+}

package/dist/artifacts/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// TODO: implement
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/github.d.ts

@@ -0,0 +1,30 @@
+export interface GitHubAuthOptions {
+    /**
+     * GitHub organization to validate against
+     * Example: "Modo-Core"
+     */
+    org: string;
+    /**
+     * REQUIRED.
+     * Target team responsible for this dispatch.
+     * Example: "dev", "billing", "design"
+     */
+    targetTeam: string;
+}
+export interface GitHubIdentity {
+    login: string;
+}
+/**
+ * Ensure GitHub CLI is authenticated and user is authorized.
+ *
+ * This function FAILS FAST:
+ *  - not logged in → throw
+ *  - not org member → throw
+ *  - not in allowed teams → throw
+ *
+ * It does NOT:
+ *  - perform dispatch
+ *  - call gateway
+ *  - print UX
+ */
+export declare function ensureGitHubAuth(options: GitHubAuthOptions): Promise<GitHubIdentity>;

package/dist/auth/github.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureGitHubAuth = ensureGitHubAuth;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+/**
+ * Ensure GitHub CLI is authenticated and user is authorized.
+ *
+ * This function FAILS FAST:
+ *  - not logged in → throw
+ *  - not org member → throw
+ *  - not in allowed teams → throw
+ *
+ * It does NOT:
+ *  - perform dispatch
+ *  - call gateway
+ *  - print UX
+ */
+async function ensureGitHubAuth(options) {
+    // ----------------------------------------------------------
+    // 1. Check gh CLI authentication status
+    // ----------------------------------------------------------
+    try {
+        await execFileAsync("gh", ["auth", "status"]);
+    }
+    catch {
+        throw new Error("GitHub CLI not authenticated. Run `gh auth login` first.");
+    }
+    // ----------------------------------------------------------
+    // 2. Resolve current GitHub user
+    // ----------------------------------------------------------
+    let login;
+    try {
+        const { stdout } = await execFileAsync("gh", [
+            "api",
+            "user",
+            "--jq",
+            ".login",
+        ]);
+        login = stdout.trim();
+    }
+    catch {
+        throw new Error("Failed to resolve GitHub user identity.");
+    }
+    if (!login) {
+        throw new Error("GitHub user identity is empty.");
+    }
+    // ----------------------------------------------------------
+    // 3. Check organization membership
+    // ----------------------------------------------------------
+    try {
+        await execFileAsync("gh", [
+            "api",
+            `orgs/${options.org}/members/${login}`,
+        ]);
+    }
+    catch {
+        throw new Error(`User ${login} is not a member of GitHub organization ${options.org}.`);
+    }
+    // ----------------------------------------------------------
+    // 4. Mandatory team membership check
+    // ----------------------------------------------------------
+    try {
+        await execFileAsync("gh", [
+            "api",
+            `orgs/${options.org}/teams/${options.targetTeam}/memberships/${login}`,
+        ]);
+    }
+    catch {
+        throw new Error(`User ${login} is not a member of required team ${options.targetTeam} in ${options.org}.`);
+    }
+    return { login };
+}

package/dist/core/dispatcher.d.ts

@@ -0,0 +1,22 @@
+import { DispatchInput, DispatchOptions, DispatchResult } from "../types/dispatcher";
+export interface DispatchHandle {
+    sessionId: string;
+    wsUrl: string;
+    /**
+     * Wait until the dispatch session is completed.
+     */
+    wait(): Promise<DispatchResult>;
+}
+/**
+ * Main dispatcher entrypoint.
+ *
+ * This function orchestrates the full dispatch lifecycle:
+ *  - validate
+ *  - POST /dispatch
+ *  - wait for final result via WebSocket
+ *  - artifact download
+ *
+ * It NEVER calls process.exit().
+ * All errors are thrown for the caller (viza-cli) to handle.
+ */
+export declare function dispatch(input: DispatchInput, options: DispatchOptions): Promise<DispatchHandle>;

package/dist/core/dispatcher.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatch = dispatch;
+const errors_1 = require("./errors");
+const dispatch_1 = require("../gateway/dispatch");
+const session_1 = require("../gateway/session");
+const downloader_1 = require("../artifacts/downloader");
+const github_1 = require("../auth/github");
+const encrypt_1 = require("../crypto/encrypt");
+/**
+ * Main dispatcher entrypoint.
+ *
+ * This function orchestrates the full dispatch lifecycle:
+ *  - validate
+ *  - POST /dispatch
+ *  - wait for final result via WebSocket
+ *  - artifact download
+ *
+ * It NEVER calls process.exit().
+ * All errors are thrown for the caller (viza-cli) to handle.
+ */
+async function dispatch(input, options) {
+    const { gateway } = options;
+    if (!gateway?.endpoint) {
+        throw new errors_1.InvalidInputError("Missing gateway endpoint");
+    }
+    // ----------------------------------------------------------
+    // 2. GitHub authentication & authorization (fail-fast)
+    // ----------------------------------------------------------
+    if (!options.auth) {
+        throw new errors_1.InvalidInputError("Missing authentication options. Anonymous dispatch is not allowed.");
+    }
+    await (0, github_1.ensureGitHubAuth)({
+        org: options.auth.org,
+        targetTeam: options.auth.targetTeam,
+    });
+    if (!input.encrypt) {
+        throw new errors_1.InvalidInputError("Encryption is mandatory for dispatch payloads");
+    }
+    const encrypted = await (0, encrypt_1.encryptPayload)(input.payload, input.encrypt);
+    const gatewayReq = {
+        intent: input.intent,
+        target: input.target,
+        eventType: input.eventType,
+        payload: encrypted,
+    };
+    let accepted;
+    try {
+        accepted = await (0, dispatch_1.dispatchToGateway)(gatewayReq, {
+            endpoint: gateway.endpoint,
+        });
+    }
+    catch (err) {
+        throw new errors_1.DispatchRejectedError("Dispatch request rejected by gateway", {
+            cause: err,
+        });
+    }
+    return {
+        sessionId: accepted.sessionId,
+        wsUrl: accepted.wsUrl,
+        async wait() {
+            let done;
+            try {
+                done = await (0, session_1.waitForSessionDone)(accepted.wsUrl);
+            }
+            catch (err) {
+                if (err?.name === "SessionTimeoutError") {
+                    throw new errors_1.SessionTimeoutError();
+                }
+                throw new errors_1.GatewayError("Gateway session error", { cause: err });
+            }
+            let logBuffer;
+            if (done.artifacts?.log) {
+                try {
+                    logBuffer = await (0, downloader_1.downloadArtifact)(done.artifacts.log);
+                }
+                catch (err) {
+                    const msg = String(err?.message || "");
+                    if (msg.includes("too large")) {
+                        throw new errors_1.ArtifactTooLargeError();
+                    }
+                    if (msg.includes("content-type")) {
+                        throw new errors_1.ArtifactInvalidTypeError();
+                    }
+                    throw new errors_1.ArtifactNotFoundError(undefined, { cause: err });
+                }
+            }
+            return {
+                status: done.status,
+                artifacts: done.artifacts,
+                logBuffer,
+            };
+        },
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Error taxonomy for viza-dispatcher
+ *
+ * Goals:
+ * - Deterministic exit codes for viza-cli
+ * - Fail-fast, no side effects
+ * - Machine-readable + human-readable
+ */
+export declare enum DispatcherExitCode {
+    OK = 0,
+    INVALID_INPUT = 2,
+    GITHUB_NOT_LOGGED_IN = 10,
+    GITHUB_FORBIDDEN = 11,
+    DISPATCH_REJECTED = 20,
+    SESSION_TIMEOUT = 21,
+    GATEWAY_ERROR = 22,
+    ARTIFACT_NOT_FOUND = 30,
+    ARTIFACT_TOO_LARGE = 31,
+    ARTIFACT_INVALID_TYPE = 32,
+    INTERNAL_ERROR = 90
+}
+export interface DispatcherErrorOptions {
+    cause?: unknown;
+    details?: Record<string, any>;
+}
+/**
+ * Base dispatcher error
+ */
+export declare class DispatcherError extends Error {
+    readonly exitCode: DispatcherExitCode;
+    readonly details?: Record<string, any>;
+    readonly cause?: unknown;
+    constructor(message: string, exitCode: DispatcherExitCode, options?: DispatcherErrorOptions);
+}
+export declare class InvalidInputError extends DispatcherError {
+    constructor(message: string, options?: DispatcherErrorOptions);
+}
+export declare class GitHubNotLoggedInError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class GitHubForbiddenError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class DispatchRejectedError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class SessionTimeoutError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class GatewayError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class ArtifactNotFoundError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class ArtifactTooLargeError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class ArtifactInvalidTypeError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+export declare class InternalDispatcherError extends DispatcherError {
+    constructor(message?: string, options?: DispatcherErrorOptions);
+}
+/**
+ * Normalize unknown errors into DispatcherError
+ * Used by viza-cli boundary
+ */
+export declare function normalizeDispatcherError(err: unknown): DispatcherError;

package/dist/core/errors.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Error taxonomy for viza-dispatcher
+ *
+ * Goals:
+ * - Deterministic exit codes for viza-cli
+ * - Fail-fast, no side effects
+ * - Machine-readable + human-readable
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternalDispatcherError = exports.ArtifactInvalidTypeError = exports.ArtifactTooLargeError = exports.ArtifactNotFoundError = exports.GatewayError = exports.SessionTimeoutError = exports.DispatchRejectedError = exports.GitHubForbiddenError = exports.GitHubNotLoggedInError = exports.InvalidInputError = exports.DispatcherError = exports.DispatcherExitCode = void 0;
+exports.normalizeDispatcherError = normalizeDispatcherError;
+var DispatcherExitCode;
+(function (DispatcherExitCode) {
+    DispatcherExitCode[DispatcherExitCode["OK"] = 0] = "OK";
+    // Input / usage
+    DispatcherExitCode[DispatcherExitCode["INVALID_INPUT"] = 2] = "INVALID_INPUT";
+    // Auth / permission
+    DispatcherExitCode[DispatcherExitCode["GITHUB_NOT_LOGGED_IN"] = 10] = "GITHUB_NOT_LOGGED_IN";
+    DispatcherExitCode[DispatcherExitCode["GITHUB_FORBIDDEN"] = 11] = "GITHUB_FORBIDDEN";
+    // Network / gateway
+    DispatcherExitCode[DispatcherExitCode["DISPATCH_REJECTED"] = 20] = "DISPATCH_REJECTED";
+    DispatcherExitCode[DispatcherExitCode["SESSION_TIMEOUT"] = 21] = "SESSION_TIMEOUT";
+    DispatcherExitCode[DispatcherExitCode["GATEWAY_ERROR"] = 22] = "GATEWAY_ERROR";
+    // Artifacts / logs
+    DispatcherExitCode[DispatcherExitCode["ARTIFACT_NOT_FOUND"] = 30] = "ARTIFACT_NOT_FOUND";
+    DispatcherExitCode[DispatcherExitCode["ARTIFACT_TOO_LARGE"] = 31] = "ARTIFACT_TOO_LARGE";
+    DispatcherExitCode[DispatcherExitCode["ARTIFACT_INVALID_TYPE"] = 32] = "ARTIFACT_INVALID_TYPE";
+    // Internal / unexpected
+    DispatcherExitCode[DispatcherExitCode["INTERNAL_ERROR"] = 90] = "INTERNAL_ERROR";
+})(DispatcherExitCode || (exports.DispatcherExitCode = DispatcherExitCode = {}));
+/**
+ * Base dispatcher error
+ */
+class DispatcherError extends Error {
+    constructor(message, exitCode, options) {
+        super(message);
+        this.name = this.constructor.name;
+        this.exitCode = exitCode;
+        this.details = options?.details;
+        this.cause = options?.cause;
+    }
+}
+exports.DispatcherError = DispatcherError;
+/* -----------------------------
+ * Input / validation
+ * ----------------------------- */
+class InvalidInputError extends DispatcherError {
+    constructor(message, options) {
+        super(message, DispatcherExitCode.INVALID_INPUT, options);
+    }
+}
+exports.InvalidInputError = InvalidInputError;
+/* -----------------------------
+ * GitHub auth
+ * ----------------------------- */
+class GitHubNotLoggedInError extends DispatcherError {
+    constructor(message = "Not logged in to GitHub", options) {
+        super(message, DispatcherExitCode.GITHUB_NOT_LOGGED_IN, options);
+    }
+}
+exports.GitHubNotLoggedInError = GitHubNotLoggedInError;
+class GitHubForbiddenError extends DispatcherError {
+    constructor(message = "GitHub permission denied", options) {
+        super(message, DispatcherExitCode.GITHUB_FORBIDDEN, options);
+    }
+}
+exports.GitHubForbiddenError = GitHubForbiddenError;
+/* -----------------------------
+ * Gateway / dispatch
+ * ----------------------------- */
+class DispatchRejectedError extends DispatcherError {
+    constructor(message = "Dispatch request rejected", options) {
+        super(message, DispatcherExitCode.DISPATCH_REJECTED, options);
+    }
+}
+exports.DispatchRejectedError = DispatchRejectedError;
+class SessionTimeoutError extends DispatcherError {
+    constructor(message = "Dispatch session timed out", options) {
+        super(message, DispatcherExitCode.SESSION_TIMEOUT, options);
+    }
+}
+exports.SessionTimeoutError = SessionTimeoutError;
+class GatewayError extends DispatcherError {
+    constructor(message = "Gateway error", options) {
+        super(message, DispatcherExitCode.GATEWAY_ERROR, options);
+    }
+}
+exports.GatewayError = GatewayError;
+/* -----------------------------
+ * Artifacts
+ * ----------------------------- */
+class ArtifactNotFoundError extends DispatcherError {
+    constructor(message = "Artifact not found", options) {
+        super(message, DispatcherExitCode.ARTIFACT_NOT_FOUND, options);
+    }
+}
+exports.ArtifactNotFoundError = ArtifactNotFoundError;
+class ArtifactTooLargeError extends DispatcherError {
+    constructor(message = "Artifact exceeds size limit", options) {
+        super(message, DispatcherExitCode.ARTIFACT_TOO_LARGE, options);
+    }
+}
+exports.ArtifactTooLargeError = ArtifactTooLargeError;
+class ArtifactInvalidTypeError extends DispatcherError {
+    constructor(message = "Invalid artifact content type", options) {
+        super(message, DispatcherExitCode.ARTIFACT_INVALID_TYPE, options);
+    }
+}
+exports.ArtifactInvalidTypeError = ArtifactInvalidTypeError;
+/* -----------------------------
+ * Internal
+ * ----------------------------- */
+class InternalDispatcherError extends DispatcherError {
+    constructor(message = "Internal dispatcher error", options) {
+        super(message, DispatcherExitCode.INTERNAL_ERROR, options);
+    }
+}
+exports.InternalDispatcherError = InternalDispatcherError;
+/**
+ * Normalize unknown errors into DispatcherError
+ * Used by viza-cli boundary
+ */
+function normalizeDispatcherError(err) {
+    if (err instanceof DispatcherError)
+        return err;
+    if (err instanceof Error) {
+        return new InternalDispatcherError(err.message, { cause: err });
+    }
+    return new InternalDispatcherError("Unknown error", { cause: err });
+}

package/dist/crypto/encrypt.d.ts

@@ -0,0 +1,12 @@
+import { EncryptedPayload } from "../gateway/types";
+import { EncryptOptions } from "../types/dispatcher";
+/**
+ * Encrypt payload using X25519 + HKDF + AES-256-GCM.
+ *
+ * Security properties:
+ *  - Ephemeral client key per invocation
+ *  - Forward secrecy
+ *  - AEAD (authenticated encryption)
+ *  - No plaintext on wire
+ */
+export declare function encryptPayload(payload: Record<string, any>, opts: EncryptOptions): EncryptedPayload;

package/dist/crypto/encrypt.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptPayload = encryptPayload;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Encrypt payload using X25519 + HKDF + AES-256-GCM.
+ *
+ * Security properties:
+ *  - Ephemeral client key per invocation
+ *  - Forward secrecy
+ *  - AEAD (authenticated encryption)
+ *  - No plaintext on wire
+ */
+function encryptPayload(payload, opts) {
+    if (!opts?.serverPublicKeyPem) {
+        throw new Error("Missing server public key for encryption");
+    }
+    // Normalize payload into an object we can safely enrich
+    let normalized;
+    if (payload === null || payload === undefined) {
+        normalized = {};
+    }
+    else if (typeof payload === "object") {
+        normalized = payload;
+    }
+    else {
+        // Primitive payloads are wrapped
+        normalized = { value: payload };
+    }
+    // Record signing time (server validates freshness using |now - created| window)
+    normalized.created = Date.now();
+    const payloadStr = JSON.stringify(normalized);
+    // Load server public key (injected, not read from FS)
+    const serverPubKey = crypto_1.default.createPublicKey(opts.serverPublicKeyPem);
+    // Generate ephemeral client key pair
+    const clientKeyPair = crypto_1.default.generateKeyPairSync("x25519");
+    const clientPriv = clientKeyPair.privateKey;
+    const clientPub = clientKeyPair.publicKey;
+    // Derive shared secret
+    const sharedSecret = crypto_1.default.diffieHellman({
+        privateKey: clientPriv,
+        publicKey: serverPubKey,
+    });
+    // Derive symmetric key via HKDF
+    const aesKey = Buffer.from(crypto_1.default.hkdfSync("sha256", sharedSecret, Buffer.alloc(0), "viza-ecdh-key", 32));
+    // Encrypt using AES-256-GCM
+    const iv = crypto_1.default.randomBytes(12);
+    const cipher = crypto_1.default.createCipheriv("aes-256-gcm", aesKey, iv);
+    const encrypted = Buffer.concat([
+        cipher.update(payloadStr, "utf8"),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    const result = {
+        alg: "x25519-hkdf-aes256gcm",
+        clientPub: clientPub
+            .export({ type: "spki", format: "der" })
+            .toString("base64"),
+        iv: iv.toString("base64"),
+        tag: tag.toString("base64"),
+        data: encrypted.toString("base64"),
+        created: normalized.created,
+    };
+    return result;
+}

package/dist/gateway/dispatch.d.ts

@@ -0,0 +1,22 @@
+import { GatewayDispatchRequest, GatewayDispatchAccepted } from "./types";
+export interface DispatchToGatewayOptions {
+    /**
+     * Base HTTPS endpoint of the gateway worker
+     * Example: https://dispatch.viza.io
+     */
+    endpoint: string;
+    /**
+     * Optional request timeout in ms (default: 15s)
+     */
+    timeoutMs?: number;
+}
+/**
+ * POST /dispatch
+ *
+ * Low-level gateway call.
+ * This function:
+ *  - does NOT retry
+ *  - does NOT handle UX
+ *  - does NOT swallow errors
+ */
+export declare function dispatchToGateway(req: GatewayDispatchRequest, options: DispatchToGatewayOptions): Promise<GatewayDispatchAccepted>;

package/dist/gateway/dispatch.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchToGateway = dispatchToGateway;
+/**
+ * POST /dispatch
+ *
+ * Low-level gateway call.
+ * This function:
+ *  - does NOT retry
+ *  - does NOT handle UX
+ *  - does NOT swallow errors
+ */
+async function dispatchToGateway(req, options) {
+    const { endpoint, timeoutMs = 15000 } = options;
+    if (!endpoint.startsWith("https://")) {
+        throw new Error(`Invalid gateway endpoint: ${endpoint}`);
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(`${endpoint}/dispatch`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(req),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        if (err?.name === "AbortError") {
+            throw new Error("Gateway dispatch request timed out");
+        }
+        throw new Error(`Failed to reach gateway: ${err?.message ?? err}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    if (!res.ok) {
+        const text = await safeReadText(res);
+        throw new Error(`Gateway HTTP error ${res.status}: ${text || res.statusText}`);
+    }
+    let json;
+    try {
+        json = (await res.json());
+    }
+    catch {
+        throw new Error("Gateway returned invalid JSON");
+    }
+    if (!json || typeof json !== "object" || !("ok" in json)) {
+        throw new Error("Gateway response does not match dispatch contract");
+    }
+    if (json.ok !== true) {
+        throw new Error(json.message
+            ? `Dispatch rejected: ${json.message}`
+            : `Dispatch rejected: ${json.error}`);
+    }
+    // Basic sanity checks
+    if (typeof json.sessionId !== "string" ||
+        typeof json.wsUrl !== "string" ||
+        typeof json.expiresAt !== "number") {
+        throw new Error("Gateway accepted response is malformed");
+    }
+    return json;
+}
+async function safeReadText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/gateway/session.d.ts

@@ -0,0 +1,16 @@
+import { GatewaySessionDoneEvent } from "./types";
+export interface WaitForSessionOptions {
+    /**
+     * Maximum time to wait for session completion (ms)
+     * Default: 10 minutes
+     */
+    timeoutMs?: number;
+}
+/**
+ * Wait for session completion via WebSocket.
+ *
+ * Contract:
+ *  - Gateway sends exactly ONE message: { type: "done", ... }
+ *  - Connection is closed after that
+ */
+export declare function waitForSessionDone(wsUrl: string, options?: WaitForSessionOptions): Promise<GatewaySessionDoneEvent>;

package/dist/gateway/session.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForSessionDone = waitForSessionDone;
+/**
+ * Wait for session completion via WebSocket.
+ *
+ * Contract:
+ *  - Gateway sends exactly ONE message: { type: "done", ... }
+ *  - Connection is closed after that
+ */
+function waitForSessionDone(wsUrl, options = {}) {
+    const { timeoutMs = 10 * 60 * 1000 } = options;
+    if (!wsUrl.startsWith("wss://")) {
+        return Promise.reject(new Error(`Invalid WebSocket URL: ${wsUrl}`));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const ws = new WebSocket(wsUrl);
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            ws.close();
+            reject(new Error("Session wait timed out"));
+        }, timeoutMs);
+        ws.onmessage = (event) => {
+            if (settled)
+                return;
+            let data;
+            try {
+                data = JSON.parse(String(event.data));
+            }
+            catch {
+                settled = true;
+                clearTimeout(timeout);
+                ws.close();
+                reject(new Error("Invalid JSON received from gateway"));
+                return;
+            }
+            if (!data ||
+                typeof data !== "object" ||
+                data.type !== "done") {
+                settled = true;
+                clearTimeout(timeout);
+                ws.close();
+                reject(new Error("Unexpected WebSocket message from gateway"));
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            ws.close();
+            resolve(data);
+        };
+        ws.onerror = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            ws.close();
+            reject(new Error("WebSocket error while waiting for session"));
+        };
+        ws.onclose = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(new Error("WebSocket closed before session completion"));
+        };
+    });
+}

package/dist/gateway/types.d.ts

@@ -0,0 +1,90 @@
+export interface EncryptedPayload {
+    alg: "x25519-hkdf-aes256gcm";
+    clientPub: string;
+    iv: string;
+    tag: string;
+    data: string;
+    created: number;
+}
+export interface GatewayDispatchRequest {
+    /**
+     * Intent identifier
+     * e.g. "deploy-base-worker", "publish-billing", "query-repo"
+     */
+    intent: string;
+    /**
+     * Maps to GitHub `repository_dispatch.event_type`
+     */
+    eventType: string;
+    /**
+     * Target repository information
+     */
+    target: {
+        owner: string;
+        repo: string;
+        ref?: string;
+    };
+    /**
+     * Payload is ALWAYS encrypted.
+     * Gateway must decrypt before forwarding.
+     */
+    payload: EncryptedPayload;
+}
+export interface GatewayDispatchAccepted {
+    ok: true;
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * WebSocket endpoint for session completion notification
+     *
+     * Example:
+     *   wss://dispatch.viza.io/session/<sessionId>
+     */
+    wsUrl: string;
+    /**
+     * Unix timestamp (seconds)
+     * After this time the session may be garbage collected
+     */
+    expiresAt: number;
+}
+export interface GatewayDispatchRejected {
+    ok: false;
+    /**
+     * Stable error code for client handling
+     */
+    error: string;
+    /**
+     * Human-readable explanation (for CLI display)
+     */
+    message?: string;
+}
+export type GatewayDispatchResponse = GatewayDispatchAccepted | GatewayDispatchRejected;
+export interface GatewaySessionDoneEvent {
+    type: "done";
+    sessionId: string;
+    /**
+     * Final execution status
+     */
+    status: "success" | "failed" | "cancelled";
+    /**
+     * Artifacts generated by the workflow
+     * These are presigned URLs (read-only)
+     */
+    artifacts?: {
+        log?: ArtifactRef;
+        result?: ArtifactRef;
+    };
+}
+export interface ArtifactRef {
+    /**
+     * Presigned download URL
+     */
+    url: string;
+    /**
+     * Optional metadata
+     */
+    contentType?: string;
+    size?: number;
+}

package/dist/gateway/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/* ============================================================
+ * Gateway ⇄ Dispatcher Contract (Encryption-Only)
+ * ============================================================
+ * Notes:
+ * - Gateway MUST NOT stream logs
+ * - Logs are fetched later via presigned artifact URLs
+ * - WebSocket is used ONLY for final status notification
+ * ============================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";
+// TODO: implement

package/dist/types/dispatcher.d.ts

@@ -0,0 +1,119 @@
+import { GitHubAuthOptions } from "../auth/github";
+import { GatewayDispatchRequest } from "../gateway/types";
+export interface EncryptOptions {
+    /**
+     * Server public key in PEM (SPKI) format.
+     * This key is used to derive the shared secret via X25519.
+     */
+    serverPublicKeyPem: string;
+}
+/****
+ * Public types for viza-dispatcher.
+ * These types form the stable contract between viza-cli and viza-dispatcher.
+ */
+/**
+ * Normalized repository target.
+ * Parsed by viza-cli, forwarded verbatim by viza-dispatcher.
+ */
+export type DispatchRepoTarget = GatewayDispatchRequest["target"];
+/**
+ * Input describing what to dispatch.
+ */
+export interface DispatchInput {
+    /**
+     * Intent name (e.g. "deploy-worker", "publish-app").
+     * Interpreted by the gateway.
+     */
+    intent: string;
+    /**
+     * Normalized dispatch target.
+     * Must already conform to gateway contract.
+     */
+    target: DispatchRepoTarget;
+    /**
+     * Plain business payload.
+     * Payload is ALWAYS encrypted before being sent to gateway.
+     * Plain payload never leaves dispatcher.
+     */
+    payload: unknown;
+    /**
+     * Maps to GitHub repository_dispatch.event_type.
+     */
+    eventType: string;
+    /**
+     * Encryption options.
+     * Encryption is mandatory; dispatcher will encrypt payload
+     * and emit an encrypted DispatchPayloadEnvelope.
+     */
+    encrypt: EncryptOptions;
+}
+/**
+ * Gateway-related options.
+ */
+export interface DispatchGatewayOptions {
+    /**
+     * Base HTTPS endpoint of the dispatch gateway.
+     * Example: https://dispatch.viza.io
+     */
+    endpoint: string;
+}
+/**
+ * UI-related toggles.
+ * NOTE: Dispatcher itself does NOT render UI.
+ * These flags are only passed through for caller coordination.
+ */
+export interface DispatchUIOptions {
+    /**
+     * Whether banner/spinner/logs are enabled.
+     * Dispatcher does not interpret these flags directly.
+     */
+    banner?: boolean;
+    spinner?: boolean;
+    showLog?: boolean;
+}
+/**
+ * Options controlling dispatch behavior.
+ */
+export interface DispatchOptions {
+    gateway: DispatchGatewayOptions;
+    auth: GitHubAuthOptions;
+}
+/**
+ * Artifact reference returned by the gateway.
+ */
+export interface DispatchArtifactRef {
+    /**
+     * Presigned download URL.
+     */
+    url: string;
+    /**
+     * Optional content type hint.
+     */
+    contentType?: string;
+}
+/**
+ * Artifacts produced by a dispatch session.
+ */
+export interface DispatchArtifacts {
+    log?: DispatchArtifactRef;
+    result?: DispatchArtifactRef;
+}
+/**
+ * Final result returned by the dispatcher.
+ * This is consumed by viza-cli.
+ */
+export interface DispatchResult {
+    /**
+     * Final status of the session.
+     */
+    status: "success" | "failed" | "cancelled";
+    /**
+     * Artifact references (if any).
+     */
+    artifacts?: DispatchArtifacts;
+    /**
+     * Raw log archive buffer (zip), if downloaded.
+     * CLI decides how to render or ignore it.
+     */
+    logBuffer?: Buffer;
+}

package/dist/types/dispatcher.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/payload.js

@@ -0,0 +1,2 @@
+"use strict";
+// TODO: implement

package/dist/types/result.js

@@ -0,0 +1,2 @@
+"use strict";
+// TODO: implement

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@vizamodo/viza-dispatcher",
+  "version": "1.3.28",
+  "description": "Dispatcher module for GitHub workflow automation across Viza projects",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "release:dev": "npm version prerelease --preid=dev && npm publish --tag dev --access public",
+    "release:beta": "npm version prerelease --preid=beta && npm publish --tag beta --access public",
+    "release:prod": "rm -rf dist && npx npm-check-updates -u && npm install && git add package.json package-lock.json && git commit -m 'chore(deps): auto update dependencies before release' || echo 'No changes' && node versioning.js && npm login && npm publish --tag latest --access public && git push"
+  },
+  "files": [
+    "dist",
+    ".keys"
+  ],
+  "bin": {
+    "viza-dispatcher": "dist/index.js"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "author": "Viza Team",
+  "license": "MIT",
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "chalk": "^5.6.2"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
+    "@types/node": "^25.0.6",
+    "typescript": "^5.9.3"
+  },
+  "type": "module"
+}