@stigmer/cli 3.0.8

package/src/resources/execution.test.ts

@@ -0,0 +1,138 @@
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionListSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { ExecutionPhase as WorkflowExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { describe, expect, it } from "vitest";
+import { UsageError } from "../errors/index.js";
+import {
+  formatAgentPhase,
+  formatWorkflowPhase,
+  isAgentExecutionId,
+  isExecutionAlias,
+  isTerminalAgentPhase,
+  isWorkflowExecutionId,
+  renderExecutionList,
+  resolveExecutionType,
+} from "./execution.js";
+
+describe("isAgentExecutionId", () => {
+  it.each([
+    ["aex_01ARZ3NDEKTSV4RRFFQ69G5FAV", true],
+    ["aex-01ARZ3NDEKTSV4RRFFQ69G5FAV", true],
+    ["aex_", true],
+    ["AEX_run", false], // case-sensitive
+    ["agt_abc", false], // different kind
+    ["wex_run", false], // workflow, not agent
+  ])("%j -> %s", (ref, expected) => {
+    expect(isAgentExecutionId(ref)).toBe(expected);
+  });
+});
+
+describe("isWorkflowExecutionId", () => {
+  it.each([
+    ["wex_run456", true],
+    ["wex-run456", true],
+    ["WEX_run", false],
+    ["wfl_abc", false],
+    ["aex_run", false],
+  ])("%j -> %s", (ref, expected) => {
+    expect(isWorkflowExecutionId(ref)).toBe(expected);
+  });
+});
+
+describe("isExecutionAlias", () => {
+  it.each([
+    ["execution", true],
+    ["executions", true],
+    ["exec", true],
+    ["  Exec  ", true],
+    ["agent", false],
+    ["session", false],
+  ])("%j -> %s", (type, expected) => {
+    expect(isExecutionAlias(type)).toBe(expected);
+  });
+});
+
+describe("resolveExecutionType", () => {
+  it("resolves agent and workflow prefixes", () => {
+    expect(resolveExecutionType("aex_01ARZ3NDEKTSV4RRFFQ69G5FAV")).toBe("agent");
+    expect(resolveExecutionType("wex_01ARZ3NDEKTSV4RRFFQ69G5FAV")).toBe("workflow");
+  });
+
+  it("throws a usage error on an unrecognized prefix", () => {
+    expect(() => resolveExecutionType("xyz_123")).toThrow(UsageError);
+  });
+});
+
+describe("renderExecutionList", () => {
+  const list = create(AgentExecutionListSchema, {
+    totalPages: 1,
+    entries: [
+      create(AgentExecutionSchema, {
+        metadata: { id: "aex_1" },
+        spec: { agentId: "agt_1" },
+        status: { phase: ExecutionPhase.EXECUTION_IN_PROGRESS, startedAt: "2026-03-01T10:00:00Z" },
+      }),
+    ],
+  });
+  const result = { schema: AgentExecutionListSchema, message: list };
+
+  it("renders the full list envelope as protojson for json", () => {
+    const json = JSON.parse(renderExecutionList(result, "json", "agent"));
+    expect(json.total_pages).toBe(1);
+    expect(json.entries[0].metadata.id).toBe("aex_1");
+  });
+
+  it("renders a table with a friendly phase label", () => {
+    const table = renderExecutionList(result, "table", "agent");
+    expect(table).toContain("AGENT");
+    expect(table).toContain("aex_1");
+    expect(table).toContain("in-progress");
+  });
+});
+
+describe("formatAgentPhase", () => {
+  it.each([
+    [ExecutionPhase.EXECUTION_PENDING, "pending"],
+    [ExecutionPhase.EXECUTION_IN_PROGRESS, "running"],
+    [ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL, "awaiting-approval"],
+    [ExecutionPhase.EXECUTION_PAUSED, "paused"],
+    [ExecutionPhase.EXECUTION_COMPLETED, "completed"],
+    [ExecutionPhase.EXECUTION_FAILED, "failed"],
+    [ExecutionPhase.EXECUTION_CANCELLED, "cancelled"],
+    [ExecutionPhase.EXECUTION_TERMINATED, "terminated"],
+    [ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED, "unknown"],
+  ])("%s -> %s", (phase, expected) => {
+    expect(formatAgentPhase(phase)).toBe(expected);
+  });
+});
+
+describe("formatWorkflowPhase", () => {
+  it.each([
+    [WorkflowExecutionPhase.EXECUTION_PENDING, "pending"],
+    [WorkflowExecutionPhase.EXECUTION_IN_PROGRESS, "running"],
+    [WorkflowExecutionPhase.EXECUTION_COMPLETED, "completed"],
+    [WorkflowExecutionPhase.EXECUTION_FAILED, "failed"],
+    [WorkflowExecutionPhase.EXECUTION_CANCELLED, "cancelled"],
+    [WorkflowExecutionPhase.EXECUTION_TERMINATED, "terminated"],
+    [WorkflowExecutionPhase.EXECUTION_PAUSED, "paused"],
+    [WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED, "unknown"],
+  ])("%s -> %s", (phase, expected) => {
+    expect(formatWorkflowPhase(phase)).toBe(expected);
+  });
+});
+
+describe("isTerminalAgentPhase", () => {
+  it.each([
+    [ExecutionPhase.EXECUTION_COMPLETED, true],
+    [ExecutionPhase.EXECUTION_FAILED, true],
+    [ExecutionPhase.EXECUTION_CANCELLED, true],
+    [ExecutionPhase.EXECUTION_TERMINATED, true],
+    [ExecutionPhase.EXECUTION_IN_PROGRESS, false],
+    [ExecutionPhase.EXECUTION_PAUSED, false],
+    [ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL, false],
+  ])("%s -> %s", (phase, expected) => {
+    expect(isTerminalAgentPhase(phase)).toBe(expected);
+  });
+});

package/src/resources/execution.ts

@@ -0,0 +1,229 @@
+// Execution routing seam.
+//
+// Executions are not addressed through the generic resource registry: agent
+// executions (`aex_`) and workflow executions (`wex_`) are served by dedicated
+// controllers, and `delete execution` maps to a *cancel*, not a destroy. This
+// module owns the ID-prefix detection and the cancel-with-result semantics so
+// that the prefix-sniffing logic lives in exactly one place.
+//
+// Wave 2a establishes the agent-execution path consumed by `delete execution`.
+// Wave 2b extends this module with the full agent-vs-workflow routing shared by
+// `usage`, `list executions`, and `download`.
+
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionSchema, type AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  AgentExecutionListSchema,
+  CancelAgentExecutionInputSchema,
+  ListAgentExecutionsRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase as WorkflowExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import {
+  ListWorkflowExecutionsRequestSchema,
+  WorkflowExecutionListSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../errors/index.js";
+import type { OutputFormat } from "../output/index.js";
+import type { ResourceResult } from "./get-bindings.js";
+import { obj, renderListMessage, str, type TableShape } from "./render.js";
+
+const AGENT_EXECUTION_PREFIX = "aex";
+const WORKFLOW_EXECUTION_PREFIX = "wex";
+
+/** True if `ref` is an agent-execution ID (`aex_…` or `aex-…`, case-sensitive). */
+export function isAgentExecutionId(ref: string): boolean {
+  return hasKindPrefix(ref, AGENT_EXECUTION_PREFIX);
+}
+
+/** True if `ref` is a workflow-execution ID (`wex_…` or `wex-…`, case-sensitive). */
+export function isWorkflowExecutionId(ref: string): boolean {
+  return hasKindPrefix(ref, WORKFLOW_EXECUTION_PREFIX);
+}
+
+// Mirrors Go's reference.isResourceIDWithKind: a kind ID prefix followed by
+// either separator the backend accepts ("_" canonical, "-" legacy). Matching is
+// case-sensitive — "AEX_" is not an execution ID.
+function hasKindPrefix(ref: string, prefix: string): boolean {
+  const trimmed = ref.trim();
+  return trimmed.startsWith(`${prefix}_`) || trimmed.startsWith(`${prefix}-`);
+}
+
+// Terminal phases cannot be cancelled; mirrors Go's isTerminalAgentPhase.
+const TERMINAL_AGENT_PHASES: ReadonlySet<ExecutionPhase> = new Set([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+/** True when an agent phase is terminal (no further transitions). Mirrors Go's isTerminalAgentPhase. */
+export function isTerminalAgentPhase(phase: ExecutionPhase): boolean {
+  return TERMINAL_AGENT_PHASES.has(phase);
+}
+
+export interface CancelExecutionResult {
+  readonly execution: AgentExecution;
+  /** True when the execution was already terminal, so no cancel was issued. */
+  readonly wasAlreadyTerminal: boolean;
+}
+
+/**
+ * Cancel an agent execution, surfacing whether it was already in a terminal
+ * state. Mirrors Go's execution.CancelWithResult: Get first to read the phase,
+ * short-circuit if terminal, otherwise issue the cancel. Keeping the Get means
+ * the success/already-terminal distinction is decided client-side from
+ * authoritative state rather than from the cancel RPC's response alone.
+ */
+export async function cancelAgentExecution(client: Stigmer, id: string): Promise<CancelExecutionResult> {
+  const current = await client.agentExecution.get(id);
+  const phase = current.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  if (TERMINAL_AGENT_PHASES.has(phase)) {
+    return { execution: current, wasAlreadyTerminal: true };
+  }
+  const cancelled = await client.agentExecution.cancel(create(CancelAgentExecutionInputSchema, { id }));
+  return { execution: cancelled, wasAlreadyTerminal: false };
+}
+
+/**
+ * True for the `execution` type-alias family. Executions bypass the resource
+ * registry (they're addressed by `aex_`/`wex_` ID, not slug), so callers route
+ * on this predicate before the registry lookup — mirroring Go's command layer.
+ */
+export function isExecutionAlias(type: string): boolean {
+  const normalized = type.trim().toLowerCase();
+  return normalized === "execution" || normalized === "executions" || normalized === "exec";
+}
+
+/** Agent (`aex_`) vs workflow (`wex_`) execution — the two controller families. */
+export type ExecutionType = "agent" | "workflow";
+
+/**
+ * Resolve an execution ID to its type by prefix. Mirrors Go's
+ * execution.ResolveType, including the multi-line guidance on an unrecognized
+ * format. Surfaced as a usage error (bad user input).
+ */
+export function resolveExecutionType(id: string): ExecutionType {
+  if (isAgentExecutionId(id)) return "agent";
+  if (isWorkflowExecutionId(id)) return "workflow";
+  throw new UsageError(
+    `unrecognized execution ID format: ${id}\n\n` +
+      "Expected formats:\n" +
+      "  Agent execution:    aex_<26-char-ulid>\n" +
+      "  Workflow execution: wex_<26-char-ulid>",
+  );
+}
+
+/** Fetch a single execution (agent or workflow) by ID, with its schema. */
+export async function getExecution(client: Stigmer, id: string): Promise<ResourceResult> {
+  if (resolveExecutionType(id) === "agent") {
+    return { schema: AgentExecutionSchema, message: await client.agentExecution.get(id) };
+  }
+  return { schema: WorkflowExecutionSchema, message: await client.workflowExecution.get(id) };
+}
+
+/** List agent executions for the current context, paginated by `limit`. */
+export async function listAgentExecutions(client: Stigmer, limit: number): Promise<ResourceResult> {
+  const message = await client.agentExecution.list(create(ListAgentExecutionsRequestSchema, { pageSize: limit }));
+  return { schema: AgentExecutionListSchema, message };
+}
+
+/** List workflow executions for the current context, paginated by `limit`. */
+export async function listWorkflowExecutions(client: Stigmer, limit: number): Promise<ResourceResult> {
+  const message = await client.workflowExecution.list(create(ListWorkflowExecutionsRequestSchema, { pageSize: limit }));
+  return { schema: WorkflowExecutionListSchema, message };
+}
+
+const AGENT_EXECUTION_TABLE: TableShape = {
+  resourceName: "executions",
+  headers: ["ID", "AGENT", "STATUS", "STARTED"],
+  row: (json) => [
+    str(obj(json, "metadata"), "id"),
+    dash(str(obj(json, "spec"), "agent_id")),
+    phaseLabel(str(obj(json, "status"), "phase")),
+    dash(str(obj(json, "status"), "started_at")),
+  ],
+};
+
+const WORKFLOW_EXECUTION_TABLE: TableShape = {
+  resourceName: "executions",
+  headers: ["ID", "WORKFLOW", "STATUS", "STARTED"],
+  row: (json) => [
+    str(obj(json, "metadata"), "id"),
+    dash(str(obj(json, "spec"), "workflow_id")),
+    phaseLabel(str(obj(json, "status"), "phase")),
+    dash(str(obj(json, "status"), "started_at")),
+  ],
+};
+
+/** Render an execution list (json/yaml = full envelope; table = grid). */
+export function renderExecutionList(result: ResourceResult, format: OutputFormat, type: ExecutionType): string {
+  const table = type === "agent" ? AGENT_EXECUTION_TABLE : WORKFLOW_EXECUTION_TABLE;
+  return renderListMessage(result.schema, result.message, format, table);
+}
+
+// Friendly phase label from a protojson enum string (table view only — json/yaml
+// keep the canonical protojson value). "EXECUTION_IN_PROGRESS" → "in-progress".
+function phaseLabel(phase: string): string {
+  if (phase === "") return "-";
+  return phase.replace(/^EXECUTION_/, "").toLowerCase().replace(/_/g, "-");
+}
+
+function dash(value: string): string {
+  return value === "" ? "-" : value;
+}
+
+/** Human-readable agent-execution phase, matching Go's execution.FormatPhase. */
+export function formatAgentPhase(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_PENDING:
+      return "pending";
+    case ExecutionPhase.EXECUTION_IN_PROGRESS:
+      return "running";
+    case ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL:
+      return "awaiting-approval";
+    case ExecutionPhase.EXECUTION_PAUSED:
+      return "paused";
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      return "completed";
+    case ExecutionPhase.EXECUTION_FAILED:
+      return "failed";
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      return "cancelled";
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return "terminated";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * Human-readable workflow-execution phase, matching Go's
+ * execution.FormatWorkflowPhase. Workflow phases live in a *different* proto
+ * package than agent phases (the enum values differ — workflow TERMINATED is 6,
+ * agent TERMINATED is 8), so this is a deliberately separate mapping rather than
+ * a shared one. Workflows have no WAITING_FOR_APPROVAL phase (approval is a task
+ * status, not an execution phase).
+ */
+export function formatWorkflowPhase(phase: WorkflowExecutionPhase): string {
+  switch (phase) {
+    case WorkflowExecutionPhase.EXECUTION_PENDING:
+      return "pending";
+    case WorkflowExecutionPhase.EXECUTION_IN_PROGRESS:
+      return "running";
+    case WorkflowExecutionPhase.EXECUTION_COMPLETED:
+      return "completed";
+    case WorkflowExecutionPhase.EXECUTION_FAILED:
+      return "failed";
+    case WorkflowExecutionPhase.EXECUTION_CANCELLED:
+      return "cancelled";
+    case WorkflowExecutionPhase.EXECUTION_TERMINATED:
+      return "terminated";
+    case WorkflowExecutionPhase.EXECUTION_PAUSED:
+      return "paused";
+    default:
+      return "unknown";
+  }
+}

package/src/resources/get-bindings.ts

@@ -0,0 +1,61 @@
+// Binds each registry kind to its proto schema and the SDK call that fetches a
+// single resource (by ID or by org/slug reference). This is the seam between the
+// proto-kind registry and the high-level SDK sub-clients for the `get` verb;
+// the schema travels with the message so rendering stays kind-agnostic.
+
+import type { DescMessage, Message } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
+import { ProjectSchema } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/api_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../errors/index.js";
+import type { ParsedReference } from "./reference.js";
+
+export interface ResourceResult {
+  readonly schema: DescMessage;
+  readonly message: Message;
+}
+
+type Getter = (client: Stigmer, ref: ParsedReference) => Promise<ResourceResult>;
+
+const GET_BINDINGS: ReadonlyMap<ApiResourceKind, Getter> = new Map([
+  [ApiResourceKind.agent, refGetter(ApiResourceKind.agent, AgentSchema, (c) => c.agent)],
+  [ApiResourceKind.workflow, refGetter(ApiResourceKind.workflow, WorkflowSchema, (c) => c.workflow)],
+  [ApiResourceKind.mcp_server, refGetter(ApiResourceKind.mcp_server, McpServerSchema, (c) => c.mcpServer)],
+  [ApiResourceKind.project, refGetter(ApiResourceKind.project, ProjectSchema, (c) => c.project)],
+  [ApiResourceKind.skill, refGetter(ApiResourceKind.skill, SkillSchema, (c) => c.skill)],
+  [ApiResourceKind.api_key, idOnlyGetter(ApiKeySchema, (c) => c.apiKey, "API keys")],
+]);
+
+export function getterFor(kind: ApiResourceKind): Getter | undefined {
+  return GET_BINDINGS.get(kind);
+}
+
+// A resource fetchable by ID or by org/slug reference.
+interface RefClient {
+  get(id: string): Promise<Message>;
+  getByReference(ref: { org: string; slug: string; kind: number }): Promise<Message>;
+}
+
+function refGetter(kind: ApiResourceKind, schema: DescMessage, pick: (c: Stigmer) => RefClient): Getter {
+  return async (client, ref) => {
+    const sub = pick(client);
+    const message =
+      ref.kind === "id" ? await sub.get(ref.id) : await sub.getByReference({ org: ref.org, slug: ref.slug, kind });
+    return { schema, message };
+  };
+}
+
+// A resource fetchable only by ID (e.g. API keys are not slug-addressable).
+function idOnlyGetter(schema: DescMessage, pick: (c: Stigmer) => { get(id: string): Promise<Message> }, label: string): Getter {
+  return async (client, ref) => {
+    if (ref.kind !== "id") {
+      throw new UsageError(`${label} can only be fetched by ID`);
+    }
+    return { schema, message: await pick(client).get(ref.id) };
+  };
+}

package/src/resources/get.ts

@@ -0,0 +1,41 @@
+// `get` dispatch: resolve a single resource by reference. Most kinds go through
+// the registry-bound SDK sub-clients (get-bindings); organizations are a
+// special case (not org-scoped; slug lookups resolve via findMyOrganizations).
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { CliExitError, ExitCode, UsageError } from "../errors/index.js";
+import { getterFor, type ResourceResult } from "./get-bindings.js";
+import type { ParsedReference } from "./reference.js";
+
+export async function fetchResource(
+  client: Stigmer,
+  kind: ApiResourceKind,
+  ref: ParsedReference,
+): Promise<ResourceResult> {
+  if (kind === ApiResourceKind.organization) {
+    return fetchOrganization(client, ref);
+  }
+  const getter = getterFor(kind);
+  if (getter === undefined) {
+    throw new UsageError("get is not implemented for this resource type");
+  }
+  return getter(client, ref);
+}
+
+async function fetchOrganization(client: Stigmer, ref: ParsedReference): Promise<ResourceResult> {
+  if (ref.kind === "id") {
+    return { schema: OrganizationSchema, message: await client.organization.get(ref.id) };
+  }
+  // Organizations are not org-scoped, so a bare token is a slug to resolve
+  // against the caller's memberships rather than an org/slug pair.
+  const mine = await client.organization.findMyOrganizations();
+  const match = mine.entries.find(
+    (org) => org.metadata?.slug === ref.slug || org.metadata?.name === ref.slug,
+  );
+  if (match === undefined) {
+    throw new CliExitError(`organization "${ref.slug}" not found`, ExitCode.NotFound);
+  }
+  return { schema: OrganizationSchema, message: match };
+}

package/src/resources/git.ts

@@ -0,0 +1,71 @@
+// Thin wrappers over the `git` CLI (the S5 decision: shell out rather than add a
+// git library). Used for skill push provenance (local repo detection) and for
+// cloning a remote repo when pushing with --git-url.
+
+import { execFileSync } from "node:child_process";
+
+function git(args: string[], cwd?: string): string {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+
+/** Repo root (`git rev-parse --show-toplevel`), or undefined if not a repo. */
+export function getGitRepoRoot(dir: string): string | undefined {
+  try {
+    return git(["rev-parse", "--show-toplevel"], dir);
+  } catch {
+    return undefined;
+  }
+}
+
+/** URL of the `origin` remote, or undefined if none. */
+export function getGitRemoteUrl(dir: string): string | undefined {
+  try {
+    const url = git(["remote", "get-url", "origin"], dir);
+    return url === "" ? undefined : url;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Current HEAD commit SHA, or undefined on error. */
+export function getGitCommit(dir: string): string | undefined {
+  try {
+    return git(["rev-parse", "HEAD"], dir);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Current branch name, or undefined when detached or on error. */
+export function getGitBranchName(dir: string): string | undefined {
+  try {
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], dir);
+    return branch === "" || branch === "HEAD" ? undefined : branch;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Clone `gitUrl` into `destDir`, checking out `gitRef` if given. Tries a shallow
+ * `--branch` clone first (fast for tags/branches), falling back to a full clone
+ * plus checkout when the ref is a commit SHA. Mirrors Go's cloneRepository.
+ */
+export function cloneRepository(gitUrl: string, gitRef: string, destDir: string): void {
+  const args = ["clone", "--depth", "1"];
+  if (gitRef !== "") args.push("--branch", gitRef);
+  args.push(gitUrl, destDir);
+
+  try {
+    execFileSync("git", args, { stdio: ["ignore", "ignore", "pipe"] });
+    return;
+  } catch (err) {
+    if (gitRef === "") {
+      throw new Error(`failed to clone repository: ${(err as Error).message}`);
+    }
+  }
+
+  // Fallback: full clone, then checkout the ref (handles commit SHAs).
+  execFileSync("git", ["clone", gitUrl, destDir], { stdio: ["ignore", "ignore", "pipe"] });
+  execFileSync("git", ["checkout", gitRef], { cwd: destDir, stdio: ["ignore", "ignore", "pipe"] });
+}