@weiyentan/opencode-plugin-awx 0.2.0

package/dist/metrics.js

@@ -0,0 +1,275 @@
+/**
+ * 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;
+ * }
+ * ```
+ */
+// ——— Factory ———
+/** Create a zeroed ToolMetrics object */
+export function createDefaultMetrics() {
+    return {
+        callCount: 0,
+        errorCount: 0,
+        totalLatencyMs: 0,
+        tokenExpiryEvents: 0,
+        psFallbackCount: 0,
+    };
+}
+// ——— MetricsStore ———
+/**
+ * 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 class MetricsStore {
+    /** Per-tool counters, keyed by tool name */
+    counters = new Map();
+    /** File path for persistence (default: `.metrics/metrics.json`) */
+    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) {
+        this.persistPath = persistPath ?? ".metrics/metrics.json";
+    }
+    // ——— Private helpers ———
+    /** Get or create the ToolMetrics entry for a tool name */
+    ensure(toolName) {
+        let metrics = this.counters.get(toolName);
+        if (!metrics) {
+            metrics = createDefaultMetrics();
+            this.counters.set(toolName, metrics);
+        }
+        return metrics;
+    }
+    // ——— Recording methods ———
+    /**
+     * 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, latencyMs) {
+        const m = this.ensure(toolName);
+        m.callCount++;
+        m.totalLatencyMs += latencyMs;
+    }
+    /**
+     * 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) {
+        const m = this.ensure(toolName);
+        m.errorCount++;
+    }
+    /**
+     * 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) {
+        const m = this.ensure(toolName);
+        m.tokenExpiryEvents++;
+    }
+    /**
+     * 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) {
+        const m = this.ensure(toolName);
+        m.psFallbackCount++;
+    }
+    // ——— Read methods ———
+    /**
+     * Get metrics for a specific tool.
+     * Returns a default zeroed object if the tool has never been recorded.
+     */
+    getMetrics(toolName) {
+        const m = this.counters.get(toolName);
+        if (!m)
+            return createDefaultMetrics();
+        // Return a shallow copy so callers can't mutate the store
+        return { ...m };
+    }
+    /**
+     * Get all tracked tools' metrics as a plain object.
+     * Returns deep copies — mutations do not affect the store.
+     */
+    getAllMetrics() {
+        const result = {};
+        for (const [name, metrics] of this.counters) {
+            result[name] = { ...metrics };
+        }
+        return result;
+    }
+    // ——— Persistence ———
+    /**
+     * 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.
+     */
+    async persist() {
+        // Dynamic imports keep the module dependency-free at the type level
+        // and avoid bundling fs/promises for environments that don't need it.
+        const fs = await import("fs/promises");
+        const path = await import("path");
+        const dir = path.dirname(this.persistPath);
+        await fs.mkdir(dir, { recursive: true });
+        const data = {
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            tools: Object.fromEntries(this.counters),
+        };
+        const tmpPath = this.persistPath + ".tmp";
+        await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+        await fs.rename(tmpPath, this.persistPath);
+    }
+    /**
+     * 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.
+     */
+    async load() {
+        const fs = await import("fs/promises");
+        let raw;
+        try {
+            raw = await fs.readFile(this.persistPath, "utf-8");
+        }
+        catch (err) {
+            if (typeof err === "object" &&
+                err !== null &&
+                "code" in err &&
+                err.code === "ENOENT") {
+                // File doesn't exist — fresh start, keep in-memory counters
+                return;
+            }
+            throw err;
+        }
+        const data = JSON.parse(raw);
+        if (data.tools) {
+            for (const [name, saved] of Object.entries(data.tools)) {
+                const existing = this.ensure(name);
+                // Merge: take the maximum of each counter (never decrease)
+                existing.callCount = Math.max(existing.callCount, saved.callCount ?? 0);
+                existing.errorCount = Math.max(existing.errorCount, saved.errorCount ?? 0);
+                existing.totalLatencyMs = Math.max(existing.totalLatencyMs, saved.totalLatencyMs ?? 0);
+                existing.tokenExpiryEvents = Math.max(existing.tokenExpiryEvents, saved.tokenExpiryEvents ?? 0);
+                existing.psFallbackCount = Math.max(existing.psFallbackCount, saved.psFallbackCount ?? 0);
+            }
+        }
+    }
+    // ——— Lifecycle ———
+    /**
+     * Reset all counters to zero.
+     * Useful for testing or for clearing metrics between sessions.
+     */
+    reset() {
+        this.counters.clear();
+    }
+}
+// ——— Lifecycle helper ———
+/**
+ * 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 function setupMetricsPersistence(store, intervalMs = 30_000, onError) {
+    let persistQueue = Promise.resolve();
+    function enqueuePersist() {
+        persistQueue = persistQueue
+            .then(() => store.persist())
+            .catch((err) => {
+            // persist failures (e.g., permission denied) should not crash
+            // the interval; surface the error via the optional callback.
+            onError?.(err);
+        });
+        return persistQueue;
+    }
+    const intervalId = setInterval(() => {
+        void enqueuePersist();
+    }, intervalMs);
+    return {
+        async clear() {
+            clearInterval(intervalId);
+            await enqueuePersist();
+        },
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAyBH,kBAAkB;AAElB,yCAAyC;AACzC,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC;QACb,cAAc,EAAE,CAAC;QACjB,iBAAiB,EAAE,CAAC;QACpB,eAAe,EAAE,CAAC;KACnB,CAAC;AACJ,CAAC;AAED,uBAAuB;AAEvB;;;;;;;;;;GAUG;AACH,MAAM,OAAO,YAAY;IACvB,4CAA4C;IACpC,QAAQ,GAA6B,IAAI,GAAG,EAAE,CAAC;IAEvD,mEAAmE;IAC3D,WAAW,CAAS;IAE5B;;;OAGG;IACH,YAAY,WAAoB;QAC9B,IAAI,CAAC,WAAW,GAAG,WAAW,IAAI,uBAAuB,CAAC;IAC5D,CAAC;IAED,0BAA0B;IAE1B,0DAA0D;IAClD,MAAM,CAAC,QAAgB;QAC7B,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,oBAAoB,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,4BAA4B;IAE5B;;;;;;;OAOG;IACH,UAAU,CAAC,QAAgB,EAAE,SAAiB;QAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC,CAAC,SAAS,EAAE,CAAC;QACd,CAAC,CAAC,cAAc,IAAI,SAAS,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,QAAgB;QAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC,CAAC,UAAU,EAAE,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,QAAgB;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACH,gBAAgB,CAAC,QAAgB;QAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC,CAAC,eAAe,EAAE,CAAC;IACtB,CAAC;IAED,uBAAuB;IAEvB;;;OAGG;IACH,UAAU,CAAC,QAAgB;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,CAAC;YAAE,OAAO,oBAAoB,EAAE,CAAC;QACtC,0DAA0D;QAC1D,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,MAAM,MAAM,GAAgC,EAAE,CAAC;QAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;QAChC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,sBAAsB;IAEtB;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO;QACX,oEAAoE;QACpE,sEAAsE;QACtE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QAElC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3C,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEzC,MAAM,IAAI,GAAqB;YAC7B,OAAO,EAAE,CAAC;YACV,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC;SACzC,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;QAC1C,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,MAAM,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QAEvC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IACE,OAAO,GAAG,KAAK,QAAQ;gBACvB,GAAG,KAAK,IAAI;gBACZ,MAAM,IAAI,GAAG;gBACZ,GAA+B,CAAC,IAAI,KAAK,QAAQ,EAClD,CAAC;gBACD,4DAA4D;gBAC5D,OAAO;YACT,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;QAEjD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACnC,2DAA2D;gBAC3D,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;gBACxE,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;gBAC3E,QAAQ,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC;gBACvF,QAAQ,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,IAAI,CAAC,CAAC,CAAC;gBAChG,QAAQ,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;IACH,CAAC;IAED,oBAAoB;IAEpB;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AAED,2BAA2B;AAE3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAmB,EACnB,aAAqB,MAAM,EAC3B,OAAgC;IAEhC,IAAI,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAErC,SAAS,cAAc;QACrB,YAAY,GAAG,YAAY;aACxB,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;aAC3B,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACb,8DAA8D;YAC9D,6DAA6D;YAC7D,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC,CAAC,CAAC;QACL,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;QAClC,KAAK,cAAc,EAAE,CAAC;IACxB,CAAC,EAAE,UAAU,CAAC,CAAC;IAEf,OAAO;QACL,KAAK,CAAC,KAAK;YACT,aAAa,CAAC,UAAU,CAAC,CAAC;YAC1B,MAAM,cAAc,EAAE,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/transforms.d.ts

@@ -0,0 +1,52 @@
+/**
+ * transforms.ts — Pure functions for transforming job extra variables
+ * before they are sent to AWX.
+ *
+ * All functions are pure: no I/O, no side effects, no network calls.
+ */
+/**
+ * Converts an SSH Git URL to its HTTPS equivalent.
+ *
+ * Pattern matched: `git@<host>:<path>[.git]` → `https://<host>/<path>`
+ *
+ * - Already-HTTPS URLs are returned unchanged.
+ * - Non-SSH URLs (HTTP, file://, plain strings) are returned unchanged.
+ * - Trailing `.git` suffix is stripped.
+ * - Null or undefined input returns an empty string.
+ *
+ * @param url - The SCM URL to normalize (may be null/undefined)
+ * @returns The HTTPS-normalized URL, or the original if not an SSH URL
+ */
+export declare function normalizeScmUrl(url: string | null | undefined): string;
+/**
+ * Extracts a branch/tag name from a Git ref string.
+ *
+ * Supported ref prefixes:
+ * - `refs/heads/<name>` → `<name>`
+ * - `refs/tags/<name>`  → `<name>`
+ *
+ * Raw branch names (no `refs/` prefix) are returned unchanged.
+ * Unrecognized ref prefixes (e.g., `refs/remotes/...`) are returned as-is.
+ * Null or undefined input returns an empty string.
+ *
+ * @param ref - The Git ref string (e.g., "refs/heads/main", "refs/tags/v1.0", "main")
+ * @returns The extracted branch/tag name
+ */
+export declare function inferGitBranch(ref: string | null | undefined): string;
+/**
+ * Validates that all required keys are present and have non-empty values
+ * in the provided extra vars.
+ *
+ * Returns a list of missing var names (in the order they appear in `required`).
+ * If `vars` is null or undefined, all required vars are reported as missing.
+ *
+ * A key is considered **missing** if:
+ * - The key does not exist on the object, OR
+ * - The value is `null`, `undefined`, or an empty/whitespace-only string.
+ *
+ * @param vars - The extra vars object to validate (may be null/undefined)
+ * @param required - The list of required variable names
+ * @returns Array of missing variable names (empty if all are present and non-empty)
+ */
+export declare function validateRequiredVars(vars: Record<string, unknown>, required: string[]): string[];
+//# sourceMappingURL=transforms.d.ts.map

