@weiyentan/opencode-plugin-awx 0.2.0

package/dist/list-projects.js

@@ -0,0 +1,84 @@
+/* ── Timeout budget ─────────────────────────────────────────────── */
+/**
+ * Calculate per-page timeout budget.
+ *
+ * Formula: totalTimeout / (maxPages + 1)
+ * The +1 accounts for any overhead/rounding and ensures we never
+ * exceed the total tool timeout even if all pages are fetched.
+ *
+ * @param totalTimeout  Total tool timeout in milliseconds
+ * @param maxPages      Maximum number of pages to fetch
+ * @returns Per-page budget in milliseconds (rounded down)
+ */
+export function calcPageBudget(totalTimeout, maxPages) {
+    return Math.floor(totalTimeout / (maxPages + 1));
+}
+/* ── Pagination logic ───────────────────────────────────────────── */
+/**
+ * Fetch paginated projects from the AWX API, consolidate results,
+ * and return them sorted by name.
+ *
+ * @param client   The AWX HTTP client
+ * @param options  Pagination and timeout options
+ * @returns Consolidated, sorted list of projects
+ */
+export async function listProjects(client, options) {
+    const maxPages = options?.maxPages ?? 5;
+    const pageSize = options?.pageSize ?? 50;
+    const totalTimeout = options?.timeout ?? 30_000;
+    const toolAbortSignal = options?.abortSignal;
+    const pageBudget = calcPageBudget(totalTimeout, maxPages);
+    const allProjects = [];
+    let page = 1;
+    let hasMore = true;
+    while (hasMore && page <= maxPages) {
+        // Check if tool has been aborted
+        if (toolAbortSignal?.aborted) {
+            throw toolAbortSignal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+        // Create per-page timeout signal
+        const pageController = new AbortController();
+        const pageTimer = setTimeout(() => pageController.abort(new DOMException(`Page ${page} timed out after ${pageBudget}ms`, "TimeoutError")), pageBudget);
+        // Wire tool abort signal to page controller
+        const abortHandler = () => {
+            clearTimeout(pageTimer);
+            pageController.abort(toolAbortSignal.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        if (toolAbortSignal && !toolAbortSignal.aborted) {
+            toolAbortSignal.addEventListener("abort", abortHandler, { once: true });
+        }
+        try {
+            // Build request path with pagination parameters
+            const path = `/api/v2/projects/?page=${page}&page_size=${pageSize}`;
+            const response = await client.request("awx-list-projects", path, { headers: { "Content-Type": "application/json" } }, pageController.signal);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch projects: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            allProjects.push(...data.results);
+            if (!data.next) {
+                hasMore = false;
+            }
+            page++;
+        }
+        finally {
+            clearTimeout(pageTimer);
+            if (toolAbortSignal && !toolAbortSignal.aborted) {
+                toolAbortSignal.removeEventListener("abort", abortHandler);
+            }
+            pageController.abort(); // prevent any lingering signal listeners
+        }
+    }
+    // Sort consolidated results by name (case-insensitive alphanumeric)
+    allProjects.sort((a, b) => a.name.localeCompare(b.name));
+    const output = {
+        count: allProjects.length,
+        results: allProjects,
+    };
+    // If we exhausted the page cap but there are more pages, warn
+    if (page > maxPages && hasMore) {
+        output.warning = "More items exist. Increase max-pages or use a filter.";
+    }
+    return output;
+}
+//# sourceMappingURL=list-projects.js.map

package/dist/list-projects.js.map

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

package/dist/list-templates.d.ts

@@ -0,0 +1,60 @@
+/**
+ * list-templates.ts — AWX job template listing with pagination consolidation
+ *
+ * Fetches job templates from the AWX /api/v2/job_templates/ endpoint,
+ * iterates through pages up to a configurable cap, sorts results by name,
+ * and enforces a per-page timeout budget.
+ *
+ * ## Timeout Budget
+ *
+ * Per-page timeout = toolTimeoutMs / (maxPages + 1).
+ * This ensures that even if every page times out sequentially, we never
+ * exceed the tool-level timeout (the +1 accounts for the tool overhead).
+ *
+ * ## Page Cap
+ *
+ * When maxPages > 0 and the cap is reached with more pages available,
+ * the output includes a warning field. The caller can detect truncation
+ * by checking for the presence of `warning`.
+ */
+import type { AwxClient } from "./client.js";
+/** A simplified template result returned to the caller */
+export interface TemplateResult {
+    id: number;
+    name: string;
+    description: string;
+}
+/** Output of the list-templates operation */
+export interface ListTemplatesOutput {
+    count: number;
+    results: TemplateResult[];
+    warning?: string;
+}
+/** Options for listTemplates */
+export interface ListTemplatesOptions {
+    /** Number of items per page (default: 50) */
+    pageSize?: number;
+    /**
+     * Maximum pages to fetch.
+     * 0 = no cap (fetch all pages).
+     * Default: 5 (5 pages × 50 items = 250 max).
+     */
+    maxPages?: number;
+}
+/**
+ * List AWX job templates with pagination consolidation.
+ *
+ * Fetches templates from `/api/v2/job_templates/`, iterating through
+ * pages up to the configured `maxPages` cap. Each page request gets a
+ * timeout budget of `toolTimeoutMs / (maxPages + 1)`.
+ *
+ * Results are sorted by name (alphanumeric, case-insensitive) before returning.
+ *
+ * @param client        The AWX HTTP client
+ * @param toolTimeoutMs Tool-level timeout in ms (used for per-page budget)
+ * @param options       Optional: pageSize, maxPages
+ * @param abortSignal   Optional tool context abort signal for cancellation
+ * @returns Consolidated, sorted template list with count and optional warning
+ */
+export declare function listTemplates(client: AwxClient, toolTimeoutMs: number, options?: ListTemplatesOptions, abortSignal?: AbortSignal): Promise<ListTemplatesOutput>;
+//# sourceMappingURL=list-templates.d.ts.map

package/dist/list-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-templates.d.ts","sourceRoot":"","sources":["../src/list-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAkFD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,oBAAoB,EAC9B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAiE9B"}

package/dist/list-templates.js

@@ -0,0 +1,120 @@
+// ── Helpers ───────────────────────────────────────────────────────
+/**
+ * Combine multiple AbortSignals into one — aborts if ANY source aborts.
+ * Uses native AbortSignal.any() on Node 20+, falls back to manual wiring.
+ */
+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;
+}
+/**
+ * Create an AbortSignal that fires after `ms` milliseconds.
+ * Uses setTimeout + AbortController for Node 18+ compatibility.
+ */
+function createTimeoutSignal(ms) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new DOMException("Page timeout.", "TimeoutError")), ms);
+    return {
+        signal: controller.signal,
+        clear: () => clearTimeout(timer),
+    };
+}
+/**
+ * Extract path + query string from a full AWX API URL.
+ * AWX pagination returns absolute URLs in `next` — we need just the path.
+ */
+function extractPath(fullUrl) {
+    try {
+        const url = new URL(fullUrl);
+        return url.pathname + (url.search || "");
+    }
+    catch {
+        // If it's already just a path, return as-is
+        return fullUrl;
+    }
+}
+/** Map a raw AWX template item to the simplified result shape */
+function mapTemplate(item) {
+    return {
+        id: item.id,
+        name: item.name,
+        description: item.description ?? "",
+    };
+}
+// ── Core Logic ────────────────────────────────────────────────────
+/**
+ * List AWX job templates with pagination consolidation.
+ *
+ * Fetches templates from `/api/v2/job_templates/`, iterating through
+ * pages up to the configured `maxPages` cap. Each page request gets a
+ * timeout budget of `toolTimeoutMs / (maxPages + 1)`.
+ *
+ * Results are sorted by name (alphanumeric, case-insensitive) before returning.
+ *
+ * @param client        The AWX HTTP client
+ * @param toolTimeoutMs Tool-level timeout in ms (used for per-page budget)
+ * @param options       Optional: pageSize, maxPages
+ * @param abortSignal   Optional tool context abort signal for cancellation
+ * @returns Consolidated, sorted template list with count and optional warning
+ */
+export async function listTemplates(client, toolTimeoutMs, options, abortSignal) {
+    const pageSize = options?.pageSize ?? 50;
+    const maxPages = options?.maxPages ?? 5;
+    // Per-page timeout budget: divide tool timeout by (maxPages + 1).
+    // The +1 provides a safety margin for tool overhead after the last page.
+    const effectiveMaxPages = Math.max(1, maxPages);
+    const perPageBudget = Math.floor(toolTimeoutMs / (effectiveMaxPages + 1));
+    const allResults = [];
+    let nextPage = null;
+    let pagesFetched = 0;
+    do {
+        pagesFetched++;
+        // Build URL for current page
+        const path = nextPage
+            ? extractPath(nextPage)
+            : `/api/v2/job_templates/?page_size=${pageSize}`;
+        // Fetch this page with per-page timeout
+        const { signal: pageSignal, clear: clearTimeout_ } = createTimeoutSignal(perPageBudget);
+        const combinedSignal = abortSignal
+            ? anyAbortSignal([abortSignal, pageSignal])
+            : pageSignal;
+        try {
+            const response = await client.request("awx-list-templates", path, undefined, combinedSignal);
+            if (!response.ok) {
+                throw new Error(`AWX API error: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            allResults.push(...data.results.map(mapTemplate));
+            nextPage = data.next;
+        }
+        finally {
+            clearTimeout_();
+        }
+        // Stop when no more pages OR we've hit the cap.
+        // maxPages <= 0 means "no cap" (fetch all).
+    } while (nextPage !== null && (maxPages <= 0 || pagesFetched < maxPages));
+    // Sort consolidated results by name (alphanumeric, case-insensitive)
+    allResults.sort((a, b) => a.name.localeCompare(b.name));
+    const output = {
+        count: allResults.length,
+        results: allResults,
+    };
+    // If there are more pages but we hit the cap, emit a warning
+    if (nextPage !== null && maxPages > 0 && pagesFetched >= maxPages) {
+        output.warning = `Page cap of ${maxPages} page${maxPages !== 1 ? "s" : ""} reached. Some results may be omitted.`;
+    }
+    return output;
+}
+//# sourceMappingURL=list-templates.js.map

package/dist/list-templates.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,174 @@
+/**
+ * metrics.ts — Per-tool counters with file-backed durability
+ *
+ * Provides structured metrics for operational visibility and phase-gating:
+ *   - Per-tool call count
+ *   - Per-tool error count
+ *   - Per-tool latency accumulation (ms)
+ *   - Token expiry events (401 detection)
+ *   - PowerShell fallback count (for deprecation monitoring)
+ *
+ * ## Durability Model
+ *
+ * Counters are file-backed so they survive plugin reloads. This is required
+ * for the Phase 2→3 gate which demands 14 consecutive days of zero PowerShell
+ * AWX calls.
+ *
+ * **File format:** JSON at a configurable path (default: `.metrics/metrics.json`).
+ * **Atomic writes:** Data is written to a `.tmp` file first, then renamed over
+ *   the target — preventing corruption on partial writes.
+ * **Merge-on-load:** When `load()` is called, disk values are merged with
+ *   in-memory counters using `Math.max()` — counters never decrease.
+ * **Missing file:** Treated as a fresh start (no error thrown).
+ *
+ * ## Integration Point
+ *
+ * Metrics hook into the client module at pipeline boundaries — not inside
+ * individual middleware. The `client.ts` request function calls `recordCall`,
+ * `recordError`, and `recordTokenExpiry` at the top level.
+ *
+ * ```typescript
+ * // In client.ts (pipeline boundary):
+ * const start = Date.now();
+ * try {
+ *   const response = await fetch(...);
+ *   metrics.recordCall(toolName, Date.now() - start);
+ *   if (response.status === 401) metrics.recordTokenExpiry(toolName);
+ *   return response;
+ * } catch (err) {
+ *   metrics.recordError(toolName);
+ *   throw err;
+ * }
+ * ```
+ */
+/** Per-tool metrics counters */
+export interface ToolMetrics {
+    /** Total number of tool calls (successful or not) */
+    callCount: number;
+    /** Total number of errors (any error, including HTTP and network errors) */
+    errorCount: number;
+    /** Accumulated latency in milliseconds (sum of all call latencies) */
+    totalLatencyMs: number;
+    /** Number of 401 Unauthorized responses (token expiry detection) */
+    tokenExpiryEvents: number;
+    /** Number of times the plugin fell back to PowerShell for this tool */
+    psFallbackCount: number;
+}
+/** Create a zeroed ToolMetrics object */
+export declare function createDefaultMetrics(): ToolMetrics;
+/**
+ * Thread-safe (in-memory) metrics store with file-backed durability.
+ *
+ * All recording methods are synchronous and fast — they mutate an in-memory
+ * Map. Persistence is explicit (call `persist()`) so the caller controls when
+ * to flush to disk.
+ *
+ * The durability model is **additive-merge**: on `load()`, existing in-memory
+ * counters are never decreased. This prevents race conditions where an
+ * in-memory increment during a concurrent persist window would be lost.
+ */
+export declare class MetricsStore {
+    /** Per-tool counters, keyed by tool name */
+    private counters;
+    /** File path for persistence (default: `.metrics/metrics.json`) */
+    private persistPath;
+    /**
+     * @param persistPath - Absolute or relative path to the metrics JSON file.
+     *   Defaults to `.metrics/metrics.json` relative to the current working directory.
+     */
+    constructor(persistPath?: string);
+    /** Get or create the ToolMetrics entry for a tool name */
+    private ensure;
+    /**
+     * Record a tool call with its latency.
+     * Called by the client at the pipeline boundary after a successful (or
+     * error-handled) fetch completes.
+     *
+     * @param toolName - The registered tool name (e.g., "list-templates", "launch-job")
+     * @param latencyMs - Round-trip latency in milliseconds
+     */
+    recordCall(toolName: string, latencyMs: number): void;
+    /**
+     * Record an error for a tool.
+     * Called by the client when a fetch request fails (any error: 4xx, 5xx,
+     * network error, timeout, abort).
+     */
+    recordError(toolName: string): void;
+    /**
+     * Record a token expiry event (HTTP 401).
+     * Called by the client when a request returns 401 Unauthorized, indicating
+     * the bearer token has expired or been revoked.
+     */
+    recordTokenExpiry(toolName: string): void;
+    /**
+     * Record a PowerShell fallback for a tool.
+     * Called when the plugin tool cannot complete the operation and falls back
+     * to the legacy PowerShell script. This counter is tracked per-tool for
+     * granular deprecation monitoring (Phase 2→3 gate requires zero PS calls
+     * across all tools for 14 consecutive days).
+     */
+    recordPsFallback(toolName: string): void;
+    /**
+     * Get metrics for a specific tool.
+     * Returns a default zeroed object if the tool has never been recorded.
+     */
+    getMetrics(toolName: string): ToolMetrics;
+    /**
+     * Get all tracked tools' metrics as a plain object.
+     * Returns deep copies — mutations do not affect the store.
+     */
+    getAllMetrics(): Record<string, ToolMetrics>;
+    /**
+     * Persist current metrics to disk using an atomic write strategy.
+     *
+     * **Atomicity**: Data is written to a `.tmp` file first, then renamed
+     * over the target. If the process crashes during the write, the original
+     * file remains intact.
+     *
+     * **Directory creation**: The parent directory is created recursively if
+     * it doesn't exist.
+     */
+    persist(): Promise<void>;
+    /**
+     * Load metrics from disk and merge with in-memory counters.
+     *
+     * **Merge strategy (additive)**: For each tool, each counter is set to
+     * `Math.max(inMemory, onDisk)`. This ensures:
+     *   - Counters never decrease (no lost increments).
+     *   - Concurrent increments during a load window are preserved.
+     *
+     * **Missing file**: Treated as a fresh start (no error). In-memory
+     * counters are left unchanged — a subsequent `persist()` will create
+     * the file.
+     */
+    load(): Promise<void>;
+    /**
+     * Reset all counters to zero.
+     * Useful for testing or for clearing metrics between sessions.
+     */
+    reset(): void;
+}
+/**
+ * Set up periodic persistence for a MetricsStore.
+ *
+ * Starts a `setInterval` that calls `store.persist()` at the given interval.
+ * Returns a `clear()` function that stops the interval and does a final
+ * persist to ensure in-memory counters are flushed to disk.
+ *
+ * This is the integration point for the plugin lifecycle:
+ * 1. Plugin's `server()` creates a `MetricsStore` and calls `store.load()`.
+ * 2. Plugin's `server()` calls this helper to start periodic persistence.
+ * 3. Plugin's `dispose()` hook calls `clear()` to stop the interval and
+ *    perform a final persist.
+ *
+ * @param store      - The MetricsStore to persist periodically
+ * @param intervalMs - Interval in milliseconds (default: 30_000 = 30s)
+ * @param onError    - Optional callback invoked when a persist attempt fails.
+ *                     Receives the error object so the caller can surface
+ *                     failures (e.g., via app logging) without crashing the
+ *                     interval.
+ */
+export declare function setupMetricsPersistence(store: MetricsStore, intervalMs?: number, onError?: (err: unknown) => void): {
+    clear: () => Promise<void>;
+};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,gCAAgC;AAChC,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;CACzB;AAWD,yCAAyC;AACzC,wBAAgB,oBAAoB,IAAI,WAAW,CAQlD;AAID;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAuC;IAEvD,mEAAmE;IACnE,OAAO,CAAC,WAAW,CAAS;IAE5B;;;OAGG;gBACS,WAAW,CAAC,EAAE,MAAM;IAMhC,0DAA0D;IAC1D,OAAO,CAAC,MAAM;IAWd;;;;;;;OAOG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAMrD;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKnC;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKzC;;;;;;OAMG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOxC;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAOzC;;;OAGG;IACH,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;IAU5C;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB9B;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B;;;OAGG;IACH,KAAK,IAAI,IAAI;CAGd;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,UAAU,GAAE,MAAe,EAC3B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC/B;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAwBhC"}