@ghx-dev/core 0.2.1 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ghx",
   "description": "GitHub execution router for AI agents — 70 capabilities with deterministic routing and normalized output",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "author": {
     "name": "Arye Kogan"
   },

package/README.md

@@ -1,283 +1,120 @@
-# @ghx-dev/core
+<h1 align="center">@ghx-dev/core</h1>
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/aryeko/ghx/main/assets/branding/social/ghx-social-dark-1280x640.png" alt="ghx social preview" width="480">
 </p>
 
+<p align="center">
+  A typed GitHub execution router that gives AI agents deterministic, token-efficient access to the GitHub API.
+</p>
+
 [![npm version](https://img.shields.io/npm/v/%40ghx-dev%2Fcore)](https://www.npmjs.com/package/@ghx-dev/core)
 [![npm downloads](https://img.shields.io/npm/dm/%40ghx-dev%2Fcore)](https://www.npmjs.com/package/@ghx-dev/core)
 [![CI (main)](https://github.com/aryeko/ghx/actions/workflows/ci-main.yml/badge.svg)](https://github.com/aryeko/ghx/actions/workflows/ci-main.yml)
 [![codecov](https://codecov.io/gh/aryeko/ghx/graph/badge.svg?token=KBIGR138V7)](https://codecov.io/gh/aryeko/ghx)
 [![License](https://img.shields.io/npm/l/%40ghx-dev%2Fcore)](https://github.com/aryeko/ghx/blob/main/LICENSE)
 
-Typed GitHub execution router for AI agents. Deterministic routing across CLI and GraphQL, runtime schema validation, and a stable result envelope -- so agents stop wasting tokens re-discovering GitHub API surfaces.
-
-## Why ghx
-
-Agents instructed to "use `gh` CLI" for common PR and issue operations waste significant tokens on research, trial-and-error, and output parsing. Benchmarked across 40 runs on standard PR and issue workflows (MCP mode benchmark coming soon):
-
-| Metric | Improvement |
-|---|---|
-| Tool calls | **-55%** (PR review), **-47%** (issue triage) |
-| Active tokens | **-88%** (PR review), **-41%** (thread resolution) |
-| Latency | **-57%** (PR review), **-26%** (thread resolution) |
-| Success rate | **100%** both modes |
-
-Full report: [Codex 5.3 Benchmark](https://github.com/aryeko/ghx/blob/main/reports/codex-5.3-benchmark/README.md)
-
-## Installation
-
-Requirements: Node.js `22+`, `gh` CLI authenticated (`gh auth status`).
-
-```bash
-npm install @ghx-dev/core
-```
-
-Alternative package managers:
-
-```bash
-pnpm add @ghx-dev/core
-# or
-yarn add @ghx-dev/core
+## Why ghx?
+
+When AI agents use the `gh` CLI directly, they waste thousands of tokens on research, trial-and-error formatting, and guessing JSON parsing paths. **ghx eliminates this waste** by providing a stable, structured execution layer.
+
+> **100% success rate, 73% fewer tool calls, 18% fewer active tokens, 54% lower latency** compared to raw CLI usage ([measured across 30 runs](https://github.com/aryeko/ghx/blob/main/docs/eval-report.md) on standard PR workflows with Codex 5.3).
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant ghx as ghx
+    participant GH as GitHub API
+
+    %% Agent requests a typed execution
+    Agent->>ghx: executeTask("pr.view", { owner, name, prNumber })
+    
+    %% ghx routing engine takes over
+    Note over ghx: 1. Validate input schema<br/>2. Select optimal route (GraphQL/CLI)<br/>3. Run preflight checks
+    ghx->>GH: typed GraphQL request
+    GH-->>ghx: response
+    Note over ghx: normalize errors & structure
+    
+    %% Stable envelope returned
+    ghx-->>Agent: ResultEnvelope { ok: true, data: { ... } }
 ```
 
-Or run directly without installing:
+## Features
 
-```bash
-npx @ghx-dev/core capabilities list
-```
+- **70+ Declarative Capabilities**: PRs, issues, labels, workflows, projects, releases — all defined by versioned YAML operation cards.
+- **Deterministic Routing**: The agent doesn't choose CLI vs. GraphQL. ghx evaluates suitability rules and picks the optimal route automatically, with built-in fallbacks.
+- **Stable Result Envelope**: No try/catch needed. Every execution returns `{ ok, data, error, meta }`. Errors are mapped to standard codes (`AUTH`, `RATE_LIMIT`, `NOT_FOUND`, etc.).
+- **Chaining & Batching**: Execute multiple steps (`add label`, `add assignee`, `comment`) in one call. ghx resolves node IDs and batches them into a single network request.
+- **Type Safety**: Full TypeScript schemas for inputs and outputs (via generated GraphQL types).
 
-Global CLI install:
-
-```bash
-npm i -g @ghx-dev/core
-```
-
-## Quick Start (CLI)
-
-Set `GITHUB_TOKEN` or `GH_TOKEN` in your environment, then:
-
-```bash
-npx @ghx-dev/core capabilities list
-npx @ghx-dev/core capabilities explain repo.view
-npx @ghx-dev/core run repo.view --input '{"owner":"aryeko","name":"ghx"}'
-```
-
-If installed globally, replace `npx @ghx-dev/core` with `ghx`.
-
-Every capability returns a stable envelope:
+## Documentation
 
-```json
-{
-  "ok": true,
-  "data": {
-    "id": "R_kgDOOx...",
-    "name": "ghx",
-    "nameWithOwner": "aryeko/ghx"
-  },
-  "error": null,
-  "meta": {
-    "capability_id": "repo.view",
-    "route_used": "cli",
-    "reason": "CARD_PREFERRED"
-  }
-}
-```
+Comprehensive documentation is available in the [`docs/`](./docs/) directory:
 
-## Chain: Batch Operations
+- **[Getting Started](./docs/getting-started/README.md)** — Installation, why ghx, and use case diagrams.
+  - [Library Quickstart](./docs/getting-started/library-quickstart.md)
+  - [CLI Quickstart](./docs/getting-started/cli-quickstart.md)
+  - [Agent Setup](./docs/getting-started/agent-setup.md)
+- **[Concepts](./docs/concepts/README.md)** — How ghx works internally (Routing Engine, Operation Cards, Result Envelope, Chaining).
+- **[Architecture](./docs/architecture/README.md)** — System design, execution pipeline, formatters, and GraphQL layer.
+- **[Reference](./docs/reference/README.md)** — API exports, error codes, and a complete table of all 70+ capabilities.
 
-Batch multiple operations into a single tool call:
+## Quick Start (Library)
 
 ```bash
-ghx chain --steps - <<'EOF'
-[
-  {"task":"issue.labels.remove","input":{"owner":"acme","name":"repo","issueNumber":42,"labels":["triage"]}},
-  {"task":"issue.labels.add","input":{"owner":"acme","name":"repo","issueNumber":42,"labels":["enhancement"]}},
-  {"task":"issue.comments.create","input":{"owner":"acme","name":"repo","issueNumber":42,"body":"Triaged."}}
-]
-EOF
+npm install @ghx-dev/core
 ```
 
-## Quick Start (Library API)
-
 ```ts
 import { createGithubClientFromToken, executeTask } from "@ghx-dev/core"
 
 const token = process.env.GITHUB_TOKEN!
 const githubClient = createGithubClientFromToken(token)
 
+// Execute a task: input is validated, optimal route is chosen
 const result = await executeTask(
   { task: "repo.view", input: { owner: "aryeko", name: "ghx" } },
   { githubClient, githubToken: token },
 )
 
 if (result.ok) {
-  console.log(result.data)
+  console.log("Success:", result.data.nameWithOwner)
+  console.log("Route used:", result.meta.route_used) // e.g. "graphql"
 } else {
-  console.error(result.error?.code, result.error?.message)
+  console.error("Failed:", result.error.code) // e.g. "NOT_FOUND"
+  console.error("Retryable?", result.error.retryable)
 }
 ```
 
-Need a custom GraphQL transport? See [Custom GraphQL Transport](#custom-graphql-transport).
-
-## Agent Onboarding
+## Quick Start (CLI)
 
-<details>
-<summary>Install ghx as a project skill for Claude Code</summary>
+Use ghx directly from your terminal or add it as an agent skill.
 
 ```bash
-npx @ghx-dev/core setup --scope project --yes
-npx @ghx-dev/core setup --scope project --verify
-```
-
-The canonical setup skill content is stored in `skills/using-ghx/SKILL.md` (package root). During build/publish it is copied to `dist/skills/using-ghx/SKILL.md`. `ghx setup` writes this content to `.agents/skills/ghx/SKILL.md` in user or project scope.
-
-</details>
-
-## Agent Tools
-
-```ts
-import {
-  createExecuteTool,
-  createGithubClientFromToken,
-  executeTask,
-  explainCapability,
-  listCapabilities,
-} from "@ghx-dev/core"
-
-// Wire the execute tool to the real engine
-const token = process.env.GITHUB_TOKEN!
-const githubClient = createGithubClientFromToken(token)
-
-const tool = createExecuteTool({
-  executeTask: (request) => executeTask(request, { githubClient, githubToken: token }),
-})
-
-// Discover and execute capabilities
-console.log(listCapabilities())
-console.log(explainCapability("repo.view"))
-const result = await tool.execute("repo.view", { owner: "aryeko", name: "ghx" })
-```
-
-## 70 Capabilities
-
-| Domain | Count | Examples |
-|---|---|---|
-| Repository | 3 | `repo.view`, `repo.labels.list` |
-| Issues | 23 | create/update/close, labels, assignees, milestones, relations |
-| Pull Requests | 21 | diff, threads, reviews, checks, merge, branch update |
-| Workflows and CI | 11 | runs, jobs, logs, dispatch, rerun, cancel, artifacts |
-| Releases | 5 | view, list, create, update, publish |
-| Projects v2 | 7 | items, fields, add/remove issues |
-
-Full list: `ghx capabilities list` or [operation card registry](https://github.com/aryeko/ghx/tree/main/packages/core/src/core/registry/cards).
-
-## Result Envelope
+# List all 70+ capabilities
+npx @ghx-dev/core capabilities list
 
-All execution paths resolve to:
+# Run a capability
+npx @ghx-dev/core run pr.view --input '{"owner":"aryeko","name":"ghx","number":42}'
 
-```ts
-type ResultEnvelope<TData = unknown> = {
-  ok: boolean
-  data?: TData
-  error?: {
-    code: string      // AUTH, NOT_FOUND, RATE_LIMIT, VALIDATION, ...
-    message: string
-    retryable: boolean
-    details?: Record<string, unknown>
-  }
-  meta: {
-    capability_id: string
-    route_used?: "cli" | "graphql" | "rest"
-    reason?: string
-    attempts?: Array<{
-      route: "cli" | "graphql" | "rest"
-      status: "success" | "error" | "skipped"
-      error_code?: string
-      duration_ms?: number
-    }>
-  }
-}
+# Output is a standard ResultEnvelope:
+# {
+#   "ok": true,
+#   "data": { ... },
+#   "meta": { "capability_id": "pr.view", "route_used": "graphql", ... }
+# }
 ```
 
-## Environment Variables
-
-- `GITHUB_TOKEN` or `GH_TOKEN` (required)
-- `GITHUB_GRAPHQL_URL` (optional; override GraphQL endpoint)
-- `GH_HOST` (optional; derives enterprise GraphQL endpoint)
-
-## Security and Permissions
-
-- Start with least privilege and grant only what your capability set needs.
-- For quick local testing, a classic PAT with `repo` scope is the simplest route.
-- For production agents, prefer fine-grained tokens with read permissions first (`Metadata`, `Contents`, `Pull requests`, `Issues`, `Actions`, `Projects`) and add writes only where needed.
+## Agent Integration
 
-## Compatibility
+To install the `ghx` skill for Claude Code:
 
-- Node.js `22+`
-- GitHub Cloud and GitHub Enterprise hosts (`GH_HOST` supported)
-- Route adapters: CLI and GraphQL
-
-<details>
-<summary>Public Exports</summary>
-
-Root (`@ghx-dev/core`):
-
-- `executeTask` -- run a capability
-- `createGithubClientFromToken` -- create a client from a token string
-- `createGithubClient`, `createGraphqlClient` -- create clients from a custom transport
-- `listOperationCards`, `getOperationCard` -- inspect capability registry
-- `createSafeCliCommandRunner` -- custom CLI execution
-- Types: `TaskRequest`, `ResultEnvelope`, `ResultError`, `ResultMeta`, `AttemptMeta`, `RouteSource`, `RouteReasonCode`, `TokenClientOptions`
-
-Subpaths:
-
-- `@ghx-dev/core/cli` -- CLI entrypoint
-
-</details>
-
-<details>
-<a id="custom-graphql-transport"></a>
-<summary>Custom GraphQL Transport</summary>
-
-For full control over the GraphQL layer, pass your own transport to `createGithubClient`:
-
-```ts
-import { createGithubClient, executeTask } from "@ghx-dev/core"
-
-const githubClient = createGithubClient({
-  async execute<TData>(query: string, variables?: Record<string, unknown>): Promise<TData> {
-    const response = await fetch("https://api.github.com/graphql", {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
-      },
-      body: JSON.stringify({ query, variables: variables ?? {} }),
-    })
-    const payload = (await response.json()) as { data?: TData; errors?: Array<{ message?: string }> }
-    if (payload.errors?.length) throw new Error(payload.errors[0]?.message ?? "GraphQL error")
-    if (payload.data === undefined) throw new Error("GraphQL response missing data")
-    return payload.data
-  },
-})
-
-const result = await executeTask(
-  { task: "repo.view", input: { owner: "aryeko", name: "ghx" } },
-  { githubClient, githubToken: process.env.GITHUB_TOKEN },
-)
+```bash
+npx @ghx-dev/core setup --scope project --yes
 ```
 
-</details>
-
-## Documentation
-
-- [Documentation Hub](https://github.com/aryeko/ghx/blob/main/docs/README.md)
-- [Architecture](https://github.com/aryeko/ghx/blob/main/docs/architecture/README.md)
-- [Capabilities Reference](https://github.com/aryeko/ghx/blob/main/docs/capabilities/README.md)
-- [Operation Cards](https://github.com/aryeko/ghx/blob/main/docs/architecture/operation-cards.md)
-- [Publishing Guide](https://github.com/aryeko/ghx/blob/main/docs/contributing/publishing.md)
+This installs `.agents/skills/ghx/SKILL.md` which teaches Claude how to use `npx @ghx-dev/core` for reliable GitHub interactions.
 
 ## License
 
-MIT - https://github.com/aryeko/ghx/blob/main/LICENSE
+MIT

package/dist/{chunk-M5PJLKL5.js → chunk-7A73AXLY.js}

@@ -76,7 +76,7 @@ import {
 import {
   createGraphqlClient,
   createTokenTransport
-} from "./chunk-HEHONZTO.js";
+} from "./chunk-C2KRRSSX.js";
 
 // src/core/execution/cli/safe-runner.ts
 import { spawn } from "child_process";
@@ -180,9 +180,97 @@ function createSafeCliCommandRunner(options) {
   };
 }
 
+// src/core/auth/resolve-token.ts
+import { statSync } from "fs";
+import { mkdir, readFile, rename, unlink, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var GH_AUTH_TIMEOUT_MS = 5e3;
+function resolveHostname() {
+  return process.env.GH_HOST || "github.com";
+}
+function resolveCacheDir() {
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+  return join(base, "ghx", "tokens");
+}
+function resolveCachePath() {
+  return join(resolveCacheDir(), resolveHostname());
+}
+async function readCachedToken() {
+  const cachePath = resolveCachePath();
+  try {
+    const stat = statSync(cachePath);
+    if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+  try {
+    const content = await readFile(cachePath, "utf8");
+    const trimmed = content.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  } catch {
+    return null;
+  }
+}
+async function writeCachedToken(token) {
+  const cacheDir = resolveCacheDir();
+  const cachePath = resolveCachePath();
+  const tmpPath = `${cachePath}.${process.pid}.tmp`;
+  await mkdir(cacheDir, { recursive: true, mode: 448 });
+  await writeFile(tmpPath, token, { mode: 384 });
+  await rename(tmpPath, cachePath);
+}
+async function resolveFromGhCli() {
+  const runner = createSafeCliCommandRunner();
+  const hostname = resolveHostname();
+  const args = hostname === "github.com" ? ["auth", "token"] : ["auth", "token", "--hostname", hostname];
+  try {
+    const result = await runner.run("gh", args, GH_AUTH_TIMEOUT_MS);
+    if (result.exitCode !== 0) {
+      return null;
+    }
+    const token = result.stdout.trim();
+    return token.length > 0 ? token : null;
+  } catch {
+    return null;
+  }
+}
+async function resolveGithubToken() {
+  const githubToken = process.env.GITHUB_TOKEN?.trim();
+  if (githubToken && githubToken.length > 0) {
+    return { token: githubToken, source: "env" };
+  }
+  const ghToken = process.env.GH_TOKEN?.trim();
+  if (ghToken && ghToken.length > 0) {
+    return { token: ghToken, source: "env" };
+  }
+  const cached = await readCachedToken();
+  if (cached !== null) {
+    return { token: cached, source: "cache" };
+  }
+  const ghCliToken = await resolveFromGhCli();
+  if (ghCliToken !== null) {
+    await writeCachedToken(ghCliToken).catch(() => {
+    });
+    return { token: ghCliToken, source: "gh-cli" };
+  }
+  throw new Error(
+    "GitHub token not found. Set GITHUB_TOKEN or GH_TOKEN environment variable, or authenticate with: gh auth login"
+  );
+}
+async function invalidateTokenCache() {
+  try {
+    await unlink(resolveCachePath());
+  } catch {
+  }
+}
+
 // src/core/registry/index.ts
 import { readdirSync, readFileSync } from "fs";
-import { dirname, extname, join } from "path";
+import { dirname, extname, join as join2 } from "path";
 import { fileURLToPath } from "url";
 import { load as parseYaml } from "js-yaml";
 
@@ -381,7 +469,7 @@ var operationCardSchema = {
 var validateCard = ajv.compile(operationCardSchema);
 function cardDirectory() {
   const currentDir = dirname(fileURLToPath(import.meta.url));
-  return join(currentDir, "cards");
+  return join2(currentDir, "cards");
 }
 function loadCardsFromYaml() {
   const directory = cardDirectory();
@@ -472,7 +560,7 @@ function loadCardsFromYaml() {
     return a.localeCompare(b);
   });
   return entries.map((entry) => {
-    const filePath = join(directory, entry);
+    const filePath = join2(directory, entry);
     const raw = readFileSync(filePath, "utf8");
     const parsed = parseYaml(raw);
     const validation = validateOperationCard(parsed);
@@ -745,7 +833,7 @@ function createLogger(config) {
   }
   function write(level, msg, ctx) {
     if (levelIndex(level) < minIndex) return;
-    const version = true ? "0.2.1" : "unknown";
+    const version = true ? "0.3.0" : "unknown";
     const entry = {
       ts: (/* @__PURE__ */ new Date()).toISOString(),
       pid: config.pid,
@@ -856,7 +944,7 @@ function assembleChainResult(input) {
       };
     }
     if (alias in mutationRawResult) {
-      return { task: req.task, ok: true, data: mutationRawResult[alias] };
+      return { task: req.task, ok: true };
     }
     if (alias in queryRawResult) {
       return { task: req.task, ok: true, data: queryRawResult[alias] };
@@ -6049,13 +6137,13 @@ function createGithubClient(transport) {
   let prMutations;
   let release;
   let project;
-  const loadRepo = async () => repo ??= await import("./repo-M6DKCWBG.js");
-  const loadIssueQueries = async () => issueQueries ??= await import("./issue-queries-ORG3VPK4.js");
-  const loadIssueMutations = async () => issueMutations ??= await import("./issue-mutations-OW464JP3.js");
-  const loadPrQueries = async () => prQueries ??= await import("./pr-queries-6CJJW7BT.js");
-  const loadPrMutations = async () => prMutations ??= await import("./pr-mutations-WOTG6FAB.js");
-  const loadRelease = async () => release ??= await import("./release-33236BBA.js");
-  const loadProject = async () => project ??= await import("./project-QFSCYDDW.js");
+  const loadRepo = async () => repo ??= await import("./repo-JF47JAZG.js");
+  const loadIssueQueries = async () => issueQueries ??= await import("./issue-queries-YQL65J7X.js");
+  const loadIssueMutations = async () => issueMutations ??= await import("./issue-mutations-DIWPF3JH.js");
+  const loadPrQueries = async () => prQueries ??= await import("./pr-queries-NUL2UZJB.js");
+  const loadPrMutations = async () => prMutations ??= await import("./pr-mutations-BVHDCAPR.js");
+  const loadRelease = async () => release ??= await import("./release-IQCWD655.js");
+  const loadProject = async () => project ??= await import("./project-3ZSPVIOC.js");
   return {
     query: (query, variables) => graphqlClient.query(query, variables),
     queryRaw: (query, variables) => graphqlClient.queryRaw(query, variables),
@@ -6116,6 +6204,8 @@ function createGithubClient(transport) {
 
 export {
   createSafeCliCommandRunner,
+  resolveGithubToken,
+  invalidateTokenCache,
   listOperationCards,
   getOperationCard,
   extractArrayItemHints,
@@ -6129,4 +6219,4 @@ export {
   createGithubClientFromToken,
   createGithubClient
 };
-//# sourceMappingURL=chunk-M5PJLKL5.js.map
+//# sourceMappingURL=chunk-7A73AXLY.js.map