@ghx-dev/core 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,19 +1,188 @@
-import { a as RouteSource, b as RouteReasonCode, R as ResultEnvelope } from './envelope-BpF6MNCv.js';
-export { A as AttemptMeta, c as ResultError, d as ResultMeta } from './envelope-BpF6MNCv.js';
 import { DocumentNode } from 'graphql';
 
+declare const errorCodes: {
+    readonly Auth: "AUTH";
+    readonly NotFound: "NOT_FOUND";
+    readonly Validation: "VALIDATION";
+    readonly RateLimit: "RATE_LIMIT";
+    readonly Network: "NETWORK";
+    readonly Server: "SERVER";
+    readonly AdapterUnsupported: "ADAPTER_UNSUPPORTED";
+    readonly Unknown: "UNKNOWN";
+};
+type ErrorCode = (typeof errorCodes)[keyof typeof errorCodes];
+
+declare const routeReasonCodes: readonly ["INPUT_VALIDATION", "OUTPUT_VALIDATION", "CARD_PREFERRED", "CARD_FALLBACK", "PREFLIGHT_FAILED", "ENV_CONSTRAINT", "CAPABILITY_LIMIT", "DEFAULT_POLICY"];
+type RouteReasonCode = (typeof routeReasonCodes)[number];
+
+type RouteSource = "cli" | "rest" | "graphql";
+interface ResultError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+interface AttemptMeta {
+    route: RouteSource;
+    status: "success" | "error" | "skipped";
+    error_code?: ErrorCode;
+    duration_ms?: number;
+}
+interface ResultMeta {
+    capability_id: string;
+    route_used?: RouteSource;
+    reason?: RouteReasonCode;
+    attempts?: AttemptMeta[];
+    pagination?: {
+        has_next_page?: boolean;
+        end_cursor?: string;
+        next?: unknown;
+    };
+    timings?: {
+        total_ms?: number;
+        adapter_ms?: number;
+    };
+    cost?: {
+        tokens_in?: number;
+        tokens_out?: number;
+    };
+}
+interface ResultEnvelope<TData = unknown> {
+    ok: boolean;
+    data?: TData;
+    error?: ResultError;
+    meta: ResultMeta;
+}
+type ChainStatus = "success" | "partial" | "failed";
+interface ChainStepResult {
+    task: string;
+    ok: boolean;
+    data?: unknown;
+    error?: ResultError;
+}
+interface ChainResultEnvelope {
+    status: ChainStatus;
+    results: ChainStepResult[];
+    meta: {
+        route_used: RouteSource;
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
+}
+
 type TaskId = string;
 interface TaskRequest<TInput = Record<string, unknown>> {
     task: TaskId;
     input: TInput;
 }
 
+type ExecuteTaskFn = (request: {
+    task: string;
+    input: Record<string, unknown>;
+    options?: Record<string, unknown>;
+}) => Promise<ResultEnvelope>;
+declare function createExecuteTool(deps: {
+    executeTask: ExecuteTaskFn;
+}): {
+    execute(capabilityId: string, params: Record<string, unknown>, options?: Record<string, unknown>): Promise<ResultEnvelope>;
+};
+
 type JsonSchema = Record<string, unknown>;
 interface SuitabilityRule {
     when: "always" | "env" | "params";
     predicate: string;
     reason: string;
 }
+/**
+ * Extracts a single value from a Phase 1 lookup result using a dot-notation path.
+ *
+ * Use when the mutation needs one node ID that can be resolved via a lookup query.
+ *
+ * @example
+ * ```yaml
+ * inject:
+ *   - target: pullRequestId
+ *     source: scalar
+ *     path: repository.pullRequest.id
+ * ```
+ */
+interface ScalarInject {
+    target: string;
+    source: "scalar";
+    path: string;
+}
+/**
+ * Resolves a list of human-readable names to node IDs using a Phase 1 lookup result.
+ *
+ * Matching is case-insensitive. Use when the mutation needs an array of IDs
+ * (e.g. label IDs, assignee IDs) that must be looked up by name.
+ *
+ * @example
+ * ```yaml
+ * inject:
+ *   - target: labelIds
+ *     source: map_array
+ *     from_input: labels           # input field containing list of names
+ *     nodes_path: repository.labels.nodes
+ *     match_field: name            # field on each node to match against input names
+ *     extract_field: id            # field on each node to extract as the resolved value
+ * ```
+ */
+interface MapArrayInject {
+    target: string;
+    source: "map_array";
+    from_input: string;
+    nodes_path: string;
+    match_field: string;
+    extract_field: string;
+}
+/**
+ * Passes a value directly from the step's `input` into a mutation variable.
+ *
+ * No Phase 1 lookup is required. Use when the caller already has the required node ID
+ * (e.g. the agent passes `issueId` directly), avoiding an unnecessary resolution round-trip.
+ *
+ * @example
+ * ```yaml
+ * inject:
+ *   - target: labelableId
+ *     source: input
+ *     from_input: issueId          # the input field whose value is passed through
+ * ```
+ */
+interface InputPassthroughInject {
+    target: string;
+    source: "input";
+    from_input: string;
+}
+/**
+ * Injects an explicit `null` value into a mutation variable.
+ *
+ * Use when a mutation variable must be explicitly set to `null` to clear a field
+ * (e.g. clearing a milestone from an issue by passing `milestoneId: null`).
+ *
+ * @example
+ * ```yaml
+ * inject:
+ *   - target: milestoneId
+ *     source: "null_literal"
+ * ```
+ */
+interface NullLiteralInject {
+    target: string;
+    source: "null_literal";
+}
+type InjectSpec = ScalarInject | MapArrayInject | InputPassthroughInject | NullLiteralInject;
+interface LookupSpec {
+    operationName: string;
+    documentPath: string;
+    vars: Record<string, string>;
+}
+interface ResolutionConfig {
+    lookup: LookupSpec;
+    inject: InjectSpec[];
+}
 interface OperationCard<Input = Record<string, unknown>> {
     capability_id: string;
     version: string;
@@ -33,6 +202,7 @@ interface OperationCard<Input = Record<string, unknown>> {
         limits?: {
             maxPageSize?: number;
         };
+        resolution?: ResolutionConfig;
     };
     cli?: {
         command: string;
@@ -54,12 +224,13 @@ interface OperationCard<Input = Record<string, unknown>> {
     }>;
 }
 
+type CliRunResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
 type CliCommandRunner = {
-    run(command: string, args: string[], timeoutMs: number): Promise<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    }>;
+    run(command: string, args: string[], timeoutMs: number): Promise<CliRunResult>;
 };
 
 type SafeRunnerOptions = {
@@ -67,9 +238,54 @@ type SafeRunnerOptions = {
 };
 declare function createSafeCliCommandRunner(options?: SafeRunnerOptions): CliCommandRunner;
 
+type CapabilityExplanation = {
+    capability_id: string;
+    purpose: string;
+    required_inputs: string[];
+    optional_inputs: Record<string, unknown>;
+    preferred_route: "cli" | "graphql" | "rest";
+    fallback_routes: Array<"cli" | "graphql" | "rest">;
+    output_fields: string[];
+};
+declare function explainCapability(capabilityId: string): CapabilityExplanation;
+
 declare function listOperationCards(): OperationCard[];
 declare function getOperationCard(capabilityId: string): OperationCard | undefined;
 
+type CapabilityListItem = {
+    capability_id: string;
+    description: string;
+    required_inputs: string[];
+    optional_inputs: string[];
+    optional_inputs_detail: Record<string, unknown>;
+};
+declare function listCapabilities(domain?: string): CapabilityListItem[];
+
+type GraphqlVariables = Record<string, unknown>;
+type GraphqlError = {
+    message: string;
+    path?: ReadonlyArray<string | number>;
+    extensions?: Record<string, unknown>;
+};
+type GraphqlRawResult<TData> = {
+    data: TData | undefined;
+    errors: GraphqlError[] | undefined;
+};
+type GraphqlDocument = string | DocumentNode;
+interface GraphqlTransport {
+    execute<TData>(query: string, variables?: GraphqlVariables): Promise<TData>;
+    executeRaw?<TData>(query: string, variables?: GraphqlVariables): Promise<GraphqlRawResult<TData>>;
+}
+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>>;
+}
+type TokenClientOptions = {
+    token: string;
+    graphqlUrl?: string;
+};
+declare function createGraphqlClient(transport: GraphqlTransport): GraphqlClient;
+
 type Maybe<T> = T | null;
 type InputMaybe<T> = Maybe<T>;
 type Exact<T extends {
@@ -99,6 +315,16 @@ type Scalars = {
         output: unknown;
     };
 };
+type DiffSide = string;
+type PullRequestReviewEvent = string;
+type DraftPullRequestReviewThread = {
+    body: Scalars["String"]["input"];
+    line?: InputMaybe<Scalars["Int"]["input"]>;
+    path?: InputMaybe<Scalars["String"]["input"]>;
+    side?: InputMaybe<DiffSide>;
+    startLine?: InputMaybe<Scalars["Int"]["input"]>;
+    startSide?: InputMaybe<DiffSide>;
+};
 
 type IssueCommentsListQueryVariables = Exact<{
     owner: Scalars["String"]["input"];
@@ -136,6 +362,13 @@ type PrListQueryVariables = Exact<{
     after?: InputMaybe<Scalars["String"]["input"]>;
 }>;
 
+type PrReviewSubmitMutationVariables = Exact<{
+    pullRequestId: Scalars["ID"]["input"];
+    event: PullRequestReviewEvent;
+    body?: InputMaybe<Scalars["String"]["input"]>;
+    threads?: InputMaybe<Array<DraftPullRequestReviewThread> | DraftPullRequestReviewThread>;
+}>;
+
 type PrReviewsListQueryVariables = Exact<{
     owner: Scalars["String"]["input"];
     name: Scalars["String"]["input"];
@@ -155,14 +388,6 @@ type RepoViewQueryVariables = Exact<{
     name: Scalars["String"]["input"];
 }>;
 
-type GraphqlVariables = Record<string, unknown>;
-type GraphqlDocument = string | DocumentNode;
-interface GraphqlTransport {
-    execute<TData>(query: string, variables?: GraphqlVariables): Promise<TData>;
-}
-interface GraphqlClient {
-    query<TData, TVariables extends GraphqlVariables = GraphqlVariables>(query: GraphqlDocument, variables?: TVariables): Promise<TData>;
-}
 type RepoViewInput = RepoViewQueryVariables;
 type IssueCommentsListInput = IssueCommentsListQueryVariables;
 type IssueListInput = IssueListQueryVariables;
@@ -187,27 +412,57 @@ type IssueCreateInput = {
     body?: string;
 };
 type IssueUpdateInput = {
-    issueId: string;
+    owner: string;
+    name: string;
+    issueNumber: number;
     title?: string;
     body?: string;
 };
 type IssueMutationInput = {
-    issueId: string;
+    owner: string;
+    name: string;
+    issueNumber: number;
 };
 type IssueLabelsUpdateInput = {
-    issueId: string;
+    owner: string;
+    name: string;
+    issueNumber: number;
+    labels: string[];
+};
+type IssueLabelsAddInput = {
+    owner: string;
+    name: string;
+    issueNumber: number;
     labels: string[];
 };
 type IssueAssigneesUpdateInput = {
-    issueId: string;
+    owner: string;
+    name: string;
+    issueNumber: number;
+    assignees: string[];
+};
+type IssueAssigneesAddInput = {
+    owner: string;
+    name: string;
+    issueNumber: number;
+    assignees: string[];
+};
+type IssueAssigneesRemoveInput = {
+    owner: string;
+    name: string;
+    issueNumber: number;
     assignees: string[];
 };
 type IssueMilestoneSetInput = {
-    issueId: string;
-    milestoneNumber: number | null;
+    owner: string;
+    name: string;
+    issueNumber: number;
+    milestoneNumber: number;
 };
 type IssueCommentCreateInput = {
-    issueId: string;
+    owner: string;
+    name: string;
+    issueNumber: number;
     body: string;
 };
 type IssueLinkedPrsListInput = {
@@ -243,9 +498,18 @@ type IssueViewData = {
     title: string;
     state: string;
     url: string;
+    body: string;
+    labels: string[];
+};
+type IssueListItemData = {
+    id: string;
+    number: number;
+    title: string;
+    state: string;
+    url: string;
 };
 type IssueListData = {
-    items: Array<IssueViewData>;
+    items: Array<IssueListItemData>;
     pageInfo: {
         endCursor: string | null;
         hasNextPage: boolean;
@@ -279,10 +543,22 @@ type IssueLabelsUpdateData = {
     id: string;
     labels: string[];
 };
+type IssueLabelsAddData = {
+    id: string;
+    labels: string[];
+};
 type IssueAssigneesUpdateData = {
     id: string;
     assignees: string[];
 };
+type IssueAssigneesAddData = {
+    id: string;
+    assignees: string[];
+};
+type IssueAssigneesRemoveData = {
+    id: string;
+    assignees: string[];
+};
 type IssueMilestoneSetData = {
     id: string;
     milestoneNumber: number | null;
@@ -315,6 +591,7 @@ type IssueRelationsGetData = {
 type IssueParentSetData = {
     issueId: string;
     parentIssueId: string;
+    updated: boolean;
 };
 type IssueParentRemoveData = {
     issueId: string;
@@ -323,6 +600,7 @@ type IssueParentRemoveData = {
 type IssueBlockedByData = {
     issueId: string;
     blockedByIssueId: string;
+    added?: boolean;
     removed?: boolean;
 };
 type PrViewData = {
@@ -331,9 +609,18 @@ type PrViewData = {
     title: string;
     state: string;
     url: string;
+    body: string;
+    labels: string[];
+};
+type PrListItemData = {
+    id: string;
+    number: number;
+    title: string;
+    state: string;
+    url: string;
 };
 type PrListData = {
-    items: Array<PrViewData>;
+    items: Array<PrListItemData>;
     pageInfo: {
         endCursor: string | null;
         hasNextPage: boolean;
@@ -405,6 +692,18 @@ type PrDiffListFilesData = {
         hasNextPage: boolean;
     };
 };
+type PrMergeStatusInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+};
+type PrMergeStatusData = {
+    mergeable: string | null;
+    mergeStateStatus: string | null;
+    reviewDecision: string | null;
+    isDraft: boolean;
+    state: string;
+};
 type ReviewThreadMutationInput = {
     threadId: string;
 };
@@ -415,6 +714,29 @@ type ReviewThreadMutationData = {
     id: string;
     isResolved: boolean;
 };
+type DraftComment = {
+    path: string;
+    body: string;
+    line: number;
+    side?: "LEFT" | "RIGHT";
+    startLine?: number;
+    startSide?: "LEFT" | "RIGHT";
+};
+type PrReviewSubmitInput = {
+    owner: string;
+    name: string;
+    prNumber: number;
+    event: PrReviewSubmitMutationVariables["event"];
+    body?: string;
+    comments?: DraftComment[];
+};
+type PrReviewSubmitData = {
+    id: string;
+    state: string;
+    url: string;
+    body: string | null;
+};
+
 interface GithubClient extends GraphqlClient {
     fetchRepoView(input: RepoViewInput): Promise<RepoViewData>;
     fetchIssueCommentsList(input: IssueCommentsListInput): Promise<IssueCommentsListData>;
@@ -424,7 +746,10 @@ interface GithubClient extends GraphqlClient {
     reopenIssue(input: IssueMutationInput): Promise<IssueMutationData>;
     deleteIssue(input: IssueMutationInput): Promise<IssueMutationData>;
     updateIssueLabels(input: IssueLabelsUpdateInput): Promise<IssueLabelsUpdateData>;
+    addIssueLabels(input: IssueLabelsAddInput): Promise<IssueLabelsAddData>;
     updateIssueAssignees(input: IssueAssigneesUpdateInput): Promise<IssueAssigneesUpdateData>;
+    addIssueAssignees(input: IssueAssigneesAddInput): Promise<IssueAssigneesAddData>;
+    removeIssueAssignees(input: IssueAssigneesRemoveInput): Promise<IssueAssigneesRemoveData>;
     setIssueMilestone(input: IssueMilestoneSetInput): Promise<IssueMilestoneSetData>;
     createIssueComment(input: IssueCommentCreateInput): Promise<IssueCommentCreateData>;
     fetchIssueLinkedPrs(input: IssueLinkedPrsListInput): Promise<IssueLinkedPrsListData>;
@@ -440,31 +765,45 @@ interface GithubClient extends GraphqlClient {
     fetchPrCommentsList(input: PrCommentsListInput): Promise<PrCommentsListData>;
     fetchPrReviewsList(input: PrReviewsListInput): Promise<PrReviewsListData>;
     fetchPrDiffListFiles(input: PrDiffListFilesInput): Promise<PrDiffListFilesData>;
+    fetchPrMergeStatus(input: PrMergeStatusInput): Promise<PrMergeStatusData>;
     replyToReviewThread(input: ReplyToReviewThreadInput): Promise<ReviewThreadMutationData>;
     resolveReviewThread(input: ReviewThreadMutationInput): Promise<ReviewThreadMutationData>;
     unresolveReviewThread(input: ReviewThreadMutationInput): Promise<ReviewThreadMutationData>;
+    submitPrReview(input: PrReviewSubmitInput): Promise<PrReviewSubmitData>;
 }
-declare function createGraphqlClient(transport: GraphqlTransport): GraphqlClient;
-type TokenClientOptions = {
-    token: string;
-    graphqlUrl?: string;
-};
-/**
- * Create a GithubClient from a token string or options object.
- * Reads GITHUB_GRAPHQL_URL and GH_HOST from env for enterprise support.
- */
 declare function createGithubClientFromToken(tokenOrOptions: string | TokenClientOptions): GithubClient;
 declare function createGithubClient(transport: GraphqlTransport): GithubClient;
 
+interface ResolutionCache {
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown): void;
+    clear(): void;
+    /** Current store size; may include expired entries due to lazy eviction. */
+    readonly size: number;
+}
+interface ResolutionCacheOptions {
+    /** Time-to-live in milliseconds. Default: 60 000 (1 min). */
+    ttlMs?: number;
+    /** Maximum number of cached entries. Default: 200. */
+    maxEntries?: number;
+}
+declare function createResolutionCache(opts?: ResolutionCacheOptions): ResolutionCache;
+declare function buildCacheKey(operationName: string, variables: Record<string, unknown>): string;
+
 type ExecutionDeps = {
-    githubClient: Pick<GithubClient, "fetchRepoView" | "fetchIssueCommentsList" | "fetchIssueList" | "fetchIssueView" | "fetchPrList" | "fetchPrView" | "fetchPrCommentsList" | "fetchPrReviewsList" | "fetchPrDiffListFiles" | "replyToReviewThread" | "resolveReviewThread" | "unresolveReviewThread">;
+    githubClient: GithubClient;
     githubToken?: string | null;
     cliRunner?: CliCommandRunner;
     ghCliAvailable?: boolean;
     ghAuthenticated?: boolean;
     skipGhPreflight?: boolean;
     reason?: RouteReasonCode;
+    resolutionCache?: ResolutionCache;
 };
 declare function executeTask(request: TaskRequest, deps: ExecutionDeps): Promise<ResultEnvelope>;
+declare function executeTasks(requests: Array<{
+    task: string;
+    input: Record<string, unknown>;
+}>, deps: ExecutionDeps): Promise<ChainResultEnvelope>;
 
-export { type CliCommandRunner, type GithubClient, type GraphqlClient, type GraphqlTransport, ResultEnvelope, RouteReasonCode, RouteSource, type TaskRequest, type TokenClientOptions, createGithubClient, createGithubClientFromToken, createGraphqlClient, createSafeCliCommandRunner, executeTask, getOperationCard, 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, buildCacheKey, createExecuteTool, createGithubClient, createGithubClientFromToken, createGraphqlClient, createResolutionCache, createSafeCliCommandRunner, executeTask, executeTasks, explainCapability, getOperationCard, listCapabilities, listOperationCards };

package/dist/index.js

@@ -1,21 +1,49 @@
 import {
+  buildCacheKey,
   createGithubClient,
   createGithubClientFromToken,
-  createGraphqlClient,
+  createResolutionCache,
   createSafeCliCommandRunner,
-  executeTask
-} from "./chunk-PJ2JKKQE.js";
-import {
+  executeTask,
+  executeTasks,
+  explainCapability,
   getOperationCard,
+  listCapabilities,
   listOperationCards
-} from "./chunk-OL4ARD3R.js";
+} from "./chunk-3P3KHWFU.js";
+import "./chunk-Q7RCIK2C.js";
+import "./chunk-3DU2WHXF.js";
+import "./chunk-TDABI6C7.js";
+import {
+  createGraphqlClient
+} from "./chunk-HEHONZTO.js";
+
+// src/core/execute/execute-tool.ts
+function createExecuteTool(deps) {
+  return {
+    execute(capabilityId, params, options) {
+      const request = {
+        task: capabilityId,
+        input: params,
+        ...options ? { options } : {}
+      };
+      return deps.executeTask(request);
+    }
+  };
+}
 export {
+  buildCacheKey,
+  createExecuteTool,
   createGithubClient,
   createGithubClientFromToken,
   createGraphqlClient,
+  createResolutionCache,
   createSafeCliCommandRunner,
   executeTask,
+  executeTasks,
+  explainCapability,
   getOperationCard,
+  listCapabilities,
   listOperationCards
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","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\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":[]}