@vizamodo/modo-dispatcher 1.1.77

package/README.md

@@ -0,0 +1,43 @@
+# @vizamodo/modo-dispatcher
+
+Client-side dispatch engine for the Viza CLI platform. Handles authentication, payload encryption, gateway communication, session lifecycle, and artifact normalization for both runtime (hub-worker) and infra (GitHub Actions) executions.
+
+---
+
+## 🚨 AI & Agentic Workflow Directives
+
+**Do not rely on this root README for system truths.**
+
+Historical context, deep architecture details, coding rules, contracts, and playbooks have been moved to the `.ai/` Layered Context System. All future AI agents and automated tooling **MUST bootstrap via `.clinerules`** and read `.ai/index/README.md` immediately before performing any work on this repository.
+
+> **Quick route for agents:** `.ai/index/README.md` → follow layers 00 → 10 → 20 → 30 in order.
+
+---
+
+## Quick Start (For Humans)
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+| Task | Command |
+|------|---------|
+| Build | `npm run build` |
+| Test | `npm test` |
+| Publish (dev) | `npm run release:dev` |
+| Publish (prod) | `npm run release:prod` |
+
+For advanced build/publish workflows, see [`.ai/40-playbooks/build-and-publish.md`](.ai/40-playbooks/build-and-publish.md).
+
+---
+
+## Package Info
+
+- **npm**: `@vizamodo/modo-dispatcher` (public)
+- **Version**: 1.1.72
+- **Type**: ESM TypeScript library
+- **Runtime**: Node.js >= 20
+- **Dependencies**: `chalk`, `ws`
+- **License**: MIT

package/dist/artifacts/builders.d.ts

@@ -0,0 +1,32 @@
+import type { DispatchResult } from "../types/dispatcher.js";
+import type { Artifacts, RuntimeArtifacts } from "./types.js";
+/**
+ * Build a runtime (hub-worker) DispatchResult from the final session done data.
+ */
+export declare function buildRuntimeResult(done: {
+    sessionId: string;
+    status: string;
+    conclusion: string;
+    artifacts?: object;
+}): DispatchResult;
+/**
+ * Build a GitHub (infra) DispatchResult.
+ * Downloads log and result artifacts from the artifact store.
+ */
+export declare function buildGithubResult(done: {
+    sessionId: string;
+    status: string;
+    conclusion: string;
+    artifacts?: Artifacts;
+}): Promise<DispatchResult>;
+/**
+ * Build the final DispatchResult from a done session.
+ * Dispatches to the runtime or GitHub builder based on runType.
+ */
+export declare function finalizeResult(done: {
+    sessionId: string;
+    status: string;
+    conclusion: string;
+    runType?: string;
+    artifacts?: Artifacts | RuntimeArtifacts | Record<string, unknown> | undefined;
+}): Promise<DispatchResult>;

package/dist/artifacts/builders.js

