@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/lib/internal/task-lifecycle.ts

@@ -0,0 +1,41 @@
+import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.ts';
+import type { TaskLifecycleRequest } from '../task/lifecycle.ts';
+
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\n`;
+const FLAGS: Record<string, string> = {
+  '--agent': 'agent', '--reason': 'reason', '--unblock-condition': 'unblockCondition',
+  '--note': 'note', '--alert-number': 'alertNumber', '--staging-dir': 'stagingDir',
+  '--issue-number': 'issueNumber'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskLifecycle(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args.length < 2) { usageFailure('task ref and intent are required'); return; }
+  const values: Record<string, unknown> = { taskRef: args[0], intent: args[1], agent: '' };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); values.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    values[key] = key === 'alertNumber' || key === 'issueNumber' ? Number(value) : value;
+  }
+  const result = applyTaskLifecycle(values as TaskLifecycleRequest);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskLifecycle };

package/lib/internal/task-short-id.ts

@@ -0,0 +1,55 @@
+import path from 'node:path';
+
+import { detectRepoRoot } from '../task/resolve-ref.ts';
+import { configuredShortIdLength, executeShortIdCommand } from '../task/short-id.ts';
+
+const USAGE = `Usage: agent-infra-internal task-short-id <alloc|release|resolve|list> [argument] [--active-dir <path>] [--short-id-length <N>] [--verify]\n`;
+
+function failure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, output: '', error: { code: 'SHORT_ID_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskShortId(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['alloc', 'release', 'resolve', 'list'].includes(operation)) { failure('a valid short-id operation is required'); return; }
+  const positional: string[] = [];
+  let activeDir: string | null = null;
+  let shortIdLength: number | null = null;
+  let verify = false;
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const value = args[index]!;
+    if (value === '--verify') {
+      if (seen.has(value)) { failure(`duplicate option '${value}'`); return; }
+      seen.add(value); verify = true; continue;
+    }
+    if (value === '--active-dir' || value === '--short-id-length') {
+      if (seen.has(value)) { failure(`duplicate option '${value}'`); return; }
+      const optionValue = args[++index];
+      if (optionValue === undefined || optionValue.startsWith('--')) { failure(`option '${value}' requires a value`); return; }
+      seen.add(value);
+      if (value === '--active-dir') activeDir = path.resolve(optionValue);
+      else shortIdLength = Number(optionValue);
+      continue;
+    }
+    if (value.startsWith('--')) { failure(`unknown option '${value}'`); return; }
+    positional.push(value);
+  }
+  if (positional.length > (operation === 'list' ? 0 : 1)) { failure('too many positional arguments'); return; }
+  let repoRoot: string | null = null;
+  try { repoRoot = detectRepoRoot(); } catch { /* custom active-dir mode */ }
+  const resolvedActiveDir = activeDir ?? (repoRoot ? path.join(repoRoot, '.agents', 'workspace', 'active') : null);
+  if (!resolvedActiveDir) { failure('cannot determine active task directory'); return; }
+  const width = shortIdLength ?? (repoRoot ? configuredShortIdLength(repoRoot) : 2);
+  const result = executeShortIdCommand({
+    operation: operation as 'alloc' | 'release' | 'resolve' | 'list',
+    argument: positional[0], activeDir: resolvedActiveDir, shortIdLength: width, verify
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskShortId };

package/lib/internal/task-snapshot.ts

@@ -0,0 +1,32 @@
+import { collectTaskSnapshot } from '../task/snapshot.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-snapshot <N | TASK-id> [--format json|text]\n';
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SNAPSHOT_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskSnapshot(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!args[0] || args[0].startsWith('--')) { fail('task ref is required'); return; }
+  let format: 'json' | 'text' = 'json';
+  let seenFormat = false;
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index];
+    if (flag !== '--format') { fail(`unknown option '${flag}'`); return; }
+    if (seenFormat) { fail("duplicate option '--format'"); return; }
+    const value = args[++index];
+    if (value !== 'json' && value !== 'text') { fail("option '--format' requires 'json' or 'text'"); return; }
+    seenFormat = true;
+    format = value;
+  }
+  const result = collectTaskSnapshot(args[0]);
+  if (format === 'text') {
+    process.stdout.write(result.status === 'ready' ? `${result.evidence}\n` : `Snapshot failed: ${result.error?.code} - ${result.error?.message}\n`);
+  } else process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskSnapshot };

package/lib/internal/task-verify.ts

@@ -0,0 +1,33 @@
+import { renderTaskVerification, verifyTaskEvent } from '../task/verification.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text]\n';
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'VERIFY_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskVerify(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')) { fail('task ref and verification event are required'); return; }
+  let artifact: string | undefined;
+  let format: 'json' | 'text' = 'json';
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag !== '--artifact' && flag !== '--format') { fail(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { fail(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) { fail(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    if (flag === '--artifact') artifact = value;
+    else if (value === 'json' || value === 'text') format = value;
+    else { fail("option '--format' requires 'json' or 'text'"); return; }
+  }
+  const result = verifyTaskEvent({ taskRef: args[0], event: args[1], ...(artifact ? { artifact } : {}) });
+  process.stdout.write(format === 'text' ? renderTaskVerification(result) : `${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'pass' ? 0 : result.status === 'blocked' ? 2 : 1;
+}
+
+export { taskVerify };

