@studio-foundation/api 0.3.0-beta.1

package/tests/tools.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildServer } from '../src/server.js';
+import { InMemoryRunStore } from '@studio-foundation/engine';
+import type { IntegrationRuntime } from '../src/integration-runtime.js';
+import type { IntegrationStore } from '../src/integration-store.js';
+
+const TMP = resolve('/tmp', `.studio-api-tools-test-${Date.now()}`);
+const TOOLS_DIR = resolve(TMP, 'tools');
+
+const CUSTOM_TOOL_YAML = `name: my-custom-tool
+description: A custom tool for testing
+version: 1
+commands:
+  - name: my-custom-tool-do_something
+    description: Does something useful
+    parameters: {}
+    execute:
+      type: shell
+      command: echo hello
+`;
+
+const nullIntegrationRuntime = { registerRoutes: () => {} } as unknown as IntegrationRuntime;
+const nullIntegrationStore = {} as unknown as IntegrationStore;
+
+function makeServer() {
+  return buildServer({
+    store: new InMemoryRunStore(),
+    launcher: { launch: async () => ({ run_id: 'x' }), cancel: async () => {} },
+    configsDir: TMP,
+    projectName: 'test-project',
+    apiConfig: {},
+    studioVersion: '0.0.0-test',
+    maskedConfig: { providers: [] },
+    integrationRuntime: nullIntegrationRuntime,
+    integrationStore: nullIntegrationStore,
+  });
+}
+
+beforeAll(() => {
+  mkdirSync(TOOLS_DIR, { recursive: true });
+  writeFileSync(resolve(TOOLS_DIR, 'my-custom-tool.tool.yaml'), CUSTOM_TOOL_YAML);
+  writeFileSync(resolve(TOOLS_DIR, 'ignored.yaml'), ''); // must be ignored
+});
+
+afterAll(() => {
+  rmSync(TMP, { recursive: true, force: true });
+});
+
+describe('GET /api/tools', () => {
+  it('returns builtin tools with is_builtin: true', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'GET', url: '/api/tools' });
+    expect(res.statusCode).toBe(200);
+    const { tools } = res.json() as { tools: { name: string; is_builtin: boolean }[] };
+    const builtins = tools.filter(t => t.is_builtin);
+    expect(builtins.map(t => t.name)).toContain('shell');
+    expect(builtins.map(t => t.name)).toContain('repo-manager');
+  });
+
+  it('returns custom tools with is_builtin: false', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'GET', url: '/api/tools' });
+    expect(res.statusCode).toBe(200);
+    const { tools } = res.json() as { tools: { name: string; is_builtin: boolean }[] };
+    const custom = tools.find(t => t.name === 'my-custom-tool');
+    expect(custom).toBeDefined();
+    expect(custom!.is_builtin).toBe(false);
+  });
+
+  it('does not include non-.tool.yaml files', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'GET', url: '/api/tools' });
+    const { tools } = res.json() as { tools: { name: string }[] };
+    expect(tools.map(t => t.name)).not.toContain('ignored');
+  });
+
+  it('returns builtins even when tools dir is missing', async () => {
+    const emptyServer = buildServer({
+      store: new InMemoryRunStore(),
+      launcher: { launch: async () => ({ run_id: 'x' }), cancel: async () => {} },
+      configsDir: resolve('/tmp', `.studio-api-no-tools-${Date.now()}`),
+      projectName: 'empty',
+      apiConfig: {},
+      studioVersion: '0.0.0-test',
+      maskedConfig: { providers: [] },
+      integrationRuntime: nullIntegrationRuntime,
+      integrationStore: nullIntegrationStore,
+    });
+    const res = await emptyServer.inject({ method: 'GET', url: '/api/tools' });
+    expect(res.statusCode).toBe(200);
+    const { tools } = res.json() as { tools: { name: string; is_builtin: boolean }[] };
+    expect(tools.some(t => t.is_builtin)).toBe(true);
+    expect(tools.every(t => t.name !== 'my-custom-tool')).toBe(true);
+  });
+});
+
+describe('GET /api/tools/:name', () => {
+  it('returns parsed YAML for a custom tool', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'GET', url: '/api/tools/my-custom-tool' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { name: string; version: number; is_builtin: boolean };
+    expect(body.name).toBe('my-custom-tool');
+    expect(body.version).toBe(1);
+    expect(body.is_builtin).toBe(false);
+  });
+
+  it('returns builtin definition for a known builtin', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'GET', url: '/api/tools/shell' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { name: string; is_builtin: boolean; prompt_snippet?: string };
+    expect(body.name).toBe('shell');
+    expect(body.is_builtin).toBe(true);
+    expect(body.prompt_snippet).toBeTruthy();
+  });
+
+  it('returns 404 for unknown tool', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'GET', url: '/api/tools/nonexistent' });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: string }).error).toBeTruthy();
+  });
+});
+
+describe('PUT /api/tools/:name', () => {
+  it('creates a new custom tool from YAML body', async () => {
+    const server = makeServer();
+    const yamlBody = `name: new-tool\ndescription: test\nversion: 1\ncommands: []\n`;
+    const res = await server.inject({
+      method: 'PUT',
+      url: '/api/tools/new-tool',
+      headers: { 'content-type': 'text/plain' },
+      payload: yamlBody,
+    });
+    expect(res.statusCode).toBe(200);
+    expect((res.json() as { name: string }).name).toBe('new-tool');
+    const getRes = await server.inject({ method: 'GET', url: '/api/tools/new-tool' });
+    expect(getRes.statusCode).toBe(200);
+  });
+
+  it('creates a new custom tool from JSON body', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'PUT',
+      url: '/api/tools/json-tool',
+      headers: { 'content-type': 'application/json' },
+      payload: { name: 'json-tool', version: 1, commands: [] },
+    });
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('returns 400 for invalid YAML body', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'PUT',
+      url: '/api/tools/bad-tool',
+      headers: { 'content-type': 'text/plain' },
+      payload: 'key: [unclosed\n  - item',
+    });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: string }).error).toBeTruthy();
+  });
+});
+
+describe('DELETE /api/tools/:name', () => {
+  it('deletes an existing custom tool', async () => {
+    const server = makeServer();
+    await server.inject({
+      method: 'PUT',
+      url: '/api/tools/to-delete',
+      headers: { 'content-type': 'text/plain' },
+      payload: 'name: to-delete\nversion: 1\ncommands: []\n',
+    });
+    const res = await server.inject({ method: 'DELETE', url: '/api/tools/to-delete' });
+    expect(res.statusCode).toBe(200);
+    const getRes = await server.inject({ method: 'GET', url: '/api/tools/to-delete' });
+    expect(getRes.statusCode).toBe(404);
+  });
+
+  it('returns 403 when trying to delete a builtin tool', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'DELETE', url: '/api/tools/shell' });
+    expect(res.statusCode).toBe(403);
+    expect((res.json() as { error: string }).error).toMatch(/builtin/i);
+  });
+
+  it('returns 404 for nonexistent custom tool', async () => {
+    const server = makeServer();
+    const res = await server.inject({ method: 'DELETE', url: '/api/tools/ghost-tool' });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: string }).error).toBeTruthy();
+  });
+});
+
+describe('POST /api/tools/install', () => {
+  it('installs a bundled tool by name', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/tools/install',
+      payload: { name: 'shell' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect((res.json() as { installed: string }).installed).toBe('shell');
+    const getRes = await server.inject({ method: 'GET', url: '/api/tools/shell' });
+    expect(getRes.statusCode).toBe(200);
+  });
+
+  it('returns 409 if tool is already installed', async () => {
+    const server = makeServer();
+    await server.inject({ method: 'POST', url: '/api/tools/install', payload: { name: 'git' } });
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/tools/install',
+      payload: { name: 'git' },
+    });
+    expect(res.statusCode).toBe(409);
+  });
+
+  it('returns 404 for unknown tool name', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/tools/install',
+      payload: { name: 'nonexistent-tool' },
+    });
+    expect(res.statusCode).toBe(404);
+    expect((res.json() as { error: string }).error).toBeTruthy();
+  });
+});