@@ -0,0 +1,72 @@
+import { GatewayError } from "../core/errors.js";
+import { safeDownloadLogArtifact, safeDownloadResultArtifact } from "./downloader.js";
+import { normalizeArtifact } from "./normalizer.js";
+import { extractErrorInfo } from "../utils/type-guards.js";
+/**
+ * Build a runtime (hub-worker) DispatchResult from the final session done data.
+ */
+export function buildRuntimeResult(done) {
+    const arts = done.artifacts;
+    if (!arts) {
+        throw new GatewayError("Invalid runtime contract: missing artifacts");
+    }
+    const rawLog = arts?.["log"];
+    const log = normalizeArtifact(rawLog);
+    const rawError = arts?.["error"];
+    const error = extractErrorInfo(rawError);
+    const runtimePayload = arts?.["result"] !== undefined ? arts["result"] : arts;
+    const normalized = {
+        kind: "runtime",
+        status: done.status,
+        conclusion: done.conclusion ?? done.status,
+        data: {
+            ok: typeof arts?.["ok"] === "boolean"
+                ? arts["ok"]
+                : done.conclusion === "success",
+            correlationId: done.sessionId,
+            log,
+            result: runtimePayload,
+            ...(error ? { error } : {}),
+        },
+    };
+    return normalized;
+}
+/**
+ * Build a GitHub (infra) DispatchResult.
+ * Downloads log and result artifacts from the artifact store.
+ */
+export async function buildGithubResult(done) {
+    const [logBuffer, resultBuffer] = await Promise.all([
+        safeDownloadLogArtifact(done.artifacts),
+        safeDownloadResultArtifact(done.artifacts),
+    ]);
+    return {
+        kind: "github",
+        status: done.status,
+        conclusion: done.conclusion ?? done.status,
+        ...(done.artifacts?.log !== undefined ? { log: done.artifacts.log } : {}),
+        ...(logBuffer !== undefined ? { logBuffer } : {}),
+        ...(resultBuffer !== undefined ? { resultBuffer } : {}),
+    };
+}
+/**
+ * Build the final DispatchResult from a done session.
+ * Dispatches to the runtime or GitHub builder based on runType.
+ */
+export async function finalizeResult(done) {
+    const artifacts = done.artifacts ?? {};
+    if (done.runType !== "infra") {
+        return buildRuntimeResult({
+            sessionId: done.sessionId,
+            status: done.status,
+            conclusion: done.conclusion,
+            artifacts: artifacts,
+        });
+    }
+    return buildGithubResult({
+        sessionId: done.sessionId,
+        status: done.status,
+        conclusion: done.conclusion,
+        artifacts: artifacts,
+    });
+}

package/dist/artifacts/downloader.d.ts

@@ -0,0 +1,28 @@
+import type { Artifacts } from "./types.js";
+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: {
+    url: string;
+    contentType?: string;
+    name?: string;
+}, options?: DownloadArtifactOptions): Promise<Buffer>;
+export declare function safeDownloadLogArtifact(artifacts?: Artifacts): Promise<Buffer | undefined>;
+export declare function safeDownloadResultArtifact(artifacts?: Artifacts): Promise<Buffer | undefined>;

package/dist/artifacts/downloader.js

@@ -0,0 +1,102 @@
+import { ArtifactInvalidTypeError, ArtifactNotFoundError, ArtifactTooLargeError } from "../core/errors.js";
+/**
+ * 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 async function downloadArtifact(ref, options = {}) {
+    const { maxSizeBytes = 50 * 1024 * 1024 } = options;
+    if (!ref?.url) {
+        throw new Error("\nInvalid artifact reference: missing url");
+    }
+    const res = await fetch(ref.url);
+    if (!res.ok) {
+        throw new Error(`\nFailed 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(`\nArtifact 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(`\nArtifact too large: ${size} bytes exceeds limit ${maxSizeBytes}`);
+        }
+    }
+    const reader = res.body?.getReader();
+    if (!reader) {
+        throw new Error("\nResponse 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(`\nArtifact too large: received ${received} bytes exceeds limit ${maxSizeBytes}`);
+            }
+            chunks.push(value);
+        }
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}
+// Helpers for artifact download
+export async function safeDownloadLogArtifact(artifacts) {
+    if (!artifacts?.log)
+        return undefined;
+    const art = artifacts.log;
+    // Respect artifact status contract
+    if (art.status !== "ok")
+        return undefined;
+    if (!art.downloadUrl)
+        return undefined;
+    try {
+        return await downloadArtifact({
+            url: art.downloadUrl,
+            contentType: "application/zip",
+            name: "log",
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("too large"))
+            throw new ArtifactTooLargeError();
+        if (msg.includes("content-type"))
+            throw new ArtifactInvalidTypeError();
+        throw new ArtifactNotFoundError(undefined, { cause: err });
+    }
+}
+export async function safeDownloadResultArtifact(artifacts) {
+    if (!artifacts?.result)
+        return undefined;
+    const art = artifacts.result;
+    if (!art.downloadUrl)
+        return undefined;
+    try {
+        return await downloadArtifact({
+            url: art.downloadUrl,
+            contentType: art.contentType ?? undefined,
+            name: "result",
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("too large"))
+            throw new ArtifactTooLargeError();
+        if (msg.includes("content-type"))
+            throw new ArtifactInvalidTypeError();
+        throw new ArtifactNotFoundError(undefined, { cause: err });
+    }
+}

package/dist/artifacts/normalizer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Normalize an artifact array.
+ * Accepts both flat arrays and numeric-keyed objects (from different
+ * backend serialization shapes).
+ */
+export declare function normalizeArtifact(raw: unknown): unknown[];
+/**
+ * Build a log artifact object from potentially numeric-keyed raw data.
+ */
+export declare function buildLogArtifact(raw: unknown): object | undefined;
+/**
+ * Normalize accepted artifacts for result consumption.
+ *
+ * Runtime payloads already follow their own semantic contract,
+ * so they are passed through unchanged. Infra artifacts are
+ * normalized to the GitHub artifact shape.
+ */
+export declare function normalizeAcceptedArtifacts(artifacts: unknown, runType?: string): Record<string, unknown> | undefined;
+/**
+ * Read a string artifact key from a raw artifacts object.
+ */
+export declare function readArtifactString(artifacts: Record<string, unknown>, key: string): string | undefined;