package/lib/internal/task-warning.ts

@@ -0,0 +1,50 @@
+import { applyWorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
+import type { WorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
+
+const USAGE = `Usage: agent-infra-internal task-warning <task-ref> <add|set-status|list> [intent flags] [--dry-run]\n`;
+const FLAGS: Record<string, string> = {
+  '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
+  '--message': 'message', '--action': 'action', '--id': 'id', '--status': 'status', '--resolution': 'resolution'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'WARNING_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskWarning(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, kind] = args;
+  if (!taskRef || !kind || !['add', 'set-status', 'list'].includes(kind)) { usageFailure('task ref and a valid intent are required'); return; }
+  const values: Record<string, unknown> = { kind, taskRef };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); values.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag); values[key] = value;
+  }
+  const required: Record<string, string[]> = {
+    add: ['step', 'severity', 'code', 'target', 'message', 'action'],
+    'set-status': ['id', 'status', 'resolution'], list: []
+  };
+  const optional = kind === 'list' ? ['status'] : [];
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...optional]);
+  const unexpected = Object.keys(values).find((key) => !allowed.has(key));
+  const missing = required[kind]!.find((key) => values[key] === undefined);
+  if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
+  if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
+  const result = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskWarning };

package/lib/platform/adapters.ts

@@ -0,0 +1,30 @@
+import type { PlatformResult } from './types.ts';
+
+type PlatformAdapterContext = {
+  cwd: string;
+  gitRemote?: (cwd: string) => string | null;
+  client?: unknown;
+};
+
+type PlatformAdapter = {
+  type: string;
+  resolveContext(context: PlatformAdapterContext): PlatformResult;
+};
+
+const adapters = new Map<string, PlatformAdapter>();
+
+function registerPlatformAdapter(adapter: PlatformAdapter): void {
+  if (!adapter.type.trim()) throw new Error('Platform adapter type is required');
+  adapters.set(adapter.type, adapter);
+}
+
+function getPlatformAdapter(type: string | null): PlatformAdapter | null {
+  return type ? adapters.get(type) ?? null : null;
+}
+
+function listPlatformAdapters(): string[] {
+  return [...adapters.keys()].sort();
+}
+
+export { getPlatformAdapter, listPlatformAdapters, registerPlatformAdapter };
+export type { PlatformAdapter, PlatformAdapterContext };

package/lib/platform/context.ts

