@gh-symphony/cli 0.0.20 → 0.0.22

package/dist/chunk-2UW7NQLX.js

@@ -0,0 +1,684 @@
+#!/usr/bin/env node
+import {
+  buildAgentInputRequiredReason,
+  createGitHubGraphQLMcpServerEntry,
+  extractEnvForCodex,
+  readAgentCredentialCache,
+  readEnvFile,
+  resolveGitHubGraphQLToken,
+  shouldReuseAgentCredentialCache,
+  writeAgentCredentialCache
+} from "./chunk-EEQQWTXS.js";
+
+// ../runtime-codex/src/runtime.ts
+import { spawn } from "child_process";
+import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+var DEFAULT_GITHUB_GIT_HOST = "github.com";
+var DEFAULT_GITHUB_GIT_USERNAME = "x-access-token";
+var STAGED_CODEX_HOME_DIRNAME = ".codex-agent";
+var DIRECT_AGENT_ENV_KEYS = [
+  "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
+  "OPENAI_ORG_ID",
+  "OPENAI_PROJECT"
+];
+var AgentRuntimeResolutionError = class extends Error {
+};
+var CODEX_PROTOCOL_EVENT_NAMES = {
+  turnStarted: "turn/started",
+  turnCompleted: "turn/completed",
+  turnFailed: "turn/failed",
+  turnCancelled: "turn/cancelled",
+  toolCallRequested: "dynamic_tool_call_request",
+  inputRequired: "item/tool/requestUserInput",
+  rateLimit: "turn/rate_limit",
+  messageDelta: "item/message/delta"
+};
+var CODEX_MESSAGE_DELTA_METHODS = /* @__PURE__ */ new Set([
+  CODEX_PROTOCOL_EVENT_NAMES.messageDelta,
+  "codex/event/agent_message_content_delta",
+  "codex/event/agent_message_delta",
+  "item/agentMessage/delta"
+]);
+var CODEX_TOKEN_USAGE_METHODS = /* @__PURE__ */ new Set([
+  "thread/tokenUsage/updated",
+  "total_token_usage",
+  "codex/event/token_count"
+]);
+function createGitHubGraphQLToolDefinition(config) {
+  const entry = createGitHubGraphQLMcpServerEntry(config);
+  return {
+    name: "github_graphql",
+    description: "Execute GitHub GraphQL queries for the active workspace so the agent can mutate project and issue state directly.",
+    command: entry.command,
+    args: entry.args,
+    env: entry.env,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "GraphQL query or mutation document."
+        },
+        variables: {
+          type: "object",
+          description: "Variables for the GraphQL document."
+        },
+        operationName: {
+          type: "string",
+          description: "Optional GraphQL operation name."
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    }
+  };
+}
+function asRecord(value) {
+  return value != null && typeof value === "object" ? value : {};
+}
+function hasOwn(record, key) {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+function hasNestedRateLimitPayload(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value;
+  const directKeys = [
+    "limit",
+    "remaining",
+    "used",
+    "reset",
+    "resetAt",
+    "resets_at",
+    "reset_at"
+  ];
+  if (directKeys.some((key) => hasOwn(record, key))) {
+    return true;
+  }
+  const preferredKeys = [
+    "rate_limits",
+    "rateLimits",
+    "rate_limit",
+    "rateLimit",
+    "result"
+  ];
+  for (const key of preferredKeys) {
+    if (hasOwn(record, key) && hasNestedRateLimitPayload(record[key])) {
+      return true;
+    }
+  }
+  return false;
+}
+function getCodexObservabilityEventName(event) {
+  return event.payload.observabilityEvent;
+}
+function normalizeCodexRuntimeEvents(message) {
+  const method = typeof message.method === "string" ? message.method : void 0;
+  if (!method) {
+    return [];
+  }
+  const params = asRecord(message.params);
+  const events = [];
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.turnStarted) {
+    events.push({
+      name: "agent.turnStarted",
+      payload: {
+        observabilityEvent: method,
+        params
+      }
+    });
+    return events;
+  }
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.toolCallRequested) {
+    events.push({
+      name: "agent.toolCallRequested",
+      payload: {
+        observabilityEvent: method,
+        params,
+        callId: typeof params.callId === "string" ? params.callId : "",
+        toolName: typeof params.tool === "string" ? params.tool : "",
+        threadId: typeof params.threadId === "string" ? params.threadId : "",
+        turnId: typeof params.turnId === "string" ? params.turnId : "",
+        arguments: params.arguments
+      }
+    });
+    return events;
+  }
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.inputRequired) {
+    events.push({
+      name: "agent.inputRequired",
+      payload: {
+        observabilityEvent: method,
+        params,
+        reason: buildAgentInputRequiredReason(params.prompt)
+      }
+    });
+    return events;
+  }
+  if (CODEX_TOKEN_USAGE_METHODS.has(method)) {
+    events.push({
+      name: "agent.tokenUsageUpdated",
+      payload: {
+        observabilityEvent: method,
+        params
+      }
+    });
+    return events;
+  }
+  if (CODEX_MESSAGE_DELTA_METHODS.has(method)) {
+    events.push({
+      name: "agent.messageDelta",
+      payload: {
+        observabilityEvent: method,
+        params,
+        delta: typeof params.delta === "string" ? params.delta : "",
+        itemId: typeof params.item_id === "string" ? params.item_id : ""
+      }
+    });
+    return events;
+  }
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.rateLimit) {
+    events.push({
+      name: "agent.rateLimit",
+      payload: {
+        observabilityEvent: method,
+        params
+      }
+    });
+    return events;
+  }
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.turnCompleted) {
+    if (hasOwn(params, "usage")) {
+      events.push({
+        name: "agent.tokenUsageUpdated",
+        payload: {
+          observabilityEvent: method,
+          params: asRecord(params.usage),
+          suppressUpdate: true
+        }
+      });
+    }
+    if (hasNestedRateLimitPayload(params)) {
+      events.push({
+        name: "agent.rateLimit",
+        payload: {
+          observabilityEvent: method,
+          params,
+          suppressUpdate: true
+        }
+      });
+    }
+    events.push({
+      name: "agent.turnCompleted",
+      payload: {
+        observabilityEvent: method,
+        params,
+        inputRequired: params.inputRequired === true
+      }
+    });
+    return events;
+  }
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.turnFailed) {
+    events.push({
+      name: "agent.turnFailed",
+      payload: {
+        observabilityEvent: method,
+        params
+      }
+    });
+    return events;
+  }
+  if (method === CODEX_PROTOCOL_EVENT_NAMES.turnCancelled) {
+    events.push({
+      name: "agent.turnCancelled",
+      payload: {
+        observabilityEvent: method,
+        params
+      }
+    });
+    return events;
+  }
+  if (method === "error") {
+    events.push({
+      name: "agent.error",
+      payload: {
+        observabilityEvent: method,
+        params,
+        error: JSON.stringify(params)
+      }
+    });
+    return events;
+  }
+  return events;
+}
+function resolveStagedCodexHome(workingDirectory) {
+  return join(workingDirectory, STAGED_CODEX_HOME_DIRNAME);
+}
+function resolvePreparedAgentEnvironment(workingDirectory, env) {
+  const preparedEnv = Object.fromEntries(
+    DIRECT_AGENT_ENV_KEYS.flatMap((key) => {
+      const value = env?.[key];
+      return typeof value === "string" && value.length > 0 ? [[key, value]] : [];
+    })
+  );
+  return {
+    ...preparedEnv,
+    CODEX_HOME: resolveStagedCodexHome(workingDirectory)
+  };
+}
+function buildCodexRuntimePlan(config) {
+  const tool = createGitHubGraphQLToolDefinition(config);
+  const gitCredentialHelper = createGitCredentialHelperEnvironment(config);
+  const shellCmd = (() => {
+    const cmd = config.agentCommand ?? "codex app-server";
+    return cmd.startsWith("bash -lc ") ? cmd.slice("bash -lc ".length) : cmd;
+  })();
+  const agentEnv = resolvePreparedAgentEnvironment(
+    config.workingDirectory,
+    config.agentEnv
+  );
+  return {
+    cwd: config.workingDirectory,
+    command: "bash",
+    args: ["-lc", shellCmd],
+    env: {
+      ...process.env,
+      ...config.extraEnv,
+      ...config.agentEnv,
+      CODEX_PROJECT_ID: config.projectId,
+      GITHUB_PROJECT_ID: config.githubProjectId ?? "",
+      GITHUB_GRAPHQL_TOOL_NAME: tool.name,
+      GITHUB_GRAPHQL_TOOL_COMMAND: [tool.command, ...tool.args].join(" "),
+      ...agentEnv,
+      ...gitCredentialHelper,
+      ...tool.env
+    },
+    tools: [tool]
+  };
+}
+function launchCodexAppServer(plan, spawnImpl = spawn) {
+  return spawnImpl(plan.command, plan.args, {
+    cwd: plan.cwd,
+    env: plan.env,
+    stdio: "pipe"
+  });
+}
+var CodexRuntimeAdapter = class {
+  constructor(config, dependencies = {}) {
+    this.config = config;
+    this.dependencies = dependencies;
+  }
+  // Event emission is intentionally deferred until the worker-owned loop is
+  // neutralized in #4. Until then, keep handler registration compatible.
+  handlers = /* @__PURE__ */ new Set();
+  plan = null;
+  child = null;
+  async prepare(_context) {
+    if (this.plan) {
+      return;
+    }
+    const agentEnv = await resolveAgentRuntimeEnvironment(
+      this.config,
+      this.dependencies,
+      this
+    );
+    await stageCodexHome(this.config, this.dependencies);
+    this.plan = buildCodexRuntimePlan({
+      ...this.config,
+      agentEnv
+    });
+  }
+  async spawnTurn(_input) {
+    if (!this.plan) {
+      await this.prepare();
+    }
+    if (!this.plan) {
+      throw new AgentRuntimeResolutionError(
+        "Codex runtime plan was not prepared before spawnTurn."
+      );
+    }
+    if (!hasRunningChild(this.child)) {
+      this.child = launchCodexAppServer(
+        this.plan,
+        this.dependencies.spawnImpl ?? spawn
+      );
+    }
+    return {
+      plan: this.plan,
+      child: this.child
+    };
+  }
+  onEvent(handler) {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+  resolveCredentials(brokerResponse) {
+    return resolvePreparedAgentEnvironment(
+      this.config.workingDirectory,
+      brokerResponse.env
+    );
+  }
+  async shutdown() {
+    terminateChildProcess(this.child);
+    this.child = null;
+    this.handlers.clear();
+  }
+  async cancel(_reason) {
+    terminateChildProcess(this.child);
+    this.child = null;
+    this.handlers.clear();
+  }
+  getPreparedPlan() {
+    return this.plan;
+  }
+};
+function createCodexRuntimeAdapter(config, dependencies = {}) {
+  return new CodexRuntimeAdapter(config, dependencies);
+}
+async function prepareCodexRuntimePlan(config, dependencies = {}) {
+  const adapter = createCodexRuntimeAdapter(config, dependencies);
+  await adapter.prepare();
+  const plan = adapter.getPreparedPlan();
+  if (!plan) {
+    throw new AgentRuntimeResolutionError(
+      "Codex runtime plan was not prepared."
+    );
+  }
+  return plan;
+}
+function createGitCredentialHelperEnvironment(config) {
+  return {
+    GITHUB_GIT_HOST: DEFAULT_GITHUB_GIT_HOST,
+    GITHUB_GIT_USERNAME: DEFAULT_GITHUB_GIT_USERNAME,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_CONFIG_COUNT: "1",
+    GIT_CONFIG_KEY_0: "credential.helper",
+    GIT_CONFIG_VALUE_0: `!node ${fileURLToPath(
+      new URL("./git-credential-helper.js", import.meta.url)
+    )}`,
+    ...config.githubToken ? {
+      GITHUB_GRAPHQL_TOKEN: config.githubToken
+    } : {},
+    ...config.githubTokenBrokerUrl ? {
+      GITHUB_TOKEN_BROKER_URL: config.githubTokenBrokerUrl
+    } : {},
+    ...config.githubTokenBrokerSecret ? {
+      GITHUB_TOKEN_BROKER_SECRET: config.githubTokenBrokerSecret
+    } : {},
+    ...config.githubTokenCachePath ? {
+      GITHUB_TOKEN_CACHE_PATH: config.githubTokenCachePath
+    } : {}
+  };
+}
+async function resolveAgentRuntimeEnvironment(config, dependencies = {}, adapter) {
+  if (config.agentEnv) {
+    return resolveRuntimeCredentials(config, { env: config.agentEnv }, adapter);
+  }
+  if (!config.agentCredentialBrokerUrl || !config.agentCredentialBrokerSecret) {
+    return resolvePreparedAgentEnvironment(config.workingDirectory);
+  }
+  const now = dependencies.now ?? /* @__PURE__ */ new Date();
+  const readFileImpl = dependencies.readFileImpl ?? readFile;
+  const cachedCredentials = config.agentCredentialCachePath ? await readAgentCredentialCache(config.agentCredentialCachePath, readFileImpl) : null;
+  if (cachedCredentials && shouldReuseAgentCredentialCache(cachedCredentials, now)) {
+    return resolveRuntimeCredentials(config, cachedCredentials, adapter);
+  }
+  const fetchImpl = dependencies.fetchImpl ?? fetch;
+  const response = await fetchImpl(config.agentCredentialBrokerUrl, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${config.agentCredentialBrokerSecret}`
+    }
+  });
+  const payload = await response.json();
+  const resolvedEnv = payload.env && response.ok ? adapter ? adapter.resolveCredentials({
+    env: payload.env,
+    expires_at: payload.expires_at
+  }) : resolvePreparedAgentEnvironment(config.workingDirectory, payload.env) : null;
+  if (!response.ok || !payload.env || Object.keys(payload.env).length === 0 || !resolvedEnv) {
+    throw new AgentRuntimeResolutionError(
+      payload.error ?? `Agent credential broker request failed with status ${response.status}.`
+    );
+  }
+  if (config.agentCredentialCachePath) {
+    const writeFileImpl = dependencies.writeFileImpl ?? writeFile;
+    await writeAgentCredentialCache(
+      config.agentCredentialCachePath,
+      payload,
+      writeFileImpl,
+      now
+    );
+  }
+  return resolvedEnv;
+}
+function resolveRuntimeCredentials(config, brokerResponse, adapter) {
+  return adapter ? adapter.resolveCredentials(brokerResponse) : resolvePreparedAgentEnvironment(config.workingDirectory, brokerResponse.env);
+}
+async function stageCodexHome(config, dependencies = {}) {
+  const codexHomeDir = resolveStagedCodexHome(config.workingDirectory);
+  const mkdirImpl = dependencies.mkdirImpl ?? mkdir;
+  await mkdirImpl(codexHomeDir, { recursive: true });
+  const writeFileImpl = dependencies.writeFileImpl ?? writeFile;
+  await writeFileImpl(
+    join(codexHomeDir, "config.toml"),
+    "# Isolated agent config \u2014 no personal MCP servers\n",
+    "utf8"
+  );
+  const realCodexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+  const copyFileImpl = dependencies.copyFileImpl ?? copyFile;
+  try {
+    await copyFileImpl(
+      join(realCodexHome, "auth.json"),
+      join(codexHomeDir, "auth.json")
+    );
+  } catch {
+  }
+}
+function hasRunningChild(child) {
+  return child !== null && child.exitCode === null && child.signalCode === null;
+}
+function terminateChildProcess(child) {
+  if (!hasRunningChild(child) || !child.pid) {
+    return;
+  }
+  try {
+    child.kill("SIGTERM");
+  } catch {
+  }
+}
+
+// ../runtime-codex/src/launcher.ts
+import { dirname, resolve } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var LocalRuntimeLauncherError = class extends Error {
+};
+function resolveLocalRuntimeLaunchConfig(env = process.env) {
+  const projectId = env.PROJECT_ID ?? env.CODEX_PROJECT_ID;
+  const workingDirectory = env.WORKING_DIRECTORY;
+  if (!projectId) {
+    throw new LocalRuntimeLauncherError(
+      "PROJECT_ID or CODEX_PROJECT_ID is required."
+    );
+  }
+  if (!workingDirectory) {
+    throw new LocalRuntimeLauncherError("WORKING_DIRECTORY is required.");
+  }
+  return {
+    projectId,
+    workingDirectory,
+    githubToken: env.GITHUB_GRAPHQL_TOKEN,
+    githubTokenBrokerUrl: env.GITHUB_TOKEN_BROKER_URL,
+    githubTokenBrokerSecret: env.GITHUB_TOKEN_BROKER_SECRET,
+    githubTokenCachePath: env.GITHUB_TOKEN_CACHE_PATH,
+    agentEnv: readDirectAgentEnvironment(env),
+    agentCredentialBrokerUrl: env.AGENT_CREDENTIAL_BROKER_URL,
+    agentCredentialBrokerSecret: env.AGENT_CREDENTIAL_BROKER_SECRET,
+    agentCredentialCachePath: env.AGENT_CREDENTIAL_CACHE_PATH,
+    githubProjectId: env.GITHUB_PROJECT_ID,
+    githubGraphqlApiUrl: env.GITHUB_GRAPHQL_API_URL,
+    agentCommand: env.SYMPHONY_AGENT_COMMAND
+  };
+}
+async function runLocalRuntimeLauncher(env = process.env) {
+  const launcherEnv = loadLauncherEnvironment(env);
+  const config = resolveLocalRuntimeLaunchConfig(launcherEnv);
+  const plan = await prepareCodexRuntimePlan(config);
+  emitLaunchSummary(config);
+  const child = launchCodexAppServer(plan);
+  process.stdout.write(
+    `[worker] codex app-server started (pid: ${child.pid ?? "unknown"})
+`
+  );
+  child.stdout?.pipe(process.stdout);
+  child.stderr?.pipe(process.stderr);
+  return await waitForChildProcess(child);
+}
+function loadLauncherEnvironment(env = process.env, cwd = process.cwd()) {
+  const mergedEnv = {
+    ...readEnvFile(
+      resolve(dirname(fileURLToPath2(import.meta.url)), "..", ".env")
+    ),
+    ...readEnvFile(resolve(cwd, ".env")),
+    ...env
+  };
+  return mergedEnv;
+}
+function readDirectAgentEnvironment(env) {
+  const agentEnv = extractEnvForCodex(env);
+  return Object.keys(agentEnv).length ? agentEnv : void 0;
+}
+function waitForChildProcess(child) {
+  return new Promise((resolve2, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        reject(
+          new LocalRuntimeLauncherError(`codex app-server exited on ${signal}.`)
+        );
+        return;
+      }
+      resolve2(code ?? 0);
+    });
+  });
+}
+async function main() {
+  const exitCode = await runLocalRuntimeLauncher(process.env);
+  process.exitCode = exitCode;
+}
+if (import.meta.url === new URL(process.argv[1] ?? "", "file:").href) {
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    process.stderr.write(`${message}
+`);
+    process.exitCode = 1;
+  });
+}
+function emitLaunchSummary(config) {
+  const githubAuthMode = config.githubToken ? "direct token" : config.githubTokenBrokerUrl && config.githubTokenBrokerSecret ? "broker" : "missing";
+  const agentAuthMode = config.agentEnv?.OPENAI_API_KEY ? "direct env" : config.agentCredentialBrokerUrl && config.agentCredentialBrokerSecret ? "broker" : "local codex auth or inherited environment";
+  process.stdout.write(
+    [
+      "[worker] starting local codex runtime",
+      `[worker] project: ${config.projectId}`,
+      `[worker] cwd: ${config.workingDirectory}`,
+      `[worker] github project: ${config.githubProjectId ?? "(unset)"}`,
+      `[worker] github auth: ${githubAuthMode}`,
+      `[worker] agent auth: ${agentAuthMode}`,
+      "[worker] note: codex app-server does not proactively read GitHub issues.",
+      "[worker] note: it waits for a client request or tool invocation."
+    ].join("\n") + "\n"
+  );
+}
+
+// ../runtime-codex/src/git-credential-helper.ts
+var DEFAULT_GITHUB_GIT_HOST2 = "github.com";
+var DEFAULT_GITHUB_GIT_USERNAME2 = "x-access-token";
+async function resolveGitCredential(request, config, fetchImpl = fetch) {
+  const requestHost = request.host?.trim();
+  const requestProtocol = request.protocol?.trim();
+  if (!requestHost || requestProtocol && requestProtocol !== "https") {
+    return "";
+  }
+  const expectedHost = normalizeGitHost(
+    config.gitHost ?? DEFAULT_GITHUB_GIT_HOST2
+  );
+  if (normalizeGitHost(requestHost) !== expectedHost) {
+    return "";
+  }
+  const token = await resolveGitHubGraphQLToken(config, {
+    fetchImpl
+  });
+  return formatGitCredentialResponse({
+    protocol: requestProtocol || "https",
+    host: requestHost,
+    username: config.gitUsername ?? DEFAULT_GITHUB_GIT_USERNAME2,
+    password: token
+  });
+}
+function parseGitCredentialRequest(rawInput) {
+  return rawInput.split("\n").map((line) => line.trim()).filter(Boolean).reduce((request, line) => {
+    const separatorIndex = line.indexOf("=");
+    if (separatorIndex === -1) {
+      return request;
+    }
+    const key = line.slice(0, separatorIndex);
+    const value = line.slice(separatorIndex + 1);
+    request[key] = value;
+    return request;
+  }, {});
+}
+function formatGitCredentialResponse(value) {
+  return `${Object.entries(value).map(([key, entry]) => `${key}=${entry}`).join("\n")}
+
+`;
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function main2() {
+  const request = parseGitCredentialRequest(await readStdin());
+  const response = await resolveGitCredential(request, {
+    token: process.env.GITHUB_GRAPHQL_TOKEN,
+    tokenBrokerUrl: process.env.GITHUB_TOKEN_BROKER_URL,
+    tokenBrokerSecret: process.env.GITHUB_TOKEN_BROKER_SECRET,
+    tokenCachePath: process.env.GITHUB_TOKEN_CACHE_PATH,
+    gitHost: process.env.GITHUB_GIT_HOST,
+    gitUsername: process.env.GITHUB_GIT_USERNAME
+  });
+  process.stdout.write(response);
+}
+if (import.meta.url === new URL(process.argv[1] ?? "", "file:").href) {
+  main2().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    process.stderr.write(`${message}
+`);
+    process.exitCode = 1;
+  });
+}
+function normalizeGitHost(host) {
+  return host.trim().toLowerCase();
+}
+
+// ../runtime-codex/src/convergence-detection.ts
+import { spawnSync } from "child_process";
+
+export {
+  getCodexObservabilityEventName,
+  normalizeCodexRuntimeEvents,
+  launchCodexAppServer,
+  prepareCodexRuntimePlan,
+  resolveLocalRuntimeLaunchConfig,
+  loadLauncherEnvironment
+};

package/dist/{chunk-MVRF7BES.js → chunk-36KYEDEO.js}

@@ -51,6 +51,14 @@ function showCursor() {
   return "\x1B[?25h";
 }
 
+// src/format/repository.ts
+function formatRepositoryDisplay(snapshot, fallback = "repository") {
+  if (snapshot.repository) {
+    return `${snapshot.repository.owner}/${snapshot.repository.name}`;
+  }
+  return snapshot.slug ?? fallback;
+}
+
 export {
   bold,
   dim,
@@ -64,5 +72,6 @@ export {
   setNoColor,
   clearScreen,
   hideCursor,
-  showCursor
+  showCursor,
+  formatRepositoryDisplay
 };