@weiyentan/opencode-plugin-awx 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,148 @@
+/**
+ * client.ts — HTTP middleware pipeline for the AWX plugin.
+ *
+ * Composes five middleware concerns into a single request pipeline:
+ *   signal → timeout → breaker gate → fetch → retry/backoff
+ *
+ * ## Pipeline
+ *
+ *  1. Combine ToolContext.abort signal + timeout signal
+ *  2. Circuit breaker gate (per-tool)
+ *  3. Native fetch with Authorization header
+ *  4. Response handling: 2xx pass, 4xx no retry, 5xx exponential backoff
+ *
+ * ## Reference
+ *
+ *  - ADR 0006: Connection Resilience Parameters
+ *  - docs/client-middleware-design.md
+ */
+import { MetricsStore } from "./metrics.js";
+/**
+ * Calculate the exponential backoff delay for a given retry attempt.
+ *
+ * Formula: base * multiplier^attempt + random(0, jitterRatio * calculated)
+ *
+ * Attempt 0 → 1000ms + 0-500ms jitter
+ * Attempt 1 → 2000ms + 0-1000ms jitter
+ * Attempt 2 → 4000ms + 0-2000ms jitter
+ *
+ * @param attempt  0-based retry attempt index
+ * @returns Delay in milliseconds
+ */
+export declare function calcBackoff(attempt: number): number;
+/**
+ * Sleep for a given duration, aborting immediately if the signal fires.
+ *
+ * Used during retry backoff so that an abort (ToolContext.abort or timeout)
+ * cancels the wait immediately instead of waiting for the backoff to elapse.
+ *
+ * @param ms      Duration in milliseconds
+ * @param signal  Optional AbortSignal — abort listener fires, wait cancels
+ */
+export declare function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Create an AbortSignal that triggers after the specified timeout.
+ *
+ * Uses `setTimeout` + `AbortController` rather than `AbortSignal.timeout()`
+ * for Node 18 compatibility and to ensure compatibility with vitest fake
+ * timers (the native `AbortSignal.timeout()` uses internal Node.js timers
+ * that cannot be mocked by vitest).
+ */
+export declare function createTimeoutSignal(ms: number): {
+    signal: AbortSignal;
+    clear: () => void;
+};
+/** Options for createClient */
+export interface ClientOptions {
+    /** Request timeout in milliseconds (default: 30_000) */
+    timeoutMs?: number;
+    /** Maximum retries on 5xx (default: 3) */
+    maxRetries?: number;
+    /** Circuit breaker trip threshold — consecutive errors before opening (default: 5) */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker cooldown in ms (default: 30_000) */
+    circuitBreakerCooldownMs?: number;
+    /**
+     * Optional shared MetricsStore for plugin-level persistence lifecycle.
+     * If not provided, a new MetricsStore is created internally.
+     * Pass the plugin-level store here so that periodic persist and
+     * init-time load are effective across all tools.
+     */
+    metricsStore?: MetricsStore;
+}
+/** The AWX HTTP client returned by createClient */
+export interface AwxClient {
+    /**
+     * Send an HTTP request through the middleware pipeline.
+     *
+     * @param toolName  Per-tool circuit breaker identifier
+     * @param path      API path (e.g., "/api/v2/job_templates/")
+     * @param init      Fetch options (method, body, headers)
+     * @param abortSignal  Optional ToolContext.abort signal for cancellation
+     */
+    request(toolName: string, path: string, init?: RequestInit, abortSignal?: AbortSignal): Promise<Response>;
+}
+/** Circuit breaker state */
+export type BreakerStateKind = "closed" | "open" | "half-open";
+/** Per-tool circuit breaker state */
+export interface BreakerState {
+    state: BreakerStateKind;
+    failureCount: number;
+    cooldownUntil: number | null;
+}
+/**
+ * Circuit breaker for per-tool request resilience.
+ *
+ * - **CLOSED**: Normal operation, requests pass through.
+ * - **OPEN**: Tripped after N consecutive failures. Requests rejected immediately.
+ * - **HALF-OPEN**: After cooldown elapses, one probe request is allowed.
+ *   Success → CLOSED, Failure → OPEN again.
+ *
+ * Uses `Date.now()` for time which works with vitest fake timers
+ * (vi.useFakeTimers() mocks Date by default).
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private cooldownUntil;
+    private readonly tripThreshold;
+    private readonly cooldownMs;
+    /**
+     * @param tripThreshold  Consecutive failures before opening (default: 5)
+     * @param cooldownMs     Milliseconds before transitioning OPEN → HALF-OPEN (default: 30_000)
+     */
+    constructor(tripThreshold?: number, cooldownMs?: number);
+    /**
+     * Try to acquire permission to make a request through the breaker.
+     *
+     * Has a side effect: if OPEN and cooldown has elapsed, transitions to
+     * HALF-OPEN to allow a probe request.
+     *
+     * - OPEN: Returns false if still in cooldown. If cooldown elapsed, transitions
+     *   to HALF-OPEN and returns true (probe allowed).
+     * - HALF-OPEN or CLOSED: Returns true.
+     */
+    tryAcquire(): boolean;
+    /** Record a successful request — resets the breaker to CLOSED. */
+    recordSuccess(): void;
+    /**
+     * Record a failed request.
+     *
+     * Increments the failure counter. If the trip threshold is reached, opens the
+     * breaker and sets the cooldown timer.
+     *
+     * In HALF-OPEN state, a single failure immediately re-opens the breaker.
+     */
+    recordFailure(): void;
+    /** Get the current breaker state (for testing/diagnostics). */
+    getState(): BreakerState;
+}
+/**
+ * Create an AWX HTTP client with middleware pipeline.
+ *
+ * @param baseUrl  The AAP base URL (e.g., "https://example.com")
+ * @param token    Bearer token (PAT) for Authorization header
+ * @param opts     Optional client configuration
+ */
+export declare function createClient(baseUrl: string, token: string, opts?: ClientOptions): AwxClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkB5C;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAInD;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAU1F;AA2BD,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,uDAAuD;IACvD,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB;;;;;;;OAOG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,WAAW,EAClB,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtB;AAID,4BAA4B;AAC5B,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE/D,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;OAGG;gBACS,aAAa,SAAI,EAAE,UAAU,SAAS;IAKlD;;;;;;;;;OASG;IACH,UAAU,IAAI,OAAO;IAYrB,kEAAkE;IAClE,aAAa,IAAI,IAAI;IAMrB;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI;IAarB,+DAA+D;IAC/D,QAAQ,IAAI,YAAY;CAOzB;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,aAAa,GACnB,SAAS,CAgKX"}