package/tests/user-store.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { UserStore, type User } from '../src/user-store.js';
+
+function makeUser(overrides: Partial<User> = {}): User {
+  return {
+    id: 'user-1',
+    email: 'alice@example.com',
+    plan: 'free',
+    api_key: 'sk-test-abc123',
+    created_at: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+describe('UserStore', () => {
+  let store: UserStore;
+
+  beforeEach(() => {
+    const dbDir = resolve('/tmp', `.studio-user-store-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dbDir, { recursive: true });
+    store = new UserStore(resolve(dbDir, 'runs.db'));
+  });
+
+  afterEach(() => {
+    store.close();
+  });
+
+  // CRUD
+  test('saves and retrieves a user by id', () => {
+    const user = makeUser();
+    store.saveUser(user);
+    expect(store.getUserById('user-1')).toEqual(user);
+  });
+
+  test('retrieves a user by api_key', () => {
+    const user = makeUser();
+    store.saveUser(user);
+    expect(store.getUserByApiKey('sk-test-abc123')).toEqual(user);
+  });
+
+  test('returns null for unknown id', () => {
+    expect(store.getUserById('nonexistent')).toBeNull();
+  });
+
+  test('returns null for unknown api_key', () => {
+    expect(store.getUserByApiKey('sk-unknown')).toBeNull();
+  });
+
+  test('lists all users', () => {
+    store.saveUser(makeUser({ id: 'u1', email: 'a@a.com', api_key: 'key-1' }));
+    store.saveUser(makeUser({ id: 'u2', email: 'b@b.com', api_key: 'key-2' }));
+    expect(store.listUsers()).toHaveLength(2);
+  });
+
+  test('deletes a user', () => {
+    store.saveUser(makeUser());
+    store.deleteUser('user-1');
+    expect(store.getUserById('user-1')).toBeNull();
+  });
+
+  // Usage tracking
+  test('getDailyUsage returns zeros for new entry', () => {
+    const usage = store.getDailyUsage('user-1', '2026-01-01');
+    expect(usage.runs_count).toBe(0);
+    expect(usage.tokens_used).toBe(0);
+  });
+
+  test('incrementRuns increases runs_count by 1', () => {
+    store.incrementRuns('user-1', '2026-01-01');
+    store.incrementRuns('user-1', '2026-01-01');
+    expect(store.getDailyUsage('user-1', '2026-01-01').runs_count).toBe(2);
+  });
+
+  test('incrementTokens increases tokens_used', () => {
+    store.incrementTokens('user-1', '2026-01-01', 1000);
+    store.incrementTokens('user-1', '2026-01-01', 500);
+    expect(store.getDailyUsage('user-1', '2026-01-01').tokens_used).toBe(1500);
+  });
+
+  test('usage is scoped by date — different dates are independent', () => {
+    store.incrementRuns('user-1', '2026-01-01');
+    store.incrementRuns('user-1', '2026-01-02');
+    expect(store.getDailyUsage('user-1', '2026-01-01').runs_count).toBe(1);
+    expect(store.getDailyUsage('user-1', '2026-01-02').runs_count).toBe(1);
+  });
+
+  test('usage is scoped by user — different users are independent', () => {
+    store.incrementRuns('user-1', '2026-01-01');
+    expect(store.getDailyUsage('user-2', '2026-01-01').runs_count).toBe(0);
+  });
+});

package/tests/users.test.ts

@@ -0,0 +1,189 @@
+// api/tests/users.test.ts
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildServer } from '../src/server.js';
+import { InMemoryRunStore } from '@studio-foundation/engine';
+import type { RunLauncher } from '../src/launcher.js';
+import type { IntegrationRuntime } from '../src/integration-runtime.js';
+import type { IntegrationStore } from '../src/integration-store.js';
+import { UserStore } from '../src/user-store.js';
+import { DEFAULT_PLANS } from '../src/plans.js';
+
+function makeMockLauncher(): RunLauncher {
+  return { launch: async () => ({ run_id: 'mock-run-id' }), cancel: async () => {}, subscribe: () => () => {} };
+}
+const nullIntegrationRuntime = { registerRoutes: () => {} } as unknown as IntegrationRuntime;
+const nullIntegrationStore = {} as unknown as IntegrationStore;
+
+function makeTempUserStore() {
+  const dir = resolve('/tmp', `.studio-users-route-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  return new UserStore(resolve(dir, 'runs.db'));
+}
+
+function buildTestServer(userStore: UserStore, apiKey?: string) {
+  return buildServer({
+    store: new InMemoryRunStore(),
+    launcher: makeMockLauncher(),
+    configsDir: '/tmp/.studio',
+    projectName: 'test',
+    apiConfig: apiKey ? { key: apiKey } : {},
+    integrationRuntime: nullIntegrationRuntime,
+    integrationStore: nullIntegrationStore,
+    userStore,
+    plans: DEFAULT_PLANS,
+    hasUsers: userStore.listUsers().length > 0,
+  });
+}
+
+describe('POST /api/users', () => {
+  let userStore: UserStore;
+
+  beforeEach(() => { userStore = makeTempUserStore(); });
+  afterEach(() => { userStore.close(); });
+
+  it('creates a user and returns api_key', async () => {
+    const server = buildTestServer(userStore, 'admin-key');
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/users',
+      headers: { Authorization: 'Bearer admin-key' },
+      payload: { email: 'alice@example.com', plan: 'pro' },
+    });
+    expect(res.statusCode).toBe(201);
+    const body = res.json();
+    expect(body.email).toBe('alice@example.com');
+    expect(body.plan).toBe('pro');
+    expect(body.api_key).toBeTruthy();
+    expect(body.id).toBeTruthy();
+  });
+
+  it('rejects duplicate email with 409', async () => {
+    const server = buildTestServer(userStore, 'admin-key');
+    await server.inject({
+      method: 'POST',
+      url: '/api/users',
+      headers: { Authorization: 'Bearer admin-key' },
+      payload: { email: 'alice@example.com' },
+    });
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/users',
+      headers: { Authorization: 'Bearer admin-key' },
+      payload: { email: 'alice@example.com' },
+    });
+    expect(res.statusCode).toBe(409);
+  });
+});
+
+describe('GET /api/users', () => {
+  let userStore: UserStore;
+
+  beforeEach(() => { userStore = makeTempUserStore(); });
+  afterEach(() => { userStore.close(); });
+
+  it('lists users without exposing api_key', async () => {
+    userStore.saveUser({ id: 'u1', email: 'alice@example.com', plan: 'free', api_key: 'secret-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({
+      method: 'GET',
+      url: '/api/users',
+      headers: { Authorization: 'Bearer secret-key' },
+    });
+    expect(res.statusCode).toBe(200);
+    const users = res.json();
+    expect(users).toHaveLength(1);
+    expect(users[0].email).toBe('alice@example.com');
+    expect(users[0].api_key).toBeUndefined();
+  });
+});
+
+describe('GET /api/users/:id', () => {
+  let userStore: UserStore;
+
+  beforeEach(() => { userStore = makeTempUserStore(); });
+  afterEach(() => { userStore.close(); });
+
+  it('returns user with today_usage', async () => {
+    userStore.saveUser({ id: 'u1', email: 'alice@example.com', plan: 'pro', api_key: 'user-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({
+      method: 'GET',
+      url: '/api/users/u1',
+      headers: { Authorization: 'Bearer user-key' },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.email).toBe('alice@example.com');
+    expect(body.today_usage).toEqual({ runs_count: 0, tokens_used: 0 });
+    expect(body.api_key).toBeUndefined();
+  });
+
+  it('returns 404 for unknown id', async () => {
+    userStore.saveUser({ id: 'u1', email: 'alice@example.com', plan: 'pro', api_key: 'user-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({
+      method: 'GET',
+      url: '/api/users/nonexistent',
+      headers: { Authorization: 'Bearer user-key' },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+});
+
+describe('DELETE /api/users/:id', () => {
+  let userStore: UserStore;
+
+  beforeEach(() => { userStore = makeTempUserStore(); });
+  afterEach(() => { userStore.close(); });
+
+  it('deletes a user and returns 204', async () => {
+    userStore.saveUser({ id: 'u1', email: 'alice@example.com', plan: 'free', api_key: 'user-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({
+      method: 'DELETE',
+      url: '/api/users/u1',
+      headers: { Authorization: 'Bearer user-key' },
+    });
+    expect(res.statusCode).toBe(204);
+    expect(userStore.getUserById('u1')).toBeNull();
+  });
+
+  it('returns 404 for unknown id', async () => {
+    userStore.saveUser({ id: 'u1', email: 'alice@example.com', plan: 'free', api_key: 'user-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({
+      method: 'DELETE',
+      url: '/api/users/nonexistent',
+      headers: { Authorization: 'Bearer user-key' },
+    });
+    expect(res.statusCode).toBe(404);
+  });
+});
+
+describe('GET /api/users/me', () => {
+  let userStore: UserStore;
+
+  beforeEach(() => { userStore = makeTempUserStore(); });
+  afterEach(() => { userStore.close(); });
+
+  it('returns current user info', async () => {
+    userStore.saveUser({ id: 'u1', email: 'me@example.com', plan: 'pro', api_key: 'my-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({
+      method: 'GET',
+      url: '/api/users/me',
+      headers: { Authorization: 'Bearer my-key' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().email).toBe('me@example.com');
+  });
+
+  it('returns 401 when not authenticated', async () => {
+    userStore.saveUser({ id: 'u1', email: 'me@example.com', plan: 'pro', api_key: 'my-key', created_at: '2026-01-01T00:00:00.000Z' });
+    const server = buildTestServer(userStore);
+    const res = await server.inject({ method: 'GET', url: '/api/users/me' });
+    expect(res.statusCode).toBe(401);
+  });
+});

package/tests/utils/repo-resolver.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { homedir } from 'node:os';
+
+// Mock node:child_process so tests don't actually run git
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  return { ...actual, execSync: vi.fn() };
+});
+
+// Mock node:fs/promises — mkdir only
+vi.mock('node:fs/promises', () => ({
+  mkdir: vi.fn().mockResolvedValue(undefined),
+}));
+
+import { resolveRepoPath, cloneRepo } from '../../src/utils/repo-resolver.js';
+import { execSync } from 'node:child_process';
+
+const mockExecSync = vi.mocked(execSync);
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  mockExecSync.mockClear();
+});
+
+describe('resolveRepoPath', () => {
+  it('returns resolved repoPathOverride when provided', async () => {
+    const result = await resolveRepoPath({ repoPathOverride: 'my-project', pipelineName: 'p' });
+    expect(result).toMatch(/my-project$/);
+  });
+
+  it('returns "." when no repoPathOverride and no repoUrl', async () => {
+    const result = await resolveRepoPath({ pipelineName: 'feature-builder' });
+    expect(result).toBe('.');
+  });
+
+  it('throws when repoUrl is set but no rawProjectsDir and no env var', async () => {
+    vi.stubEnv('STUDIO_PROJECTS_DIR', '');
+    await expect(
+      resolveRepoPath({ repoUrl: 'https://github.com/user/repo', pipelineName: 'p' })
+    ).rejects.toThrow('STUDIO_PROJECTS_DIR is not set');
+  });
+
+  it('clones when repoUrl is provided with rawProjectsDir', async () => {
+    const result = await resolveRepoPath({
+      repoUrl: 'https://github.com/user/repo',
+      rawProjectsDir: '/tmp/projects',
+      pipelineName: 'my-pipeline',
+    });
+    expect(mockExecSync).toHaveBeenCalledOnce();
+    const cmd = mockExecSync.mock.calls[0]![0] as string;
+    expect(cmd).toContain('git clone');
+    expect(cmd).toContain('https://github.com/user/repo');
+    expect(result).toContain('/tmp/projects/my-pipeline-');
+  });
+
+  it('clones when repoUrl is provided via STUDIO_PROJECTS_DIR env var', async () => {
+    vi.stubEnv('STUDIO_PROJECTS_DIR', '/tmp/envprojects');
+    const result = await resolveRepoPath({
+      repoUrl: 'https://github.com/user/repo',
+      pipelineName: 'test-pipe',
+    });
+    expect(mockExecSync).toHaveBeenCalledOnce();
+    expect(result).toContain('/tmp/envprojects/test-pipe-');
+  });
+
+  it('expands ~ in rawProjectsDir', async () => {
+    const result = await resolveRepoPath({
+      repoUrl: 'https://github.com/user/repo',
+      rawProjectsDir: '~/projects',
+      pipelineName: 'p',
+    });
+    expect(result).toContain(homedir() + '/projects/p-');
+  });
+
+  it('repoPathOverride takes precedence over repoUrl', async () => {
+    const result = await resolveRepoPath({
+      repoPathOverride: '/explicit/path',
+      repoUrl: 'https://github.com/user/repo',
+      rawProjectsDir: '/tmp/p',
+      pipelineName: 'p',
+    });
+    expect(result).toBe('/explicit/path');
+    expect(mockExecSync).not.toHaveBeenCalled();
+  });
+
+  it('passes branch arg when branch is set', async () => {
+    await resolveRepoPath({
+      repoUrl: 'https://github.com/user/repo',
+      rawProjectsDir: '/tmp/projects',
+      pipelineName: 'p',
+      branch: 'main',
+    });
+    const cmd = mockExecSync.mock.calls[0]![0] as string;
+    expect(cmd).toContain('--branch main');
+  });
+});
+
+describe('cloneRepo', () => {
+  it('throws a descriptive error when git clone fails', async () => {
+    mockExecSync.mockImplementationOnce(() => { throw new Error('repository not found'); });
+    await expect(
+      cloneRepo('https://github.com/bad/repo', '/tmp/p', 'pipeline')
+    ).rejects.toThrow('Failed to clone https://github.com/bad/repo');
+  });
+});