@weiyentan/opencode-plugin-awx 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weiyentan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+# AWX Plugin (`@weiyentan/opencode-plugin-awx`)
+
+OpenCode server plugin for [AWX](https://github.com/ansible/awx) / Ansible Automation Platform (AAP). Provides native tool access to job templates, projects, and job lifecycle operations.
+
+## Status
+
+✅ **Phase 0 — Repository Scaffolding** (complete)  
+✅ **Phase 1 — Client Infrastructure** (complete)  
+✅ **Phase 2 — Tool Implementation** (complete)
+
+The AWX plugin delivers these modules:
+
+| Module | File | Purpose |
+|--------|------|---------|
+| **Plugin entry** | `src/index.ts` | Registers all AWX tools (awx-list-templates, awx-list-projects, awx-launch-job, awx-job-status, awx-wait-job, awx-get-job-events, awx-sync-project) + hello-world scaffold; wires HTTP client, metrics lifecycle, and dispose hook |
+| **Auth hook** | `src/auth.ts` | Bearer token / PAT authentication via OpenCode's `type: "api"` auth hook with init-time validation |
+| **Output contract** | `src/contracts/job-detail.ts` | Zod schemas and TypeScript types (`JobDetailOutput`) matching `awx_job_detail.py` v1.0 |
+| **Transforms** | `src/transforms.ts` | Pure functions: SSH→HTTPS URL conversion, git branch inference, required-var validation |
+| **Client middleware** | `src/client.ts` | HTTP middleware pipeline: circuit breaker, retry/backoff, timeout via native `fetch` |
+| **Metrics** | `src/metrics.ts` | Per-tool counters with file-backed durability for operational visibility |
+| **Node shim** | `src/node-shim.d.ts` | Minimal Node.js built-in declarations (avoids `@types/node` dependency) |
+| **Snapshot generator** | `scripts/generate-snapshots.py` | Python script that regenerates contract snapshots from fixture data |
+
+Tool implementation (Phase 2) is complete — all 7 AWX tools are implemented and tested. See the [issue tracker](https://github.com/weiyentan/opencode-plugins/issues) for upcoming enhancements.
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0 (Node 18 compatibility is handled transparently — the client middleware includes `anyAbortSignal()` and `createTimeoutSignal()` fallbacks)
+- **npm** >= 9.0.0 (ships with Node.js 18)
+- TypeScript knowledge for plugin development
+- Access to an AAP instance for integration testing (optional — unit tests run offline)
+
+## Setup
+
+```bash
+# From the monorepo root:
+npm install
+
+# Or from this package directly:
+cd packages/awx
+npm install
+```
+
+This package is consumed by the OpenCode plugin server as a dependency — no standalone runtime is needed.
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile TypeScript to `dist/` (`tsc`) |
+| `npm test` | Run the Vitest test suite (`vitest run`) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run lint` | Type-check without emitting (`tsc --noEmit`) |
+| `npm run typecheck` | Alias for `lint` — strict type checking |
+
+## Testing
+
+```bash
+# Unit tests (no AAP instance required)
+npm test
+```
+
+Tests follow TDD (test-driven development) with [Vitest](https://vitest.dev) and verify behavior through the public plugin interface.
+
+### Running Integration Tests
+
+Integration tests in `tests/integration/` exercise the plugin's tools against a **live AAP instance** through the plugin's own tool registration mechanism.
+
+#### Read-Only Tools
+
+The suite `tests/integration/read-only.test.ts` covers `awx-list-templates` and `awx-list-projects`.
+
+#### Job Lifecycle Tools
+
+The suite `tests/integration/job-lifecycle.test.ts` covers the full AWX job lifecycle:
+
+- `awx-launch-job` → launches a job template
+- `awx-job-status` → fetches structured job detail (v1.0 output contract)
+- `awx-wait-job` → non-blocking status check (no polling)
+- `awx-get-job-events` → retrieves job events
+
+#### Prerequisites
+
+| Env Var | Default | Required | Description |
+|---------|---------|----------|-------------|
+| `AWX_TOKEN` | — | **Yes** | Valid AAP Personal Access Token (PAT) |
+| `AAP_BASE_URL` | `https://example.com` | No | Base URL of the AAP instance |
+| `JOB_TEMPLATE_ID` | `10` | No | Non-production AWX job template ID to launch |
+| `EXTRA_VARS_INVENTORY` | `"test"` | No | Inventory name for extra_vars |
+| `EXTRA_VARS_SCM_URL` | `"https://github.com/example/repo.git"` | No | SCM URL for extra_vars |
+| `EXTRA_VARS_SCM_BRANCH` | `"main"` | No | SCM branch for extra_vars |
+
+> **Important:** Use a non-production job template. The launch tool starts a real job on AAP. The plugin's transforms pipeline requires `inventory`, `scm_url`, and `scm_branch` in extra_vars — configure them via env vars to match your template's expectations.
+
+#### Run Command
+
+```bash
+# From packages/awx/
+export AWX_TOKEN=your_pat_token_here
+npx vitest run tests/integration/
+
+# Run a specific suite:
+npx vitest run tests/integration/read-only.test.ts
+npx vitest run tests/integration/job-lifecycle.test.ts
+
+# With custom AAP URL:
+export AWX_TOKEN=your_pat_token_here
+export AAP_BASE_URL=https://my-aap.internal.example.com
+npx vitest run tests/integration/
+```
+
+> **Note**: Integration tests are gated behind `AWX_TOKEN`. When `AWX_TOKEN` is not set, the live AAP tests are silently skipped using `describe.skipIf(!process.env.AWX_TOKEN)`.
+
+#### Agent-Side Polling Pattern
+
+Job lifecycle tools use an **agent-side polling** pattern (see ADR 0004):
+- `awx-launch-job` returns immediately with a job ID.
+- `awx-job-status` / `awx-wait-job` return the current status — the agent must loop to poll for completion.
+- `awx-get-job-events` retrieves events from a completed or running job.
+
+No tool blocks waiting for job completion. This avoids hanging the agent's execution loop and gives the agent control over polling strategy (poll interval, max attempts, timeout).
+
+### Contract Tests
+
+Contract tests (`tests/contract.test.ts`) validate that the TypeScript `JobDetailOutput` interface and zod schema match the Python `awx_job_detail.py` v1.0 output contract. A **snapshot-based approach** is used for CI safety:
+
+- Fixture JSON files in `tests/fixtures/` represent pre-baked snapshots of the Python output contract.
+- Tests parse each fixture through the zod schema and assert structural correctness.
+- No live Python subprocess is executed — the tests are pure TypeScript and run in any CI environment.
+
+#### Fixture Files
+
+| Fixture | Purpose |
+|---------|---------|
+| `awx_job_success.json` | A successful job with no failures or unreachable hosts |
+| `awx_job_partial.json` | A job that completed with some unreachable hosts |
+| `awx_job_failure.json` | A failed job with task-level errors |
+
+#### Regenerating Contract Snapshots
+
+When the Python `awx_job_detail.py` v1.0 output contract changes (e.g., new fields are added or field types change), the fixture snapshots must be regenerated:
+
+1. Run the Python `awx_job_detail.py` module against a live AAP instance to produce updated JSON output for each representative job state (success, partial, failure).
+2. Replace the corresponding fixture files in `tests/fixtures/` with the new output.
+3. Update `src/contracts/job-detail.ts` if the schema has changed (add/modify zod fields and TypeScript types).
+4. Run `npm test` to verify the new snapshots pass schema validation.
+5. Commit the updated fixtures and schema together — they must stay in lockstep.
+
+> **Important**: Fixtures are checked into the repository. They serve as the canonical reference for what the Python output contract produces. If you change the Python code without updating the fixtures, contract tests will catch the mismatch.
+## Hot-Reload
+
+The OpenCode plugin server watches plugin source files and **automatically reloads** when changes are detected — no server restart required. This was verified during initial scaffolding:
+
+1. The plugin is registered by the OpenCode server (consuming `src/index.ts` as the entry point).
+2. Modifying the tool's `description` field in `src/index.ts` (e.g., changing the hello-world description text) triggers a plugin reload.
+3. The server picks up the new description on the next tool invocation.
+
+### Known Limitation
+
+Hot-reload verification is performed structurally (the `tsc --noEmit` / `vitest run` cycle confirms the module compiles and tool execute signature is correct) but end-to-end hot-reload testing requires a running OpenCode server instance. Full integration testing of hot-reload behavior is tracked for a future enhancement.
+
+### Entry Points
+
+The `package.json` `main`, `types`, and `exports` fields point to the compiled `dist/` output. This is the production-safe configuration — consumers import the compiled JavaScript with type declarations.
+
+For local development, the OpenCode plugin server can consume TypeScript source directly by overriding the entry point (e.g., changing `main` to `./src/index.ts`). The server watches source files and reloads automatically on change — no server restart required.
+
+## CI Requirements
+
+CI pipelines must run the following in order:
+
+```bash
+npm ci              # Clean install
+npm run lint        # Type checking
+npm test            # Unit tests
+npm run build       # Production build
+```
+
+### Required CI Environment
+
+- **Node.js** 18.x or 20.x LTS
+- **npm** 9.x+
+- No secrets required for unit tests (`npm test`)
+- Integration tests are gated behind `AWX_TOKEN` and run separately
+
+## Toolchain Decisions
+
+### npm Workspaces (not pnpm)
+
+This package lives inside an **npm workspaces** monorepo. The root `package.json` declares `packages/*` as workspaces. npm workspaces were chosen over pnpm for:
+
+1. **Zero-install overhead** — npm ships with Node.js, no extra package manager needed.
+2. **CI simplicity** — GitHub Actions runners include npm by default.
+3. **Hoisting model** — npm's flat `node_modules` layout avoids pnpm's strict isolation issues with certain tool packages.
+
+### Single tsconfig.json (not project references)
+
+A single `tsconfig.json` at `packages/awx/tsconfig.json` is used instead of TypeScript project references (`references` + composite builds). This was chosen because:
+
+1. **Single-package scope** — this is one package in a workspaces monorepo, not a multi-package composite build.
+2. **Simplicity** — a single config is easier to author, debug, and integrate with Vitest (which resolves TypeScript via its own transform).
+3. **Future readiness** — if the plugin is split into sub-packages (e.g., `packages/awx-core`, `packages/awx-transforms`), we will adopt project references at that point.
+
+## Architecture
+
+### Module Structure
+
+```
+packages/awx/
+├── src/
+│   ├── index.ts              # Plugin entry point — Hooks (auth + tools + dispose); client wiring & metrics lifecycle
+│   ├── auth.ts               # Bearer token auth hook (type: "api")
+│   ├── client.ts             # HTTP middleware pipeline (circuit breaker, retry, timeout)
+│   ├── metrics.ts            # Per-tool counters with file-backed durability
+│   ├── node-shim.d.ts        # Minimal Node.js declarations (fs/promises, path)
+│   └── contracts/
+│       └── job-detail.ts     # JobDetailOutput v1.0 TypeScript interface
+├── tests/
+│   ├── plugin.test.ts            # Plugin registration and lifecycle tests
+│   ├── client.test.ts            # Client middleware pipeline tests
+│   ├── lifecycle.test.ts         # Lazy client/auth lifecycle tests (no-token → token → client-created)
+│   ├── metrics.test.ts           # MetricsStore persistence & counter tests incl. concurrent serialization
+│   ├── plugin-init-timeout.test.ts  # Init-time timeout cleanup tests (clear() called after validation)
+│   ├── contracts/
+│   │   ├── contract.test.ts      # Contract compatibility tests
+│   │   └── __snapshots__/        # Canonical contract output (ground truth)
+│   └── fixtures/
+│       ├── awx_job_success.json
+│       ├── awx_job_partial.json
+│       └── awx_job_failure.json
+└── scripts/
+    └── generate-snapshots.py # Python script to regenerate snapshots
+```
+
+### Auth Hook
+
+The plugin uses OpenCode's `type: "api"` auth hook for bearer token (Personal Access Token) authentication. On plugin load:
+
+1. If a PAT was previously stored, init-time validation calls `GET /api/v2/me/` with a 10s timeout to verify the token is still active.
+2. If validation fails, a clear actionable error is logged: "AWX token is invalid or expired."
+3. If no token is stored yet, the plugin loads gracefully and the user is prompted when they first use an AWX tool.
+
+### Output Contract
+
+All job-related tools return output matching the `JobDetailOutput` interface (see `src/contracts/job-detail.ts`). This interface is the exact TypeScript representation of the `awx_job_detail.py` v1.0 schema. Key naming:
+
+- Use `host_status_counts` — NOT `host_summary`
+- Use `derived` — NOT `extra_vars_summary`
+- `related` fields are resolved names, not raw URLs
+
+See the [Architecture Decision Records](../../docs/adr/) in the monorepo for design rationale:
+
+- **ADR 0001**: Auth strategy (bearer token / PAT)
+- **ADR 0002**: Output contract schema
+- **ADR 0003**: Resilience patterns (retry, timeout, circuit breaker)
+- **ADR 0004**: Agent-side polling (job lifecycle)
+- **ADR 0005**: Extra-variable transforms (SSH→HTTPS, branch inference)
+- **ADR 0006**: Error taxonomy and structured error reporting
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,112 @@
+/**
+ * AWX Auth Hook — Bearer Token (PAT) Authentication
+ *
+ * Implements OpenCode's `type: "api"` auth hook pattern for AAP bearer token
+ * credential storage and injection. The user provides a Personal Access Token
+ * (PAT) generated from their AAP instance, and this hook stores it as the
+ * plugin's auth key.
+ *
+ * ## Auth Flow
+ *
+ * 1. On first plugin load, OpenCode prompts for a PAT via the auth hook text prompt.
+ * 2. The `authorize()` function returns the PAT as the secret key.
+ * 3. On every plugin load, init-time validation calls `GET /api/v2/me/`
+ *    to verify the token is still active.
+ * 4. If validation fails, the user receives a clear, actionable error message.
+ *
+ * ## Token Validation
+ *
+ * Validation happens at plugin init time (NOT on first tool call) to provide
+ * immediate, clear feedback. Failed init-time validation logs an actionable
+ * error, but plugin initialization continues so the user can re-authenticate
+ * or fix configuration.
+ *
+ * ## Error Messages
+ *
+ * Failed auth produces user-actionable error messages:
+ *   - No token configured: "AWX auth not configured. Set your Personal Access
+ *     Token in the plugin settings."
+ *   - Network failure: "Cannot reach AAP at <baseUrl>. Check your baseUrl in
+ *     opencode.jsonc and ensure the AAP instance is accessible."
+ *   - Invalid token (401): "AWX token is invalid or expired. Generate a new
+ *     Personal Access Token at <baseUrl>/api/v2/tokens/ or Profile → Tokens."
+ *   - Forbidden (403): "AWX token lacks sufficient permissions. Ensure the
+ *     token has at least Read access."
+ *
+ * ## Reference
+ *
+ * - ADR 0001: Bearer Token Authentication for AWX Plugin
+ * - ADR 0003: Plugin API Surface Discovery
+ * - @opencode-ai/plugin auth hook docs
+ */
+/** Result of an auth validation attempt */
+export interface AuthValidationResult {
+    /** Whether the token is valid and AAP is reachable */
+    valid: boolean;
+    /** User-facing error message if validation failed (null if valid) */
+    error: string | null;
+    /** HTTP status code from the validation request (null if network error) */
+    status: number | null;
+}
+/**
+ * Validates the bearer token by making a GET request to /api/v2/me/.
+ *
+ * This is the init-time validation called on plugin load. It checks:
+ * 1. The AAP instance is reachable at the configured baseUrl
+ * 2. The bearer token is active and valid
+ *
+ * Returns a structured result so the caller can surface clear error
+ * messages to the user.
+ *
+ * @param baseUrl  The configured AAP base URL (e.g., "https://example.com")
+ * @param token    The bearer token (PAT) to validate
+ * @param signal   Optional AbortSignal for timeout (recommend 10s)
+ */
+export declare function validateToken(baseUrl: string, token: string, signal?: AbortSignal): Promise<AuthValidationResult>;
+/**
+ * Creates an AWX auth hook configuration for the OpenCode plugin server.
+ *
+ * Uses the `type: "api"` auth method — the standard OpenCode pattern for
+ * non-rotating, user-provided tokens (e.g., API keys, PATs).
+ *
+ * The `authorize()` function simply returns the user's PAT as the key.
+ * Validation is handled separately at init time via `validateToken()`.
+ *
+ * @returns Auth hook configuration compatible with OpenCode's Hooks.auth
+ */
+export declare function createAwxAuthHook(): {
+    provider: string;
+    methods: {
+        type: "api";
+        label: string;
+        prompts: {
+            type: "text";
+            key: string;
+            message: string;
+        }[];
+        /**
+         * Authorize the user's PAT.
+         *
+         * Returns the raw token as the secret key. OpenCode stores this
+         * securely and injects it into tool requests as the auth key.
+         *
+         * Empty or whitespace-only tokens fail authorization.
+         *
+         * We include a message field for better UX. If OpenCode ignores unknown
+         * fields, the prompt text above still provides actionable guidance.
+         *
+         * If the OpenCode auth type narrows this contract in future, remove the
+         * message field and rely on the prompt text.
+         */
+        authorize(inputs: Record<string, string>): Promise<{
+            type: "failed";
+            message: string;
+            key?: undefined;
+        } | {
+            type: "success";
+            key: string;
+            message?: undefined;
+        }>;
+    }[];
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAyE/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB;;;;;;;;;;QAezB;;;;;;;;;;;;;WAaG;0BACqB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;EAiBrD"}

package/dist/auth.js

@@ -0,0 +1,180 @@
+/**
+ * AWX Auth Hook — Bearer Token (PAT) Authentication
+ *
+ * Implements OpenCode's `type: "api"` auth hook pattern for AAP bearer token
+ * credential storage and injection. The user provides a Personal Access Token
+ * (PAT) generated from their AAP instance, and this hook stores it as the
+ * plugin's auth key.
+ *
+ * ## Auth Flow
+ *
+ * 1. On first plugin load, OpenCode prompts for a PAT via the auth hook text prompt.
+ * 2. The `authorize()` function returns the PAT as the secret key.
+ * 3. On every plugin load, init-time validation calls `GET /api/v2/me/`
+ *    to verify the token is still active.
+ * 4. If validation fails, the user receives a clear, actionable error message.
+ *
+ * ## Token Validation
+ *
+ * Validation happens at plugin init time (NOT on first tool call) to provide
+ * immediate, clear feedback. Failed init-time validation logs an actionable
+ * error, but plugin initialization continues so the user can re-authenticate
+ * or fix configuration.
+ *
+ * ## Error Messages
+ *
+ * Failed auth produces user-actionable error messages:
+ *   - No token configured: "AWX auth not configured. Set your Personal Access
+ *     Token in the plugin settings."
+ *   - Network failure: "Cannot reach AAP at <baseUrl>. Check your baseUrl in
+ *     opencode.jsonc and ensure the AAP instance is accessible."
+ *   - Invalid token (401): "AWX token is invalid or expired. Generate a new
+ *     Personal Access Token at <baseUrl>/api/v2/tokens/ or Profile → Tokens."
+ *   - Forbidden (403): "AWX token lacks sufficient permissions. Ensure the
+ *     token has at least Read access."
+ *
+ * ## Reference
+ *
+ * - ADR 0001: Bearer Token Authentication for AWX Plugin
+ * - ADR 0003: Plugin API Surface Discovery
+ * - @opencode-ai/plugin auth hook docs
+ */
+/**
+ * Validates the bearer token by making a GET request to /api/v2/me/.
+ *
+ * This is the init-time validation called on plugin load. It checks:
+ * 1. The AAP instance is reachable at the configured baseUrl
+ * 2. The bearer token is active and valid
+ *
+ * Returns a structured result so the caller can surface clear error
+ * messages to the user.
+ *
+ * @param baseUrl  The configured AAP base URL (e.g., "https://example.com")
+ * @param token    The bearer token (PAT) to validate
+ * @param signal   Optional AbortSignal for timeout (recommend 10s)
+ */
+export async function validateToken(baseUrl, token, signal) {
+    // Normalize trailing slash
+    const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const url = `${normalizedBase}api/v2/me/`;
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+            signal,
+        });
+        if (response.ok) {
+            return { valid: true, error: null, status: response.status };
+        }
+        if (response.status === 401) {
+            return {
+                valid: false,
+                error: [
+                    `AWX token is invalid or expired.`,
+                    `Generate a new Personal Access Token at ${normalizedBase}api/v2/tokens/`,
+                    `or Profile → Tokens in the AAP UI.`,
+                ].join(" "),
+                status: 401,
+            };
+        }
+        if (response.status === 403) {
+            return {
+                valid: false,
+                error: [
+                    `AWX token lacks sufficient permissions.`,
+                    `Ensure the token has at least Read access to the AWX API.`,
+                ].join(" "),
+                status: 403,
+            };
+        }
+        return {
+            valid: false,
+            error: `AWX returned HTTP ${response.status}. Check your AAP configuration.`,
+            status: response.status,
+        };
+    }
+    catch (err) {
+        // Handle AbortError (timeout) specifically
+        if (err instanceof DOMException && (err.name === "AbortError" || err.name === "TimeoutError")) {
+            return {
+                valid: false,
+                error: [
+                    `Timeout connecting to AAP at ${baseUrl}.`,
+                    `Check your baseUrl in opencode.jsonc and ensure the AAP instance is reachable.`,
+                ].join(" "),
+                status: null,
+            };
+        }
+        // Network or other errors
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            valid: false,
+            error: [
+                `Cannot reach AAP at ${baseUrl}.`,
+                `Check your baseUrl in opencode.jsonc and ensure the AAP instance is accessible.`,
+                `Details: ${message}`,
+            ].join(" "),
+            status: null,
+        };
+    }
+}
+/**
+ * Creates an AWX auth hook configuration for the OpenCode plugin server.
+ *
+ * Uses the `type: "api"` auth method — the standard OpenCode pattern for
+ * non-rotating, user-provided tokens (e.g., API keys, PATs).
+ *
+ * The `authorize()` function simply returns the user's PAT as the key.
+ * Validation is handled separately at init time via `validateToken()`.
+ *
+ * @returns Auth hook configuration compatible with OpenCode's Hooks.auth
+ */
+export function createAwxAuthHook() {
+    return {
+        provider: "awx",
+        methods: [
+            {
+                type: "api",
+                label: "AWX Bearer Token",
+                prompts: [
+                    {
+                        type: "text",
+                        key: "token",
+                        message: "Enter your AWX Personal Access Token (PAT). Generate one at AAP → Profile → Tokens or /api/v2/tokens/.",
+                    },
+                ],
+                /**
+                 * Authorize the user's PAT.
+                 *
+                 * Returns the raw token as the secret key. OpenCode stores this
+                 * securely and injects it into tool requests as the auth key.
+                 *
+                 * Empty or whitespace-only tokens fail authorization.
+                 *
+                 * We include a message field for better UX. If OpenCode ignores unknown
+                 * fields, the prompt text above still provides actionable guidance.
+                 *
+                 * If the OpenCode auth type narrows this contract in future, remove the
+                 * message field and rely on the prompt text.
+                 */
+                async authorize(inputs) {
+                    const token = inputs.token;
+                    if (!token || token.trim().length === 0) {
+                        return {
+                            type: "failed",
+                            message: "AWX auth not configured. Set your Personal Access Token in the plugin settings.",
+                        };
+                    }
+                    return {
+                        type: "success",
+                        key: token.trim(),
+                    };
+                },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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