package/dist/client.js

@@ -0,0 +1,334 @@
+/**
+ * client.ts — HTTP middleware pipeline for the AWX plugin.
+ *
+ * Composes five middleware concerns into a single request pipeline:
+ *   signal → timeout → breaker gate → fetch → retry/backoff
+ *
+ * ## Pipeline
+ *
+ *  1. Combine ToolContext.abort signal + timeout signal
+ *  2. Circuit breaker gate (per-tool)
+ *  3. Native fetch with Authorization header
+ *  4. Response handling: 2xx pass, 4xx no retry, 5xx exponential backoff
+ *
+ * ## Reference
+ *
+ *  - ADR 0006: Connection Resilience Parameters
+ *  - docs/client-middleware-design.md
+ */
+import { MetricsStore } from "./metrics.js";
+/* ── Retry / Backoff parameters ─────────────────────────────────── */
+/** Default max retries (3 retries = 4 total attempts) */
+const DEFAULT_MAX_RETRIES = 3;
+/** Base backoff delay in milliseconds */
+const BACKOFF_BASE_MS = 1000;
+/** Backoff multiplier (exponential) */
+const BACKOFF_MULTIPLIER = 2;
+/** Jitter range: 0 to 50% of calculated delay */
+const JITTER_RATIO = 0.5;
+/* ── Pure utility functions ────────────────────────────────────── */
+/**
+ * Calculate the exponential backoff delay for a given retry attempt.
+ *
+ * Formula: base * multiplier^attempt + random(0, jitterRatio * calculated)
+ *
+ * Attempt 0 → 1000ms + 0-500ms jitter
+ * Attempt 1 → 2000ms + 0-1000ms jitter
+ * Attempt 2 → 4000ms + 0-2000ms jitter
+ *
+ * @param attempt  0-based retry attempt index
+ * @returns Delay in milliseconds
+ */
+export function calcBackoff(attempt) {
+    const base = BACKOFF_BASE_MS * Math.pow(BACKOFF_MULTIPLIER, attempt);
+    const jitter = Math.random() * base * JITTER_RATIO;
+    return Math.round(base + jitter);
+}
+/**
+ * Sleep for a given duration, aborting immediately if the signal fires.
+ *
+ * Used during retry backoff so that an abort (ToolContext.abort or timeout)
+ * cancels the wait immediately instead of waiting for the backoff to elapse.
+ *
+ * @param ms      Duration in milliseconds
+ * @param signal  Optional AbortSignal — abort listener fires, wait cancels
+ */
+export async function sleepWithAbort(ms, signal) {
+    if (signal?.aborted) {
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        const timer = setTimeout(() => {
+            resolve();
+            signal?.removeEventListener("abort", onAbort);
+        }, ms);
+        if (!signal)
+            return;
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/* ── Node 18 Compatibility Helpers ─────────────────────────────── */
+/**
+ * Create an AbortSignal that triggers after the specified timeout.
+ *
+ * Uses `setTimeout` + `AbortController` rather than `AbortSignal.timeout()`
+ * for Node 18 compatibility and to ensure compatibility with vitest fake
+ * timers (the native `AbortSignal.timeout()` uses internal Node.js timers
+ * that cannot be mocked by vitest).
+ */
+export function createTimeoutSignal(ms) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), ms);
+    return {
+        signal: controller.signal,
+        clear: () => clearTimeout(timer),
+    };
+}
+/**
+ * Combine multiple AbortSignals into one — aborts if ANY source signal aborts.
+ *
+ * Uses `AbortSignal.any()` on Node 20+ (where it is natively available),
+ * and falls back to manual event wiring on Node 18.
+ */
+function anyAbortSignal(signals) {
+    if (typeof AbortSignal.any === "function") {
+        return AbortSignal.any(signals);
+    }
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason ?? new DOMException("Aborted", "AbortError"));
+            return controller.signal;
+        }
+        signal.addEventListener("abort", () => {
+            controller.abort(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        }, { once: true });
+    }
+    return controller.signal;
+}
+/**
+ * Circuit breaker for per-tool request resilience.
+ *
+ * - **CLOSED**: Normal operation, requests pass through.
+ * - **OPEN**: Tripped after N consecutive failures. Requests rejected immediately.
+ * - **HALF-OPEN**: After cooldown elapses, one probe request is allowed.
+ *   Success → CLOSED, Failure → OPEN again.
+ *
+ * Uses `Date.now()` for time which works with vitest fake timers
+ * (vi.useFakeTimers() mocks Date by default).
+ */
+export class CircuitBreaker {
+    state = "closed";
+    failureCount = 0;
+    cooldownUntil = null;
+    tripThreshold;
+    cooldownMs;
+    /**
+     * @param tripThreshold  Consecutive failures before opening (default: 5)
+     * @param cooldownMs     Milliseconds before transitioning OPEN → HALF-OPEN (default: 30_000)
+     */
+    constructor(tripThreshold = 5, cooldownMs = 30_000) {
+        this.tripThreshold = tripThreshold;
+        this.cooldownMs = cooldownMs;
+    }
+    /**
+     * Try to acquire permission to make a request through the breaker.
+     *
+     * Has a side effect: if OPEN and cooldown has elapsed, transitions to
+     * HALF-OPEN to allow a probe request.
+     *
+     * - OPEN: Returns false if still in cooldown. If cooldown elapsed, transitions
+     *   to HALF-OPEN and returns true (probe allowed).
+     * - HALF-OPEN or CLOSED: Returns true.
+     */
+    tryAcquire() {
+        if (this.state === "open") {
+            const now = Date.now();
+            if (this.cooldownUntil !== null && now >= this.cooldownUntil) {
+                this.state = "half-open";
+                return true;
+            }
+            return false;
+        }
+        return true;
+    }
+    /** Record a successful request — resets the breaker to CLOSED. */
+    recordSuccess() {
+        this.state = "closed";
+        this.failureCount = 0;
+        this.cooldownUntil = null;
+    }
+    /**
+     * Record a failed request.
+     *
+     * Increments the failure counter. If the trip threshold is reached, opens the
+     * breaker and sets the cooldown timer.
+     *
+     * In HALF-OPEN state, a single failure immediately re-opens the breaker.
+     */
+    recordFailure() {
+        this.failureCount++;
+        if (this.failureCount >= this.tripThreshold) {
+            this.state = "open";
+            this.cooldownUntil = Date.now() + this.cooldownMs;
+        }
+        else if (this.state === "half-open") {
+            // Half-open failure → back to open with new cooldown
+            this.state = "open";
+            this.cooldownUntil = Date.now() + this.cooldownMs;
+        }
+    }
+    /** Get the current breaker state (for testing/diagnostics). */
+    getState() {
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            cooldownUntil: this.cooldownUntil,
+        };
+    }
+}
+/* ── Factory ───────────────────────────────────────────────────── */
+/**
+ * Create an AWX HTTP client with middleware pipeline.
+ *
+ * @param baseUrl  The AAP base URL (e.g., "https://example.com")
+ * @param token    Bearer token (PAT) for Authorization header
+ * @param opts     Optional client configuration
+ */
+export function createClient(baseUrl, token, opts) {
+    const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const timeoutMs = opts?.timeoutMs ?? 30_000;
+    const maxRetries = opts?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const breakerThreshold = opts?.circuitBreakerThreshold ?? 5;
+    const breakerCooldownMs = opts?.circuitBreakerCooldownMs ?? 30_000;
+    // Per-tool circuit breakers
+    const breakers = new Map();
+    /** Get or create a circuit breaker for a tool */
+    function breakerFor(toolName) {
+        let breaker = breakers.get(toolName);
+        if (!breaker) {
+            breaker = new CircuitBreaker(breakerThreshold, breakerCooldownMs);
+            breakers.set(toolName, breaker);
+        }
+        return breaker;
+    }
+    // Shared metrics store instance (use injected store or create new one)
+    const metrics = opts?.metricsStore ?? new MetricsStore();
+    /** Create a spec-compliant 503 Response for when the circuit breaker is open */
+    function circuitOpenResponse() {
+        const body = JSON.stringify({
+            code: "CIRCUIT_OPEN",
+            message: "AWX circuit breaker is open — AAP may be unreachable. Try again in 30s.",
+            retryable: true,
+        });
+        return new Response(body, {
+            status: 503,
+            statusText: "Circuit breaker open",
+            headers: { "Content-Type": "application/json" },
+        });
+    }
+    return {
+        async request(toolName, path, init, abortSignal) {
+            const start = Date.now();
+            // Build full URL
+            const url = `${normalizedBase}${path.startsWith("/") ? path.slice(1) : path}`;
+            // Combine abort signals: ToolContext.abort + timeout
+            const { signal: timeoutSignal, clear: clearTimeout_ } = createTimeoutSignal(timeoutMs);
+            const combinedSignal = abortSignal
+                ? anyAbortSignal([abortSignal, timeoutSignal])
+                : timeoutSignal;
+            // Build headers (plain object for testability — fetch accepts both)
+            const headers = {
+                Accept: "application/json",
+                Authorization: `Bearer ${token}`,
+            };
+            // Merge caller-supplied headers (caller wins on conflicts)
+            if (init?.headers) {
+                const callerHeaders = init.headers instanceof Headers
+                    ? Object.fromEntries(init.headers.entries())
+                    : Array.isArray(init.headers)
+                        ? Object.fromEntries(init.headers)
+                        : init.headers;
+                Object.assign(headers, callerHeaders);
+            }
+            const fetchInit = {
+                method: init?.method ?? "GET",
+                headers,
+                body: init?.body,
+                signal: combinedSignal,
+            };
+            const breaker = breakerFor(toolName);
+            // ── Track outcome for metrics ──
+            let recordedError = false;
+            // ── Middleware pipeline ──
+            try {
+                // ── Retry loop with exponential backoff + circuit breaker ──
+                for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                    // ── Circuit breaker gate (checked before every attempt) ──
+                    if (!breaker.tryAcquire()) {
+                        // Breaker is open — fail fast, no fetch
+                        recordedError = true;
+                        return circuitOpenResponse();
+                    }
+                    try {
+                        const response = await fetch(url, fetchInit);
+                        // 2xx — success, reset breaker, return immediately
+                        if (response.ok) {
+                            breaker.recordSuccess();
+                            return response;
+                        }
+                        // Non-2xx outcome — will record error in finally block
+                        recordedError = true;
+                        // 4xx — client error, do NOT retry, do NOT trip circuit breaker
+                        if (response.status >= 400 && response.status < 500) {
+                            if (response.status === 401) {
+                                metrics.recordTokenExpiry(toolName);
+                            }
+                            return response;
+                        }
+                        // 5xx — server error, record failure, retry if attempts remain
+                        breaker.recordFailure();
+                        if (attempt < maxRetries) {
+                            const delay = calcBackoff(attempt);
+                            await sleepWithAbort(delay, combinedSignal);
+                            continue;
+                        }
+                        // Max retries exhausted — return the last response
+                        return response;
+                    }
+                    catch (err) {
+                        // AbortError — propagate immediately, do NOT retry
+                        if (err instanceof DOMException && err.name === "AbortError") {
+                            throw err;
+                        }
+                        // Network or other error — count as failure, retry if attempts remain
+                        recordedError = true;
+                        breaker.recordFailure();
+                        if (attempt < maxRetries) {
+                            const delay = calcBackoff(attempt);
+                            await sleepWithAbort(delay, combinedSignal);
+                            continue;
+                        }
+                        // Max retries exhausted — throw the error
+                        throw err;
+                    }
+                }
+                // Unreachable — all paths above either return or throw
+                throw new Error("Unreachable: retry loop exhausted");
+            }
+            finally {
+                const duration = Date.now() - start;
+                metrics.recordCall(toolName, duration);
+                if (recordedError) {
+                    metrics.recordError(toolName);
+                }
+                clearTimeout_();
+            }
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/contracts/job-detail.d.ts

@@ -0,0 +1,141 @@
+/**
+ * AWX Job Detail Output Contract — v1.0
+ *
+ * Canonical TypeScript representation of the `awx_job_detail.py` v1.0 output schema.
+ * Every job-related tool MUST return output matching this contract.
+ *
+ * This file provides **both**:
+ * - Zod schemas for runtime validation (e.g., API response parsing)
+ * - Inferred TypeScript types for static type checking
+ *
+ * The contract has been verified against fixture snapshots in `tests/contracts/__snapshots__/`.
+ *
+ * ## Schema Fields
+ *
+ * - **schema_version**: Always "1.0"
+ * - **job**: Core job metadata (id, name, status, timestamps, etc.)
+ * - **related**: Resolved names (not URLs) for related AWX resources
+ * - **host_status_counts**: Count of hosts in each Ansible state — NOT `host_summary`
+ * - **derived**: Boolean flags computed from raw data — NOT `extra_vars_summary`
+ * - **warnings / errors**: String arrays for user-facing messages
+ * - **stdout** (optional): Full job stdout text
+ * - **raw_events** (optional): Raw AWX job events array
+ *
+ * ## Field Naming Convention
+ *
+ * - Use `host_status_counts` — NOT `host_summary`
+ * - Use `derived` — NOT `extra_vars_summary`
+ * - `related` fields are resolved names, not raw URLs
+ * - `job.limit` is the AWX job limit (host pattern), not a pagination value
+ *
+ * ## Snapshot Testing
+ *
+ * Fixture JSON files in `tests/fixtures/` serve as contract snapshots.
+ * When the Python `awx_job_detail.py` v1.0 output contract changes,
+ * regenerate the fixtures (see README.md for instructions) and re-run
+ * tests to verify schema compatibility.
+ *
+ * ## Regeneration
+ *
+ * To regenerate the contract snapshots after fixture changes:
+ * ```bash
+ * python3 scripts/generate-snapshots.py
+ * ```
+ */
+import { z } from "zod";
+export declare const JobCoreSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    status: z.ZodString;
+    failed: z.ZodBoolean;
+    job_type: z.ZodString;
+    playbook: z.ZodString;
+    created: z.ZodString;
+    started: z.ZodNullable<z.ZodString>;
+    finished: z.ZodNullable<z.ZodString>;
+    elapsed: z.ZodNullable<z.ZodNumber>;
+    execution_node: z.ZodString;
+    controller_node: z.ZodString;
+    scm_branch: z.ZodString;
+    verbosity: z.ZodNumber;
+    forks: z.ZodNullable<z.ZodNumber>;
+    limit: z.ZodString;
+}, z.core.$strip>;
+export declare const RelatedSchema: z.ZodObject<{
+    inventory_name: z.ZodString;
+    project_name: z.ZodString;
+    job_template_name: z.ZodString;
+    instance_group_name: z.ZodString;
+    created_by: z.ZodString;
+    credential_names: z.ZodArray<z.ZodString>;
+    label_names: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const HostStatusCountsSchema: z.ZodObject<{
+    ok: z.ZodNumber;
+    failed: z.ZodNumber;
+    skipped: z.ZodNumber;
+    changed: z.ZodNumber;
+    unreachable: z.ZodNumber;
+}, z.core.$strip>;
+export declare const DerivedSchema: z.ZodObject<{
+    is_successful: z.ZodBoolean;
+    is_failed: z.ZodBoolean;
+    has_unreachable_hosts: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const JobDetailOutputSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0">;
+    job: z.ZodObject<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+        status: z.ZodString;
+        failed: z.ZodBoolean;
+        job_type: z.ZodString;
+        playbook: z.ZodString;
+        created: z.ZodString;
+        started: z.ZodNullable<z.ZodString>;
+        finished: z.ZodNullable<z.ZodString>;
+        elapsed: z.ZodNullable<z.ZodNumber>;
+        execution_node: z.ZodString;
+        controller_node: z.ZodString;
+        scm_branch: z.ZodString;
+        verbosity: z.ZodNumber;
+        forks: z.ZodNullable<z.ZodNumber>;
+        limit: z.ZodString;
+    }, z.core.$strip>;
+    related: z.ZodObject<{
+        inventory_name: z.ZodString;
+        project_name: z.ZodString;
+        job_template_name: z.ZodString;
+        instance_group_name: z.ZodString;
+        created_by: z.ZodString;
+        credential_names: z.ZodArray<z.ZodString>;
+        label_names: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    host_status_counts: z.ZodObject<{
+        ok: z.ZodNumber;
+        failed: z.ZodNumber;
+        skipped: z.ZodNumber;
+        changed: z.ZodNumber;
+        unreachable: z.ZodNumber;
+    }, z.core.$strip>;
+    derived: z.ZodObject<{
+        is_successful: z.ZodBoolean;
+        is_failed: z.ZodBoolean;
+        has_unreachable_hosts: z.ZodBoolean;
+    }, z.core.$strip>;
+    warnings: z.ZodArray<z.ZodString>;
+    errors: z.ZodArray<z.ZodString>;
+    stdout: z.ZodOptional<z.ZodString>;
+    raw_events: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Core job metadata fields */
+export type JobCore = z.infer<typeof JobCoreSchema>;
+/** Resolved names for related AWX resources */
+export type Related = z.infer<typeof RelatedSchema>;
+/** Count of hosts in each Ansible state */
+export type HostStatusCounts = z.infer<typeof HostStatusCountsSchema>;
+/** Computed boolean flags */
+export type Derived = z.infer<typeof DerivedSchema>;
+/** Top-level JobDetailOutput contract (v1.0) */
+export type JobDetailOutput = z.infer<typeof JobDetailOutputSchema>;
+//# sourceMappingURL=job-detail.d.ts.map

package/dist/contracts/job-detail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-detail.d.ts","sourceRoot":"","sources":["../../src/contracts/job-detail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;iBAiBxB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;iBAQxB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;iBAMjC,CAAC;AAEH,eAAO,MAAM,aAAa;;;;iBAIxB,CAAC;AAIH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUhC,CAAC;AAIH,+BAA+B;AAC/B,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,+CAA+C;AAC/C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,2CAA2C;AAC3C,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,6BAA6B;AAC7B,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}