package/dist/artifacts/normalizer.js

@@ -0,0 +1,65 @@
+import { extractString, isObject, } from "../utils/type-guards.js";
+/**
+ * Normalize an artifact array.
+ * Accepts both flat arrays and numeric-keyed objects (from different
+ * backend serialization shapes).
+ */
+export function normalizeArtifact(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (!raw || typeof raw !== "object") {
+        return [];
+    }
+    const obj = raw;
+    const numericKeys = Object.keys(obj).filter((k) => !Number.isNaN(Number(k)));
+    if (numericKeys.length === 0) {
+        return [];
+    }
+    return numericKeys
+        .sort((a, b) => Number(a) - Number(b))
+        .map((k) => obj[k]);
+}
+/**
+ * Build a log artifact object from potentially numeric-keyed raw data.
+ */
+export function buildLogArtifact(raw) {
+    if (!isObject(raw) || Array.isArray(raw))
+        return undefined;
+    return {
+        path: extractString(raw, "path") ?? "",
+        downloadUrl: extractString(raw, "downloadUrl") ?? "",
+        status: extractString(raw, "status") ?? "ok",
+        ...raw,
+    };
+}
+/**
+ * Normalize accepted artifacts for result consumption.
+ *
+ * Runtime payloads already follow their own semantic contract,
+ * so they are passed through unchanged. Infra artifacts are
+ * normalized to the GitHub artifact shape.
+ */
+export function normalizeAcceptedArtifacts(artifacts, runType) {
+    if (!isObject(artifacts)) {
+        return undefined;
+    }
+    // Runtime payloads already follow their own semantic contract.
+    if (runType !== "infra") {
+        return artifacts;
+    }
+    const log = buildLogArtifact(artifacts["log"]);
+    const result = isObject(artifacts["result"])
+        ? { ...artifacts["result"] }
+        : undefined;
+    return {
+        ...(log ? { log } : {}),
+        ...(result ? { result } : {}),
+    };
+}
+/**
+ * Read a string artifact key from a raw artifacts object.
+ */
+export function readArtifactString(artifacts, key) {
+    return extractString(artifacts, key);
+}

