@ghx-dev/core 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,17 @@
 import { DocumentNode } from 'graphql';
 
+type TokenResolution = {
+    token: string;
+    source: "env" | "cache" | "gh-cli";
+};
+declare function resolveGithubToken(): Promise<TokenResolution>;
+declare function invalidateTokenCache(): Promise<void>;
+
+/**
+ * All possible error codes returned in {@link ResultError.code}.
+ *
+ * Retryable codes: `RATE_LIMIT`, `NETWORK`, `SERVER`.
+ */
 declare const errorCodes: {
     readonly Auth: "AUTH";
     readonly NotFound: "NOT_FOUND";
@@ -10,24 +22,49 @@ declare const errorCodes: {
     readonly AdapterUnsupported: "ADAPTER_UNSUPPORTED";
     readonly Unknown: "UNKNOWN";
 };
+/** Union of all error code string literals. */
 type ErrorCode = (typeof errorCodes)[keyof typeof errorCodes];
 
+/**
+ * All possible reason codes explaining why a particular route was selected.
+ *
+ * Included in {@link ResultMeta.reason}.
+ */
 declare const routeReasonCodes: readonly ["INPUT_VALIDATION", "OUTPUT_VALIDATION", "CARD_PREFERRED", "CARD_FALLBACK", "PREFLIGHT_FAILED", "ENV_CONSTRAINT", "CAPABILITY_LIMIT", "DEFAULT_POLICY"];
+/** Reason code explaining why a particular route was selected. */
 type RouteReasonCode = (typeof routeReasonCodes)[number];
 
+/** The transport route used to execute a capability. */
 type RouteSource = "cli" | "rest" | "graphql";
+/**
+ * Structured error returned inside a {@link ResultEnvelope} when `ok` is `false`.
+ *
+ * @see {@link ErrorCode} for the full list of error codes.
+ */
 interface ResultError {
     code: ErrorCode;
     message: string;
     retryable: boolean;
     details?: Record<string, unknown>;
 }
+/**
+ * Records a single route attempt during execution.
+ *
+ * The routing engine may try multiple routes (preferred → fallback).
+ * Each attempt is logged here regardless of outcome.
+ */
 interface AttemptMeta {
     route: RouteSource;
     status: "success" | "error" | "skipped";
     error_code?: ErrorCode;
     duration_ms?: number;
 }
+/**
+ * Metadata attached to every {@link ResultEnvelope}.
+ *
+ * Provides observability into which route was used, why, how long it took,
+ * and the full list of route attempts.
+ */
 interface ResultMeta {
     capability_id: string;
     route_used?: RouteSource;
@@ -47,19 +84,35 @@ interface ResultMeta {
         tokens_out?: number;
     };
 }
+/**
+ * The universal response contract for all ghx operations.
+ *
+ * Every call to {@link executeTask} returns a `ResultEnvelope` — it never throws.
+ * Check `ok` to distinguish success from failure; `data` and `error` are exclusive.
+ *
+ * @typeParam TData - The shape of the success payload, varies per capability.
+ */
 interface ResultEnvelope<TData = unknown> {
     ok: boolean;
     data?: TData;
     error?: ResultError;
     meta: ResultMeta;
 }
+/** Aggregate outcome of a batch execution via {@link executeTasks}. */
 type ChainStatus = "success" | "partial" | "failed";
+/** Result of a single step within a chain execution. */
 interface ChainStepResult {
     task: string;
     ok: boolean;
     data?: unknown;
     error?: ResultError;
 }
+/**
+ * Response envelope for batch operations via {@link executeTasks}.
+ *
+ * Contains per-step results and aggregate metadata
+ * (total, succeeded, failed counts).
+ */
 interface ChainResultEnvelope {
     status: ChainStatus;
     results: ChainStepResult[];
@@ -71,7 +124,13 @@ interface ChainResultEnvelope {
     };
 }
 
+/** A dotted capability identifier (e.g. `"pr.view"`, `"issue.labels.add"`). */
 type TaskId = string;
+/**
+ * A request to execute a single ghx capability.
+ *
+ * @typeParam TInput - The shape of the input payload, varies per capability.
+ */
 interface TaskRequest<TInput = Record<string, unknown>> {
     task: TaskId;
     input: TInput;
@@ -82,13 +141,28 @@ type ExecuteTaskFn = (request: {
     input: Record<string, unknown>;
     options?: Record<string, unknown>;
 }) => Promise<ResultEnvelope>;
+/**
+ * Creates an execute tool suitable for wiring into an AI agent's tool loop.
+ *
+ * Wraps the execution engine into a simple `{ execute(capabilityId, params) }` shape.
+ *
+ * @example
+ * ```ts
+ * const tool = createExecuteTool({
+ *   executeTask: (req) => executeTask(req, deps),
+ * })
+ * const result = await tool.execute("repo.view", { owner: "aryeko", name: "ghx" })
+ * ```
+ */
 declare function createExecuteTool(deps: {
     executeTask: ExecuteTaskFn;
 }): {
     execute(capabilityId: string, params: Record<string, unknown>, options?: Record<string, unknown>): Promise<ResultEnvelope>;
 };
 
+/** Represents a JSON Schema definition for card inputs/outputs. */
 type JsonSchema = Record<string, unknown>;
+/** Defines when a fallback route should override the preferred route. */
 interface SuitabilityRule {
     when: "always" | "env" | "params";
     predicate: string;
@@ -173,16 +247,25 @@ interface NullLiteralInject {
     target: string;
     source: "null_literal";
 }
+/** A specification for how to inject a resolved Phase 1 value into Phase 2. */
 type InjectSpec = ScalarInject | MapArrayInject | InputPassthroughInject | NullLiteralInject;
+/** Defines the GraphQL query to run during the Phase 1 lookup. */
 interface LookupSpec {
     operationName: string;
     documentPath: string;
     vars: Record<string, string>;
 }
+/** Configuration for a Phase 1 node ID lookup prior to mutation execution. */
 interface ResolutionConfig {
     lookup: LookupSpec;
     inject: InjectSpec[];
 }
+/**
+ * Declarative configuration for a single ghx capability.
+ *
+ * Defines the capability's identity, input/output schemas, routing preferences,
+ * and adapter-specific execution details (GraphQL, CLI, REST).
+ */
 interface OperationCard<Input = Record<string, unknown>> {
     capability_id: string;
     version: string;
@@ -239,6 +322,7 @@ type SafeRunnerOptions = {
 };
 declare function createSafeCliCommandRunner(options?: SafeRunnerOptions): CliCommandRunner;
 
+/** Structured explanation of a capability, returned by {@link explainCapability}. */
 type CapabilityExplanation = {
     capability_id: string;
     purpose: string;
@@ -248,11 +332,19 @@ type CapabilityExplanation = {
     fallback_routes: Array<"cli" | "graphql" | "rest">;
     output_fields: string[];
 };
+/**
+ * Return a structured explanation of a capability by its ID.
+ *
+ * @throws If the capability ID is unknown.
+ */
 declare function explainCapability(capabilityId: string): CapabilityExplanation;
 
+/** Return a copy of all registered operation cards, in canonical order. */
 declare function listOperationCards(): OperationCard[];
+/** Look up a single operation card by its dotted capability ID (e.g. `"pr.view"`). */
 declare function getOperationCard(capabilityId: string): OperationCard | undefined;
 
+/** Summary of a capability, returned by {@link listCapabilities}. */
 type CapabilityListItem = {
     capability_id: string;
     description: string;
@@ -260,31 +352,56 @@ type CapabilityListItem = {
     optional_inputs: string[];
     optional_inputs_detail: Record<string, unknown>;
 };
+/**
+ * List all available capabilities, optionally filtered by domain.
+ *
+ * @param domain - Filter by top-level domain (e.g. `"pr"`, `"issue"`, `"workflow"`).
+ */
 declare function listCapabilities(domain?: string): CapabilityListItem[];
 
 type GraphqlVariables = Record<string, unknown>;
+/** A single error from a GraphQL response. */
 type GraphqlError = {
     message: string;
     path?: ReadonlyArray<string | number>;
     extensions?: Record<string, unknown>;
 };
+/** Raw GraphQL response containing both `data` and `errors` fields. */
 type GraphqlRawResult<TData> = {
     data: TData | undefined;
     errors: GraphqlError[] | undefined;
 };
 type GraphqlDocument = string | DocumentNode;
+/**
+ * Low-level transport interface for sending GraphQL queries.
+ *
+ * Implement this to use a custom HTTP client, proxy, or mock.
+ * Pass to {@link createGithubClient} or {@link createGraphqlClient}.
+ */
 interface GraphqlTransport {
     execute<TData>(query: string, variables?: GraphqlVariables): Promise<TData>;
     executeRaw?<TData>(query: string, variables?: GraphqlVariables): Promise<GraphqlRawResult<TData>>;
 }
+/**
+ * Higher-level GraphQL client with `query` and `queryRaw` methods.
+ *
+ * Created by {@link createGraphqlClient} from a {@link GraphqlTransport}.
+ */
 interface GraphqlClient {
     query<TData, TVariables extends GraphqlVariables = GraphqlVariables>(query: GraphqlDocument, variables?: TVariables): Promise<TData>;
     queryRaw<TData, TVariables extends GraphqlVariables = GraphqlVariables>(query: GraphqlDocument, variables?: TVariables): Promise<GraphqlRawResult<TData>>;
 }
+/** Options for creating a token-based GraphQL transport. */
 type TokenClientOptions = {
     token: string;
     graphqlUrl?: string;
 };
+/**
+ * Create a {@link GraphqlClient} from a {@link GraphqlTransport}.
+ *
+ * Wraps the raw transport `execute` method with query string normalization
+ * and a `queryRaw` method that returns settled results.
+ */
 declare function createGraphqlClient(transport: GraphqlTransport): GraphqlClient;
 
 type Maybe<T> = T | null;
@@ -1013,6 +1130,14 @@ type ProjectV2ItemFieldUpdateData = {
     itemId: string;
 };
 
+/**
+ * High-level GitHub API client with 50+ typed methods.
+ *
+ * Extends {@link GraphqlClient} with domain-specific helpers for issues, PRs,
+ * releases, projects, and repos. Domain modules are lazy-loaded on first use.
+ *
+ * Create via {@link createGithubClientFromToken} or {@link createGithubClient}.
+ */
 interface GithubClient extends GraphqlClient {
     fetchRepoView(input: RepoViewInput): Promise<RepoViewData>;
     fetchIssueCommentsList(input: IssueCommentsListInput): Promise<IssueCommentsListData>;
@@ -1067,9 +1192,28 @@ interface GithubClient extends GraphqlClient {
     removeProjectV2Item(input: ProjectV2ItemRemoveInput): Promise<ProjectV2ItemRemoveData>;
     updateProjectV2ItemField(input: ProjectV2ItemFieldUpdateInput): Promise<ProjectV2ItemFieldUpdateData>;
 }
+/**
+ * Create a {@link GithubClient} from a token (string or options object).
+ *
+ * Uses the default `fetch`-based transport. For custom transports, use
+ * {@link createGithubClient} instead.
+ *
+ * @throws If the token is empty.
+ */
 declare function createGithubClientFromToken(tokenOrOptions: string | TokenClientOptions): GithubClient;
+/**
+ * Create a {@link GithubClient} from a custom {@link GraphqlTransport}.
+ *
+ * Use this for enterprise endpoints, proxies, or test mocking.
+ */
 declare function createGithubClient(transport: GraphqlTransport): GithubClient;
 
+/**
+ * Cache for Phase 1 resolution lookups in batch execution.
+ *
+ * Avoids redundant GraphQL lookups when the same entity is referenced
+ * by multiple steps in a chain.
+ */
 interface ResolutionCache {
     get(key: string): unknown | undefined;
     set(key: string, value: unknown): void;
@@ -1083,9 +1227,20 @@ interface ResolutionCacheOptions {
     /** Maximum number of cached entries. Default: 200. */
     maxEntries?: number;
 }
+/**
+ * Create an in-memory resolution cache with TTL and FIFO eviction.
+ *
+ * Pass to `ExecutionDeps.resolutionCache` for batch operations.
+ */
 declare function createResolutionCache(opts?: ResolutionCacheOptions): ResolutionCache;
+/** Build a deterministic cache key from an operation name and variables. */
 declare function buildCacheKey(operationName: string, variables: Record<string, unknown>): string;
 
+/**
+ * Dependencies required by the execution engine.
+ *
+ * Pass to {@link executeTask} or {@link executeTasks}.
+ */
 type ExecutionDeps = {
     githubClient: GithubClient;
     githubToken?: string | null;
@@ -1097,10 +1252,22 @@ type ExecutionDeps = {
     resolutionCache?: ResolutionCache;
 };
 
+/**
+ * Execute a single GitHub operation.
+ *
+ * Looks up the operation card, validates input, selects a route, and returns
+ * a {@link ResultEnvelope}. Never throws.
+ */
 declare function executeTask(request: TaskRequest, deps: ExecutionDeps): Promise<ResultEnvelope>;
+/**
+ * Execute multiple operations as a batch.
+ *
+ * Classifies steps, resolves node IDs via Phase 1 lookups, batches GraphQL
+ * operations, and returns a {@link ChainResultEnvelope}.
+ */
 declare function executeTasks(requests: Array<{
     task: string;
     input: Record<string, unknown>;
 }>, deps: ExecutionDeps): Promise<ChainResultEnvelope>;
 
-export { type AttemptMeta, type CapabilityExplanation, type CapabilityListItem, type ChainResultEnvelope, type ChainStatus, type ChainStepResult, type CliCommandRunner, type GithubClient, type GraphqlClient, type GraphqlError, type GraphqlRawResult, type GraphqlTransport, type OperationCard, type ResolutionCache, type ResolutionCacheOptions, type ResultEnvelope, type ResultError, type ResultMeta, type RouteReasonCode, type RouteSource, type TaskRequest, type TokenClientOptions, buildCacheKey, createExecuteTool, createGithubClient, createGithubClientFromToken, createGraphqlClient, createResolutionCache, createSafeCliCommandRunner, executeTask, executeTasks, explainCapability, getOperationCard, listCapabilities, listOperationCards };
+export { type AttemptMeta, type CapabilityExplanation, type CapabilityListItem, type ChainResultEnvelope, type ChainStatus, type ChainStepResult, type CliCommandRunner, type GithubClient, type GraphqlClient, type GraphqlError, type GraphqlRawResult, type GraphqlTransport, type OperationCard, type ResolutionCache, type ResolutionCacheOptions, type ResultEnvelope, type ResultError, type ResultMeta, type RouteReasonCode, type RouteSource, type TaskRequest, type TokenClientOptions, type TokenResolution, buildCacheKey, createExecuteTool, createGithubClient, createGithubClientFromToken, createGraphqlClient, createResolutionCache, createSafeCliCommandRunner, executeTask, executeTasks, explainCapability, getOperationCard, invalidateTokenCache, listCapabilities, listOperationCards, resolveGithubToken };

package/dist/index.js

@@ -8,9 +8,11 @@ import {
   executeTasks,
   explainCapability,
   getOperationCard,
+  invalidateTokenCache,
   listCapabilities,
-  listOperationCards
-} from "./chunk-M5PJLKL5.js";
+  listOperationCards,
+  resolveGithubToken
+} from "./chunk-7A73AXLY.js";
 import "./chunk-H7CLZHRO.js";
 import "./chunk-NQ53ETYV.js";
 import "./chunk-TGL33GEA.js";
@@ -24,7 +26,7 @@ import "./chunk-GQO6BHJV.js";
 import "./chunk-R3CBGJZX.js";
 import {
   createGraphqlClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/core/execute/execute-tool.ts
 function createExecuteTool(deps) {
@@ -51,7 +53,9 @@ export {
   executeTasks,
   explainCapability,
   getOperationCard,
+  invalidateTokenCache,
   listCapabilities,
-  listOperationCards
+  listOperationCards,
+  resolveGithubToken
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/execute/execute-tool.ts"],"sourcesContent":["import type { ResultEnvelope } from \"../contracts/envelope.js\"\n\ntype ExecuteTaskFn = (request: {\n  task: string\n  input: Record<string, unknown>\n  options?: Record<string, unknown>\n}) => Promise<ResultEnvelope>\n\nexport function createExecuteTool(deps: { executeTask: ExecuteTaskFn }) {\n  return {\n    execute(\n      capabilityId: string,\n      params: Record<string, unknown>,\n      options?: Record<string, unknown>,\n    ): Promise<ResultEnvelope> {\n      const request = {\n        task: capabilityId,\n        input: params,\n        ...(options ? { options } : {}),\n      }\n\n      return deps.executeTask(request)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQO,SAAS,kBAAkB,MAAsC;AACtE,SAAO;AAAA,IACL,QACE,cACA,QACA,SACyB;AACzB,YAAM,UAAU;AAAA,QACd,MAAM;AAAA,QACN,OAAO;AAAA,QACP,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,MAC/B;AAEA,aAAO,KAAK,YAAY,OAAO;AAAA,IACjC;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/core/execute/execute-tool.ts"],"sourcesContent":["import type { ResultEnvelope } from \"../contracts/envelope.js\"\n\ntype ExecuteTaskFn = (request: {\n  task: string\n  input: Record<string, unknown>\n  options?: Record<string, unknown>\n}) => Promise<ResultEnvelope>\n\n/**\n * Creates an execute tool suitable for wiring into an AI agent's tool loop.\n *\n * Wraps the execution engine into a simple `{ execute(capabilityId, params) }` shape.\n *\n * @example\n * ```ts\n * const tool = createExecuteTool({\n *   executeTask: (req) => executeTask(req, deps),\n * })\n * const result = await tool.execute(\"repo.view\", { owner: \"aryeko\", name: \"ghx\" })\n * ```\n */\nexport function createExecuteTool(deps: { executeTask: ExecuteTaskFn }) {\n  return {\n    execute(\n      capabilityId: string,\n      params: Record<string, unknown>,\n      options?: Record<string, unknown>,\n    ): Promise<ResultEnvelope> {\n      const request = {\n        task: capabilityId,\n        input: params,\n        ...(options ? { options } : {}),\n      }\n\n      return deps.executeTask(request)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBO,SAAS,kBAAkB,MAAsC;AACtE,SAAO;AAAA,IACL,QACE,cACA,QACA,SACyB;AACzB,YAAM,UAAU;AAAA,QACd,MAAM;AAAA,QACN,OAAO;AAAA,QACP,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,MAC/B;AAEA,aAAO,KAAK,YAAY,OAAO;AAAA,IACjC;AAAA,EACF;AACF;","names":[]}

package/dist/{issue-mutations-OW464JP3.js → issue-mutations-DIWPF3JH.js}

@@ -51,7 +51,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/domains/issue-mutations.ts
 function parseIssueNode(issue) {
@@ -642,4 +642,4 @@ export {
   runIssueReopen,
   runIssueUpdate
 };
-//# sourceMappingURL=issue-mutations-OW464JP3.js.map
+//# sourceMappingURL=issue-mutations-DIWPF3JH.js.map

package/dist/{issue-queries-ORG3VPK4.js → issue-queries-YQL65J7X.js}

@@ -12,7 +12,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/domains/issue-queries.ts
 async function runIssueView(transport, input) {
@@ -90,4 +90,4 @@ export {
   runIssueList,
   runIssueView
 };
-//# sourceMappingURL=issue-queries-ORG3VPK4.js.map
+//# sourceMappingURL=issue-queries-YQL65J7X.js.map

package/dist/{pr-mutations-WOTG6FAB.js → pr-mutations-BVHDCAPR.js}

@@ -33,7 +33,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/operations/review-thread-state.generated.ts
 var ReviewThreadStateDocument = `
@@ -481,4 +481,4 @@ export {
   runSubmitPrReview,
   runUnresolveReviewThread
 };
-//# sourceMappingURL=pr-mutations-WOTG6FAB.js.map
+//# sourceMappingURL=pr-mutations-BVHDCAPR.js.map

package/dist/{pr-queries-6CJJW7BT.js → pr-queries-NUL2UZJB.js}

@@ -15,7 +15,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/domains/pr-queries.ts
 async function runPrView(transport, input) {
@@ -140,4 +140,4 @@ export {
   runPrReviewsList,
   runPrView
 };
-//# sourceMappingURL=pr-queries-6CJJW7BT.js.map
+//# sourceMappingURL=pr-queries-NUL2UZJB.js.map

package/dist/{project-QFSCYDDW.js → project-3ZSPVIOC.js}

@@ -19,7 +19,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/operations/project-v2-fields-list-user.generated.ts
 var ProjectV2FieldsListUserDocument = `
@@ -426,4 +426,4 @@ export {
   runProjectV2OrgView,
   runProjectV2UserView
 };
-//# sourceMappingURL=project-QFSCYDDW.js.map
+//# sourceMappingURL=project-3ZSPVIOC.js.map

package/dist/{release-33236BBA.js → release-IQCWD655.js}

@@ -9,7 +9,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/domains/release.ts
 function mapReleaseNode(r) {
@@ -54,4 +54,4 @@ export {
   runReleaseList,
   runReleaseView
 };
-//# sourceMappingURL=release-33236BBA.js.map
+//# sourceMappingURL=release-IQCWD655.js.map

package/dist/{repo-M6DKCWBG.js → repo-JF47JAZG.js}

@@ -10,7 +10,7 @@ import {
 } from "./chunk-OQWLEFAH.js";
 import {
   createGraphqlRequestClient
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/gql/domains/repo.ts
 async function runRepoView(transport, input) {
@@ -79,4 +79,4 @@ export {
   runRepoLabelsList,
   runRepoView
 };
-//# sourceMappingURL=repo-M6DKCWBG.js.map
+//# sourceMappingURL=repo-JF47JAZG.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghx-dev/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "GitHub execution router for AI agents with deterministic routing and normalized output.",
   "author": "Arye Kogan",
   "license": "MIT",
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "ajv": "^8.18.0",
-    "graphql": "^16.11.0",
+    "graphql": "^16.13.1",
     "graphql-request": "^7.3.1",
     "graphql-tag": "^2.12.6",
     "js-yaml": "^4.1.0"
@@ -77,15 +77,15 @@
     "@graphql-codegen/typescript": "^5.0.8",
     "@graphql-codegen/typescript-graphql-request": "^6.3.0",
     "@graphql-codegen/typescript-operations": "^5.0.8",
-    "@opencode-ai/sdk": "^1.2.10",
+    "@opencode-ai/sdk": "^1.2.23",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.2.3",
-    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/coverage-v8": "^3.2.4",
     "tsup": "^8.5.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^2.1.8"
+    "vitest": "^3.2.4"
   },
   "scripts": {
     "ghx": "tsx src/cli/index.ts",

package/skills/using-ghx/SKILL.md

@@ -1,10 +1,19 @@
 ---
-description: Execute GitHub operations via ghx — deterministic routing, normalized output, 70 capabilities
+name: using-ghx
+description: Executes GitHub operations via ghx. Use for all GitHub interactions instead of raw gh or gh api commands.
 ---
 
 # ghx CLI Skill
 
-**CRITICAL:** Use `ghx` for ALL GitHub operations. Do not use `gh api` or any other raw `gh` commands unless no matching ghx capability exists.
+## Authentication
+
+ghx automatically resolves your GitHub token. It checks (in order):
+1. `GITHUB_TOKEN` environment variable
+2. `GH_TOKEN` environment variable
+3. Cached token (from previous resolution)
+4. `gh auth token` (requires `gh` CLI authenticated via `gh auth login`)
+
+If you are authenticated via `gh auth login`, ghx works out of the box with no extra configuration.
 
 ## Capabilities
 
@@ -103,7 +112,16 @@ Example (submitting a review with inline comments):
 
 ```bash
 ghx run pr.reviews.submit --input - <<'EOF'
-{"owner": "acme", "name": "my-repo", "prNumber": 42, "event": "REQUEST_CHANGES", "body": "Please fix the issues.", "comments": [{"path": "src/index.ts", "line": 10, "body": "Off-by-one error here."}]}
+{
+  "owner": "acme",
+  "name": "my-repo",
+  "prNumber": 42,
+  "event": "REQUEST_CHANGES",
+  "body": "Please fix the issues.",
+  "comments": [
+    { "path": "src/index.ts", "line": 10, "body": "Off-by-one error here." }
+  ]
+}
 EOF
 ```
 
@@ -111,7 +129,7 @@ EOF
 
 ## Chain
 
-**Always use `ghx chain` when you have two or more operations to execute in a single call.** It batches steps into as few GraphQL round-trips as possible (typically one) — reducing latency and avoiding mid-sequence failures. Steps are not transactional; a `"partial"` result is possible if one step fails after another has already succeeded.
+Use `ghx chain` when you have two or more operations to run. It batches steps into as few GraphQL round-trips as possible (typically one) — reducing latency and avoiding mid-sequence failures. Steps are not transactional; a `"partial"` result is possible if one step fails after another has already succeeded.
 
 ```bash
 ghx chain --steps - <<'EOF'
@@ -125,3 +143,5 @@ EOF
 **Result:** `{ status, results[] }`. Each result: `{ task, ok, data? }` on success — `{ task, ok, error: { code, message } }` on failure.
 
 **CRITICAL:** Do not use `gh api` or any other raw `gh` commands unless no matching ghx capability exists. Always try `ghx` first.
+
+**IMPORTANT:** Always use `ghx chain` when you have two or more operations to execute in a single call!

package/dist/chunk-HEHONZTO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/gql/transport.ts"],"sourcesContent":["import { type DocumentNode, print } from \"graphql\"\nimport type { GraphQLClient, RequestDocument, RequestOptions } from \"graphql-request\"\n\nexport type GraphqlVariables = Record<string, unknown>\n\nexport type GraphqlError = {\n  message: string\n  path?: ReadonlyArray<string | number>\n  extensions?: Record<string, unknown>\n}\n\nexport type GraphqlRawResult<TData> = {\n  data: TData | undefined\n  errors: GraphqlError[] | undefined\n}\n\ntype GraphqlDocument = string | DocumentNode\ntype QueryLike = GraphqlDocument | RequestDocument\n\nexport interface GraphqlTransport {\n  execute<TData>(query: string, variables?: GraphqlVariables): Promise<TData>\n  executeRaw?<TData>(query: string, variables?: GraphqlVariables): Promise<GraphqlRawResult<TData>>\n}\n\nexport interface GraphqlClient {\n  query<TData, TVariables extends GraphqlVariables = GraphqlVariables>(\n    query: GraphqlDocument,\n    variables?: TVariables,\n  ): Promise<TData>\n  queryRaw<TData, TVariables extends GraphqlVariables = GraphqlVariables>(\n    query: GraphqlDocument,\n    variables?: TVariables,\n  ): Promise<GraphqlRawResult<TData>>\n}\n\nexport type TokenClientOptions = {\n  token: string\n  graphqlUrl?: string\n}\n\nfunction queryToString(query: QueryLike): string {\n  if (typeof query === \"string\") {\n    return query\n  }\n\n  if (typeof query === \"object\" && query !== null && \"kind\" in query) {\n    return print(query as DocumentNode)\n  }\n\n  return String(query)\n}\n\nfunction assertQuery(query: string): void {\n  if (query.trim().length === 0) {\n    throw new Error(\"GraphQL query must be non-empty\")\n  }\n}\n\nexport function createGraphqlClient(transport: GraphqlTransport): GraphqlClient {\n  return {\n    async query<TData, TVariables extends GraphqlVariables = GraphqlVariables>(\n      query: GraphqlDocument,\n      variables?: TVariables,\n    ): Promise<TData> {\n      const queryText = queryToString(query)\n      assertQuery(queryText)\n      return transport.execute<TData>(queryText, variables)\n    },\n    async queryRaw<TData, TVariables extends GraphqlVariables = GraphqlVariables>(\n      query: GraphqlDocument,\n      variables?: TVariables,\n    ): Promise<GraphqlRawResult<TData>> {\n      const queryText = queryToString(query)\n      assertQuery(queryText)\n      // Both paths normalize transport-level errors into settled results\n      try {\n        if (transport.executeRaw) {\n          return await transport.executeRaw<TData>(queryText, variables)\n        }\n        const data = await transport.execute<TData>(queryText, variables)\n        return { data, errors: undefined }\n      } catch (err) {\n        return {\n          data: undefined,\n          errors: [{ message: err instanceof Error ? err.message : String(err) }],\n        }\n      }\n    },\n  }\n}\n\nexport function createGraphqlRequestClient(transport: GraphqlTransport): GraphQLClient {\n  const client: Pick<GraphQLClient, \"request\"> = {\n    request<TData, TVariables extends object = object>(\n      documentOrOptions: RequestDocument | RequestOptions<TVariables, TData>,\n      ...variablesAndRequestHeaders: unknown[]\n    ): Promise<TData> {\n      const options =\n        typeof documentOrOptions === \"object\" &&\n        documentOrOptions !== null &&\n        \"document\" in documentOrOptions\n          ? documentOrOptions\n          : {\n              document: documentOrOptions,\n              variables: variablesAndRequestHeaders[0] as TVariables | undefined,\n            }\n\n      const queryText = queryToString(options.document)\n      assertQuery(queryText)\n      return transport.execute<TData>(queryText, options.variables as GraphqlVariables)\n    },\n  }\n\n  return client as GraphQLClient\n}\n\nconst DEFAULT_GRAPHQL_URL = \"https://api.github.com/graphql\"\n\nexport function resolveGraphqlUrl(): string {\n  if (process.env.GITHUB_GRAPHQL_URL) {\n    return process.env.GITHUB_GRAPHQL_URL\n  }\n\n  if (process.env.GH_HOST) {\n    return `https://${process.env.GH_HOST}/api/graphql`\n  }\n\n  return DEFAULT_GRAPHQL_URL\n}\n\ntype JsonPayload<TData> = {\n  data?: TData\n  errors?: GraphqlError[]\n  message?: string\n}\n\nasync function fetchGraphql<TData>(\n  url: string,\n  token: string,\n  query: string,\n  variables?: GraphqlVariables,\n): Promise<JsonPayload<TData>> {\n  const response = await fetch(url, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      authorization: `Bearer ${token}`,\n    },\n    body: JSON.stringify({ query, variables: variables ?? {} }),\n  })\n\n  if (!response.ok) {\n    let message = `GraphQL request failed (${response.status})`\n    try {\n      const body = (await response.json()) as JsonPayload<TData>\n      if (body.message) {\n        message = body.message\n      }\n    } catch {\n      // Non-JSON error body — use status-based message\n    }\n    throw new Error(message)\n  }\n\n  try {\n    return (await response.json()) as JsonPayload<TData>\n  } catch {\n    throw new Error(`GraphQL response is not valid JSON (${response.status})`)\n  }\n}\n\nexport function createTokenTransport(token: string, graphqlUrl?: string): GraphqlTransport {\n  const url = graphqlUrl ?? resolveGraphqlUrl()\n\n  return {\n    async execute<TData>(query: string, variables?: GraphqlVariables): Promise<TData> {\n      const payload = await fetchGraphql<TData>(url, token, query, variables)\n\n      if (payload.errors?.length) {\n        throw new Error(payload.errors[0]?.message ?? \"GraphQL returned errors\")\n      }\n\n      if (payload.data === undefined) {\n        throw new Error(\"GraphQL response missing data\")\n      }\n\n      return payload.data\n    },\n\n    async executeRaw<TData>(\n      query: string,\n      variables?: GraphqlVariables,\n    ): Promise<GraphqlRawResult<TData>> {\n      const payload = await fetchGraphql<TData>(url, token, query, variables)\n      return {\n        data: payload.data,\n        errors: payload.errors?.length ? payload.errors : undefined,\n      }\n    },\n  }\n}\n"],"mappings":"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","names":[]}