@@ -0,0 +1,164 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import semver from 'semver';
+
+import { getPlatformAdapter, registerPlatformAdapter } from './adapters.ts';
+import { createGitHubClient, MINIMUM_GITHUB_CLI_VERSION } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { platformResult } from './types.ts';
+import type { PlatformResult } from './types.ts';
+
+type ContextOptions = {
+  cwd?: string;
+  gitRemote?: (cwd: string) => string | null;
+  client?: {
+    version(options?: Parameters<GitHubClient['version']>[0]): ReturnType<GitHubClient['version']>;
+    json(args: string[], options?: Parameters<GitHubClient['json']>[1]): ReturnType<GitHubClient['json']>;
+  };
+  platformType?: string;
+};
+
+function findRepoRoot(cwd: string): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+function parseGitHubRemote(remote: string): string | null {
+  const trimmed = remote.trim().replace(/\.git$/, '');
+  const match = trimmed.match(/^(?:https?:\/\/github\.com\/|ssh:\/\/(?:git@)?github\.com\/|git@github\.com:)([^/\s]+\/[^/\s]+)$/i);
+  return match?.[1] || null;
+}
+
+function defaultGitRemote(cwd: string): string | null {
+  try {
+    return execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function readPlatformType(repoRoot: string): string | null {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+    return typeof config?.platform?.type === 'string' ? config.platform.type : null;
+  } catch {
+    return null;
+  }
+}
+
+function failure(error: { code: string; message: string; retryable: boolean }, repo: string | null): PlatformResult {
+  const blocked = error.retryable || error.code === 'AUTH_REQUIRED' || error.code === 'PLATFORM_DEPENDENCY_MISSING';
+  return platformResult(blocked ? 'blocked' : 'failed', {
+    platform: { type: 'github', repository: repo, currentUser: null }, error
+  });
+}
+
+function resolveGitHubContext(options: ContextOptions & { cwd: string }): PlatformResult {
+  const { cwd } = options;
+  const platform = 'github';
+  const client = options.client || createGitHubClient();
+  const version = client.version({ cwd });
+  if (!version.ok) return failure(version.error, null);
+  if (!semver.gte(version.value, MINIMUM_GITHUB_CLI_VERSION)) {
+    return failure({
+      code: 'GH_CLI_VERSION_UNSUPPORTED',
+      message: `GitHub CLI ${version.value} is unsupported; install gh >= ${MINIMUM_GITHUB_CLI_VERSION}`,
+      retryable: false
+    }, null);
+  }
+  const remote = (options.gitRemote || defaultGitRemote)(cwd);
+  if (!remote) {
+    return platformResult('no-op', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: { code: 'REMOTE_MISSING', message: 'Git origin remote is not configured', retryable: false }
+    });
+  }
+  const ownerRepo = parseGitHubRemote(remote);
+  if (!ownerRepo) {
+    const nonGitHub = !/github\.com/i.test(remote);
+    return platformResult(nonGitHub ? 'no-op' : 'failed', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: {
+        code: nonGitHub ? 'PLATFORM_UNSUPPORTED' : 'REMOTE_INVALID',
+        message: `Unable to parse GitHub owner/repo from '${remote}'`,
+        retryable: false
+      }
+    });
+  }
+
+  const repository = client.json(['api', `repos/${ownerRepo}`], { cwd });
+  if (!repository.ok) return failure(repository.error, null);
+  const repositoryValue = repository.value as { fork?: boolean; full_name?: string; parent?: { full_name?: string } } | null;
+  const upstream = repositoryValue?.fork ? repositoryValue.parent?.full_name : repositoryValue?.full_name;
+  if (!upstream) {
+    return platformResult('blocked', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: { code: 'UPSTREAM_UNRESOLVED', message: 'Unable to resolve the upstream repository', retryable: false }
+    });
+  }
+  const user = client.json(['api', 'user'], { cwd });
+  if (!user.ok) return failure(user.error, upstream);
+  const userValue = user.value as { login?: string } | null;
+  const permissions = client.json(['api', `repos/${upstream}`], { cwd });
+  if (!permissions.ok) return failure(permissions.error, upstream);
+  const permissionValue = permissions.value as { permissions?: Record<string, boolean> } | null;
+  const values = permissionValue?.permissions || {};
+  const capabilities = {
+    authenticated: Boolean(userValue?.login),
+    comment: Boolean(userValue?.login),
+    triage: Boolean(values.triage || values.push || values.admin),
+    push: Boolean(values.push || values.admin),
+    admin: Boolean(values.admin)
+  };
+  const status = Object.values(capabilities).every(Boolean) ? 'no-op' : 'degraded';
+  return platformResult(status, {
+    changed: false,
+    platform: { type: platform, repository: upstream, currentUser: userValue?.login || null },
+    resource: { kind: 'repository', number: null },
+    capabilities,
+    operations: [{ name: 'resolve', status: 'no-op', reasonCode: null }]
+  });
+}
+
+registerPlatformAdapter({
+  type: 'github',
+  resolveContext(options) {
+    return resolveGitHubContext(options as ContextOptions & { cwd: string });
+  }
+});
+
+registerPlatformAdapter({
+  type: 'none',
+  resolveContext() {
+    return platformResult('no-op', {
+      platform: { type: 'none', repository: null, currentUser: null },
+      operations: [{ name: 'resolve', status: 'no-op', reasonCode: 'PLATFORM_DISABLED' }]
+    });
+  }
+});
+
+function resolvePlatformContext(options: ContextOptions = {}): PlatformResult {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const repoRoot = findRepoRoot(cwd);
+  const platform = options.platformType ?? readPlatformType(repoRoot);
+  const adapter = getPlatformAdapter(platform);
+  if (!adapter) {
+    return platformResult('no-op', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: { code: 'PLATFORM_UNSUPPORTED', message: `Platform '${platform || 'none'}' has no registered adapter`, retryable: false }
+    });
+  }
+  return adapter.resolveContext({ cwd, gitRemote: options.gitRemote, client: options.client });
+}
+
+export { parseGitHubRemote, resolvePlatformContext };
+export type { ContextOptions };