package/dist/artifacts/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Log artifact produced by GitHub Actions pipeline.
+ * This is the SSOT contract used across dispatcher.
+ */
+export type LogArtifact = {
+    path: string;
+    downloadUrl: string;
+    status: "ok" | "failed";
+    runStatus?: string;
+    conclusion?: string;
+    triggeredAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    queueDuration?: string;
+    runDuration?: string;
+    duration?: string;
+};
+/**
+ * Result artifact (JSON output from workflow)
+ */
+export type ResultArtifact = {
+    path: string;
+    downloadUrl: string;
+    contentType: string;
+};
+/**
+ * Unified artifacts container (SSOT)
+ */
+export type Artifacts = {
+    log?: LogArtifact;
+    result?: ResultArtifact;
+};
+/**
+ * Structured log entry for runtime commands.
+ * Replaces `unknown[]` with proper typing.
+ */
+export interface LogEntry {
+    /** ISO timestamp of the log entry */
+    timestamp?: string;
+    /** Log level */
+    level?: 'info' | 'warn' | 'error' | 'debug';
+    /** Log message */
+    message: string;
+    /** Additional structured metadata */
+    metadata?: Record<string, unknown>;
+    /** Step name if this log belongs to a specific step */
+    step?: string;
+    /** Duration of the operation if applicable */
+    duration?: string;
+}
+/**
+ * Structured error for runtime artifacts.
+ */
+export interface RuntimeError {
+    message: string;
+    stack?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Runtime artifacts with proper typing.
+ * Used for hub-worker runtime commands.
+ */
+export type RuntimeArtifacts = {
+    /** Whether the command succeeded */
+    ok?: boolean;
+    /** Structured log entries */
+    log?: LogEntry[];
+    /** Command result payload */
+    result?: unknown;
+    /** Structured error if command failed */
+    error?: RuntimeError;
+};
+/**
+ * Artifact reference returned by gateway.
+ * Used for lazy loading of artifacts.
+ */
+export interface ArtifactRef {
+    /** Presigned download URL */
+    url: string;
+    /** Expected content type */
+    contentType?: string;
+    /** Human-readable name for diagnostics */
+    name?: string;
+}
+/**
+ * Gateway artifact format (minimal version).
+ * Used for initial response before full artifact is fetched.
+ */
+export interface GatewayArtifactRef {
+    path: string;
+    downloadUrl?: string;
+    contentType?: string;
+}

package/dist/artifacts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/identity/extract-identity.d.ts

@@ -0,0 +1,8 @@
+import { TokenClaims } from "../session/types.js";
+export interface Identity {
+    login: string;
+    teams: string[];
+    email: string;
+    avatarUrl: string;
+}
+export declare function extractIdentity(claims: TokenClaims): Identity;

package/dist/auth/identity/extract-identity.js

@@ -0,0 +1,15 @@
+import { normalizeTeams } from "./normalize-teams.js";
+import { validateClaims } from "./validate-claims.js";
+export function extractIdentity(claims) {
+    validateClaims(claims);
+    const teams = normalizeTeams(claims["teams"]);
+    if (teams.length === 0) {
+        throw new Error("Authentication completed but teams claim is missing.");
+    }
+    return {
+        login: claims.login,
+        teams,
+        email: typeof claims["email"] === "string" ? claims["email"] : "",
+        avatarUrl: typeof claims["avatarUrl"] === "string" ? claims["avatarUrl"] : "",
+    };
+}

package/dist/auth/identity/normalize-teams.d.ts

@@ -0,0 +1 @@
+export declare function normalizeTeams(teamsClaim: unknown): string[];

package/dist/auth/identity/normalize-teams.js

@@ -0,0 +1,5 @@
+export function normalizeTeams(teamsClaim) {
+    return Array.isArray(teamsClaim)
+        ? teamsClaim.filter((team) => typeof team === "string" && team.length > 0)
+        : [];
+}

package/dist/auth/identity/validate-claims.d.ts

@@ -0,0 +1,2 @@
+import { TokenClaims } from "../session/types.js";
+export declare function validateClaims(claims: TokenClaims): void;

package/dist/auth/identity/validate-claims.js

@@ -0,0 +1,5 @@
+export function validateClaims(claims) {
+    if (typeof claims.login !== "string" || !claims.login) {
+        throw new Error("Authentication completed but login claim is missing.");
+    }
+}

package/dist/auth/jwt/parse.d.ts

@@ -0,0 +1,2 @@
+import { TokenClaims } from "../session/types.js";
+export declare function parseJwtClaims(token: string): TokenClaims;

package/dist/auth/jwt/parse.js

@@ -0,0 +1,16 @@
+export function parseJwtClaims(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+        return {};
+    }
+    try {
+        const payloadPart = parts[1];
+        if (!payloadPart)
+            return {};
+        const payload = JSON.parse(Buffer.from(payloadPart, "base64url").toString("utf8"));
+        return payload && typeof payload === "object" ? payload : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/auth/jwt/verify.d.ts

@@ -0,0 +1 @@
+export declare function isJwtExpired(token: string, skewSeconds?: number): boolean;

package/dist/auth/jwt/verify.js

@@ -0,0 +1,9 @@
+import { parseJwtClaims } from "./parse.js";
+export function isJwtExpired(token, skewSeconds = 60) {
+    const claims = parseJwtClaims(token);
+    if (typeof claims.exp !== "number") {
+        return false;
+    }
+    const now = Math.floor(Date.now() / 1000);
+    return claims.exp <= now + skewSeconds;
+}

package/dist/auth/oauth/auth-error.d.ts

@@ -0,0 +1,12 @@
+export interface StructuredAuthError {
+    code: string;
+    message: string;
+    githubLogin?: string;
+    githubUserId?: number;
+    suggestion?: string;
+}
+export declare class AuthError extends Error {
+    readonly authError: StructuredAuthError;
+    constructor(authError: StructuredAuthError);
+}
+export declare function toStructuredAuthError(error: unknown): StructuredAuthError;

package/dist/auth/oauth/auth-error.js

@@ -0,0 +1,47 @@
+const MALFORMED_TRANSPORT_ERROR = {
+    code: "malformed_auth_error_transport",
+    message: "Authentication could not be completed due to an invalid auth error contract.",
+    suggestion: "Retry login. If the issue persists, contact support.",
+};
+export class AuthError extends Error {
+    authError;
+    constructor(authError) {
+        super(authError.message);
+        this.name = "AuthError";
+        this.authError = authError;
+    }
+}
+export function toStructuredAuthError(error) {
+    // (debug logging removed)
+    if (error instanceof AuthError) {
+        return error.authError;
+    }
+    if (isStructuredAuthError(error)) {
+        return {
+            code: error.code,
+            message: error.message,
+            ...(typeof error.githubLogin === "string" ? { githubLogin: error.githubLogin } : {}),
+            ...(typeof error.githubUserId === "number" ? { githubUserId: error.githubUserId } : {}),
+            ...(typeof error.suggestion === "string" ? { suggestion: error.suggestion } : {}),
+        };
+    }
+    if (error instanceof Error) {
+        console.error("[auth] malformed auth error transport from Error", {
+            name: error.name,
+            message: error.message,
+        });
+    }
+    else {
+        console.error("[auth] malformed auth error transport", {
+            receivedType: typeof error,
+            received: error,
+        });
+    }
+    return MALFORMED_TRANSPORT_ERROR;
+}
+function isStructuredAuthError(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return typeof candidate.code === "string" && typeof candidate.message === "string";
+}

package/dist/auth/oauth/auth-session-store.d.ts

@@ -0,0 +1,30 @@
+import { StructuredAuthError } from "./auth-error.js";
+export type AuthSessionStatus = "pending" | "success" | "failed";
+export interface AuthSession {
+    sessionId: string;
+    status: AuthSessionStatus;
+    login?: string;
+    email?: string;
+    avatarUrl?: string;
+    teams?: string[];
+    error?: StructuredAuthError;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface AuthSessionResultPayload {
+    sessionId: string;
+    status: "success" | "failed";
+    login?: string;
+    email?: string;
+    avatarUrl?: string;
+    teams?: string[];
+    error?: StructuredAuthError;
+}
+export declare class AuthSessionStore {
+    private static readonly SESSION_TTL_MS;
+    private readonly sessions;
+    create(sessionId: string): AuthSession;
+    get(sessionId: string): AuthSession | undefined;
+    applyResult(payload: AuthSessionResultPayload): AuthSession | undefined;
+    delete(sessionId: string): void;
+}