package/dist/transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../src/transforms.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CA2BtE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAiBrE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,EAAE,CAgBV"}

package/dist/transforms.js

@@ -0,0 +1,108 @@
+/**
+ * transforms.ts — Pure functions for transforming job extra variables
+ * before they are sent to AWX.
+ *
+ * All functions are pure: no I/O, no side effects, no network calls.
+ */
+// ---------------------------------------------------------------------------
+// normalizeScmUrl
+// ---------------------------------------------------------------------------
+/**
+ * Converts an SSH Git URL to its HTTPS equivalent.
+ *
+ * Pattern matched: `git@<host>:<path>[.git]` → `https://<host>/<path>`
+ *
+ * - Already-HTTPS URLs are returned unchanged.
+ * - Non-SSH URLs (HTTP, file://, plain strings) are returned unchanged.
+ * - Trailing `.git` suffix is stripped.
+ * - Null or undefined input returns an empty string.
+ *
+ * @param url - The SCM URL to normalize (may be null/undefined)
+ * @returns The HTTPS-normalized URL, or the original if not an SSH URL
+ */
+export function normalizeScmUrl(url) {
+    if (url == null || url === "") {
+        return "";
+    }
+    // If already HTTPS, passthrough
+    if (url.startsWith("https://") || url.startsWith("http://")) {
+        return url;
+    }
+    // Match SSH format: git@<host>:<path>
+    const sshMatch = url.match(/^git@([^:]+):(.+)$/);
+    if (!sshMatch) {
+        // Not an SSH URL — return unchanged
+        return url;
+    }
+    const [, host, path] = sshMatch;
+    if (!host || !path) {
+        return url;
+    }
+    // Strip trailing .git if present
+    const cleanPath = path.endsWith(".git") ? path.slice(0, -4) : path;
+    return `https://${host}/${cleanPath}`;
+}
+// ---------------------------------------------------------------------------
+// inferGitBranch
+// ---------------------------------------------------------------------------
+/**
+ * Extracts a branch/tag name from a Git ref string.
+ *
+ * Supported ref prefixes:
+ * - `refs/heads/<name>` → `<name>`
+ * - `refs/tags/<name>`  → `<name>`
+ *
+ * Raw branch names (no `refs/` prefix) are returned unchanged.
+ * Unrecognized ref prefixes (e.g., `refs/remotes/...`) are returned as-is.
+ * Null or undefined input returns an empty string.
+ *
+ * @param ref - The Git ref string (e.g., "refs/heads/main", "refs/tags/v1.0", "main")
+ * @returns The extracted branch/tag name
+ */
+export function inferGitBranch(ref) {
+    if (ref == null || ref === "") {
+        return "";
+    }
+    // refs/heads/<branch>
+    if (ref.startsWith("refs/heads/")) {
+        return ref.slice("refs/heads/".length);
+    }
+    // refs/tags/<tag>
+    if (ref.startsWith("refs/tags/")) {
+        return ref.slice("refs/tags/".length);
+    }
+    // Raw name or unrecognized prefix — return as-is
+    return ref;
+}
+// ---------------------------------------------------------------------------
+// validateRequiredVars
+// ---------------------------------------------------------------------------
+/**
+ * Validates that all required keys are present and have non-empty values
+ * in the provided extra vars.
+ *
+ * Returns a list of missing var names (in the order they appear in `required`).
+ * If `vars` is null or undefined, all required vars are reported as missing.
+ *
+ * A key is considered **missing** if:
+ * - The key does not exist on the object, OR
+ * - The value is `null`, `undefined`, or an empty/whitespace-only string.
+ *
+ * @param vars - The extra vars object to validate (may be null/undefined)
+ * @param required - The list of required variable names
+ * @returns Array of missing variable names (empty if all are present and non-empty)
+ */
+export function validateRequiredVars(vars, required) {
+    const missing = [];
+    for (const name of required) {
+        const value = vars?.[name];
+        if (vars == null ||
+            value === null ||
+            value === undefined ||
+            (typeof value === "string" && value.trim() === "")) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+//# sourceMappingURL=transforms.js.map

package/dist/transforms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.js","sourceRoot":"","sources":["../src/transforms.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,gCAAgC;IAChC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5D,OAAO,GAAG,CAAC;IACb,CAAC;IAED,sCAAsC;IACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACjD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,oCAAoC;QACpC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAC;IAEhC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iCAAiC;IACjC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEnE,OAAO,WAAW,IAAI,IAAI,SAAS,EAAE,CAAC;AACxC,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,GAA8B;IAC3D,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,sBAAsB;IACtB,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,kBAAkB;IAClB,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,iDAAiD;IACjD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAA6B,EAC7B,QAAkB;IAElB,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;QAC3B,IACE,IAAI,IAAI,IAAI;YACZ,KAAK,KAAK,IAAI;YACd,KAAK,KAAK,SAAS;YACnB,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAClD,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@weiyentan/opencode-plugin-awx",
+  "version": "0.2.0",
+  "private": false,
+  "description": "OpenCode plugin for AWX / Ansible Automation Platform — native tool access to job templates, projects, and job lifecycle operations.",
+  "type": "module",
+  "files": ["dist/**", "README.md", "LICENSE"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.17.8",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.17.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "awx",
+    "ansible",
+    "aap",
+    "automation-platform"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/weiyentan/opencode-plugins",
+    "directory": "packages/awx"
+  }
+}