package/lib/platform/github-client.ts

@@ -0,0 +1,146 @@
+import process from 'node:process';
+import spawn from 'cross-spawn';
+
+import semver from 'semver';
+
+import type { PlatformError } from './types.ts';
+
+type RunResult = { status: number | null; stdout: string; stderr: string; error?: Error };
+type RunOptions = { cwd?: string; input?: string };
+type Runner = (args: string[], options: RunOptions) => RunResult;
+type RequestOptions = RunOptions & { method?: 'GET' | 'PATCH' | 'POST' | 'DELETE' };
+type ClientResult<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
+
+type GitHubClient = {
+  version(options?: RunOptions): ClientResult<string>;
+  json<T = unknown>(args: string[], options?: RequestOptions): ClientResult<T>;
+  text(args: string[], options?: RequestOptions): ClientResult<string>;
+};
+
+type ClientOptions = {
+  runner?: Runner;
+  retryDelaysMs?: number[];
+  sleep?: (delayMs: number) => void;
+};
+
+const MINIMUM_GITHUB_CLI_VERSION = '2.16.0';
+
+function defaultRunner(args: string[], options: RunOptions): RunResult {
+  const command = process.env.AGENT_INFRA_GH_BIN || 'gh';
+  let prefix: string[] = [];
+  try {
+    prefix = JSON.parse(process.env.AGENT_INFRA_GH_ARGS_JSON || '[]') as string[];
+  } catch {
+    prefix = [];
+  }
+  const result = spawn.sync(command, [...prefix, ...args], {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    env: process.env,
+    input: options.input,
+    shell: false
+  });
+  return {
+    status: result.status,
+    stdout: String(result.stdout || ''),
+    stderr: String(result.stderr || ''),
+    error: result.error
+  };
+}
+
+function retryDelaysFromEnvironment(): number[] {
+  const raw = process.env.AGENT_INFRA_PLATFORM_RETRY_DELAYS_MS;
+  if (!raw) return [3000, 10000];
+  return raw.split(',').map(Number).filter((value) => Number.isFinite(value) && value >= 0);
+}
+
+function defaultSleep(delayMs: number): void {
+  if (delayMs <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMs);
+}
+
+function classifyGitHubFailure(result: RunResult): PlatformError {
+  const detail = `${result.stderr}\n${result.stdout}\n${result.error?.message || ''}`.trim();
+  const lower = detail.toLowerCase();
+  if (/\b401\b|bad credentials|authentication required|not logged into/.test(lower)) {
+    return { code: 'AUTH_REQUIRED', message: detail || 'GitHub authentication is required', retryable: false };
+  }
+  if (/\b429\b|rate limit|secondary rate|\b5\d\d\b|timeout|timed out|econnreset|enotfound|dns|tls|socket|network/.test(lower)) {
+    return { code: 'NETWORK_TRANSIENT', message: detail || 'GitHub request failed temporarily', retryable: true };
+  }
+  if (/\b403\b|resource not accessible|permission denied/.test(lower)) {
+    return { code: 'PERMISSION_DENIED', message: detail || 'GitHub permission denied', retryable: false };
+  }
+  if (/\b404\b/.test(lower)) {
+    return { code: 'RESOURCE_NOT_FOUND', message: detail || 'GitHub resource not found', retryable: false };
+  }
+  if (/\b422\b|validation failed/.test(lower)) {
+    return { code: 'PLATFORM_REQUEST_INVALID', message: detail || 'GitHub rejected the request', retryable: false };
+  }
+  if (result.error && 'code' in result.error && (result.error as NodeJS.ErrnoException).code === 'ENOENT') {
+    return { code: 'PLATFORM_DEPENDENCY_MISSING', message: detail || 'GitHub CLI is unavailable', retryable: false };
+  }
+  return { code: 'PLATFORM_REQUEST_FAILED', message: detail || 'GitHub request failed', retryable: false };
+}
+
+function createGitHubClient(options: ClientOptions = {}): GitHubClient {
+  const runner = options.runner || defaultRunner;
+  const delays = options.retryDelaysMs || retryDelaysFromEnvironment();
+  const sleep = options.sleep || defaultSleep;
+
+  function run(args: string[], request: RequestOptions = {}): ClientResult<string> {
+    const method = request.method || 'GET';
+    const retryableMethod = method === 'GET' || method === 'PATCH';
+    let attempt = 0;
+    while (true) {
+      const result = runner(args, request);
+      if (result.status === 0) return { ok: true, value: result.stdout };
+      const error = classifyGitHubFailure(result);
+      if (!retryableMethod || !error.retryable) return { ok: false, error };
+      if (attempt >= delays.length) {
+        return {
+          ok: false,
+          error: error.code === 'NETWORK_TRANSIENT'
+            ? { ...error, code: 'NETWORK_RETRY_EXHAUSTED', message: `${error.message} (retry exhausted)` }
+            : error
+        };
+      }
+      sleep(delays[attempt]!);
+      attempt += 1;
+    }
+  }
+
+  return {
+    version(request = {}) {
+      const result = runner(['--version'], request);
+      if (result.status !== 0) return { ok: false, error: classifyGitHubFailure(result) };
+      const version = result.stdout.match(/^gh version (\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\s|$)/m)?.[1];
+      if (!version || !semver.valid(version)) {
+        return {
+          ok: false,
+          error: { code: 'GH_CLI_VERSION_INVALID', message: 'GitHub CLI returned an invalid version', retryable: false }
+        };
+      }
+      return { ok: true, value: version };
+    },
+    text(args, request = {}) {
+      const result = run(args, request);
+      return result.ok ? { ok: true, value: result.value.trim() } : result;
+    },
+    json<T>(args: string[], request: RequestOptions = {}): ClientResult<T> {
+      const result = run(args, request);
+      if (!result.ok) return result;
+      try {
+        return { ok: true, value: JSON.parse(result.value || 'null') as T };
+      } catch {
+        return {
+          ok: false,
+          error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub returned invalid JSON', retryable: true }
+        };
+      }
+    }
+  };
+}
+
+export { classifyGitHubFailure, createGitHubClient, MINIMUM_GITHUB_CLI_VERSION };
+export type { ClientResult, GitHubClient, RequestOptions, RunOptions, RunResult, Runner };