@hyperdrive.bot/cli 1.0.13 → 1.0.17

package/dist/commands/{jira → tracker}/status.js

@@ -33,7 +33,7 @@ export default class JiraStatus extends Command {
         // Fetch status
         spinner.start('Fetching Jira connection status...');
         try {
-            const response = await apiService['makeSignedRequest']('GET', '/hyperdrive/jira/status');
+            const response = await apiService.jiraStatus();
             spinner.succeed('Status retrieved');
             // Display summary
             this.log('');
@@ -76,7 +76,7 @@ export default class JiraStatus extends Command {
                 }
                 else {
                     this.log(chalk.yellow('⚠️  Action Required: Install the Forge app from the Atlassian Marketplace'));
-                    this.log(chalk.dim(`   Run: ${chalk.cyan('hd jira connect')} to see installation instructions`));
+                    this.log(chalk.dim(`   Run: ${chalk.cyan('hd tracker connect')} to see installation instructions`));
                 }
                 this.log('');
             }
@@ -85,7 +85,7 @@ export default class JiraStatus extends Command {
                 this.log(chalk.yellow('No Jira connections found'));
                 this.log('');
                 this.log(chalk.dim('To connect a Jira instance, run:'));
-                this.log(chalk.dim(`  ${chalk.cyan('hd jira connect')}`));
+                this.log(chalk.dim(`  ${chalk.cyan('hd tracker connect')}`));
                 this.log('');
             }
             // Success message if everything is connected

package/dist/lib/ensure-branches.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared core logic for `hd stage ensure-branches`.
+ *
+ * Given a set of linked projects and a target branch name, this function
+ * iterates each project and guarantees the branch exists on its remote,
+ * creating it from the remote's current default branch when missing. It is
+ * strictly idempotent: detection always runs before mutation, so re-invoking
+ * with no missing branches makes zero API mutation calls.
+ */
+import { type GitProvider } from './git-providers/index.js';
+export type ProjectStatus = 'created' | 'exists' | 'failed' | 'skipped-no-remote';
+export interface LinkedProjectInput {
+    /** Project slug (used for display/reporting). */
+    slug?: string;
+    /** Provider identifier — only `'gitlab'` is supported today. */
+    gitProvider?: string;
+    /** Full repo path, e.g. `dev_squad/repo/web-apps/sign` (no host, no `.git`). */
+    gitFullRepoPath?: string;
+}
+export interface EnsureBranchesProjectResult {
+    slug: string;
+    remoteUrl: string;
+    status: ProjectStatus;
+    defaultBranch?: string;
+    error?: string;
+}
+export interface EnsureBranchesResult {
+    total: number;
+    created: number;
+    alreadyExisted: number;
+    failed: number;
+    projects: EnsureBranchesProjectResult[];
+}
+export interface EnsureBranchesOptions {
+    stageName: string;
+    branchName: string;
+    linkedProjects: LinkedProjectInput[];
+    verbose?: boolean;
+    dryRun?: boolean;
+    logger: (msg: string) => void;
+    /**
+     * Optional provider override — primarily for tests. When omitted, the
+     * provider is resolved from each project's remote URL via the factory.
+     */
+    providerFactory?: (remoteUrl: string) => GitProvider;
+}
+/**
+ * Ensure the stage branch exists on every linked project's remote.
+ *
+ * Never throws — all errors are collected into `result.projects[i].error` so
+ * the caller can decide the final exit code based on `result.failed`.
+ */
+export declare function ensureBranches(opts: EnsureBranchesOptions): Promise<EnsureBranchesResult>;

package/dist/lib/ensure-branches.js

@@ -0,0 +1,149 @@
+/**
+ * Shared core logic for `hd stage ensure-branches`.
+ *
+ * Given a set of linked projects and a target branch name, this function
+ * iterates each project and guarantees the branch exists on its remote,
+ * creating it from the remote's current default branch when missing. It is
+ * strictly idempotent: detection always runs before mutation, so re-invoking
+ * with no missing branches makes zero API mutation calls.
+ */
+import { getProviderForRemote } from './git-providers/index.js';
+/**
+ * Ensure the stage branch exists on every linked project's remote.
+ *
+ * Never throws — all errors are collected into `result.projects[i].error` so
+ * the caller can decide the final exit code based on `result.failed`.
+ */
+export async function ensureBranches(opts) {
+    const { stageName, branchName, linkedProjects, verbose, dryRun, logger } = opts;
+    const resolveProvider = opts.providerFactory ?? getProviderForRemote;
+    const projects = [];
+    let created = 0;
+    let alreadyExisted = 0;
+    let failed = 0;
+    for (const project of linkedProjects) {
+        const slug = project.slug ?? '<unknown>';
+        if (!project.gitFullRepoPath) {
+            if (verbose) {
+                logger(`${slug}: skipped — no git remote configured`);
+            }
+            projects.push({ slug, remoteUrl: '', status: 'skipped-no-remote' });
+            continue;
+        }
+        const providerName = project.gitProvider ?? 'gitlab';
+        const remoteUrl = `https://${providerName}.com/${project.gitFullRepoPath}.git`;
+        let provider;
+        try {
+            provider = resolveProvider(remoteUrl);
+        }
+        catch (error) {
+            const message = error.message;
+            failed += 1;
+            projects.push({ slug, remoteUrl, status: 'failed', error: message });
+            if (verbose) {
+                logger(`${slug}: FAILED — ${message}`);
+            }
+            else {
+                logger(`⚠️  ${slug} (${remoteUrl}): ${message}`);
+            }
+            continue;
+        }
+        let defaultBranch;
+        try {
+            defaultBranch = await provider.detectDefaultBranch({ remoteUrl });
+        }
+        catch (error) {
+            const message = error.message;
+            failed += 1;
+            projects.push({ slug, remoteUrl, status: 'failed', error: message });
+            if (verbose) {
+                logger(`${slug}: FAILED — ${message}`);
+            }
+            else {
+                logger(`⚠️  ${slug} (${remoteUrl}): ${message}`);
+            }
+            continue;
+        }
+        // Idempotency check — never mutate if the branch already exists.
+        let stageBranchCheck;
+        try {
+            stageBranchCheck = await provider.getBranch({ remoteUrl, branchName });
+        }
+        catch (error) {
+            const message = error.message;
+            failed += 1;
+            projects.push({ slug, remoteUrl, status: 'failed', error: message, defaultBranch });
+            if (verbose) {
+                logger(`${slug}: FAILED — ${message}`);
+            }
+            else {
+                logger(`⚠️  ${slug} (${remoteUrl}): ${message}`);
+            }
+            continue;
+        }
+        if (stageBranchCheck.exists) {
+            alreadyExisted += 1;
+            projects.push({ slug, remoteUrl, status: 'exists', defaultBranch });
+            if (verbose) {
+                logger(`${slug}: branch exists, skipping`);
+            }
+            continue;
+        }
+        if (dryRun) {
+            created += 1;
+            projects.push({ slug, remoteUrl, status: 'created', defaultBranch });
+            logger(`[dry-run] ${slug}: would create ${branchName} from ${defaultBranch}`);
+            continue;
+        }
+        // Resolve the default branch SHA before creating.
+        let defaultBranchSha;
+        try {
+            const defaultBranchCheck = await provider.getBranch({ remoteUrl, branchName: defaultBranch });
+            if (!defaultBranchCheck.exists || !defaultBranchCheck.sha) {
+                throw new Error(`default branch ${defaultBranch} not found on remote`);
+            }
+            defaultBranchSha = defaultBranchCheck.sha;
+        }
+        catch (error) {
+            const message = error.message;
+            failed += 1;
+            projects.push({ slug, remoteUrl, status: 'failed', error: message, defaultBranch });
+            if (verbose) {
+                logger(`${slug}: FAILED — ${message}`);
+            }
+            else {
+                logger(`⚠️  ${slug} (${remoteUrl}): ${message}`);
+            }
+            continue;
+        }
+        try {
+            await provider.createBranch({ remoteUrl, branchName, fromSha: defaultBranchSha });
+            created += 1;
+            projects.push({ slug, remoteUrl, status: 'created', defaultBranch });
+            if (verbose) {
+                logger(`${slug}: created ${branchName} from ${defaultBranch}`);
+            }
+        }
+        catch (error) {
+            const message = error.message;
+            failed += 1;
+            projects.push({ slug, remoteUrl, status: 'failed', error: message, defaultBranch });
+            if (verbose) {
+                logger(`${slug}: FAILED — ${message}`);
+            }
+            else {
+                logger(`⚠️  ${slug} (${remoteUrl}): ${message}`);
+            }
+        }
+    }
+    // Suppress unused-var warning in build — `stageName` is kept on the options
+    // interface for future logging/telemetry, even if unused in the loop body.
+    void stageName;
+    return {
+        total: linkedProjects.length,
+        created,
+        alreadyExisted,
+        failed,
+        projects,
+    };
+}

package/dist/lib/git-providers/github.d.ts

@@ -0,0 +1,16 @@
+/**
+ * GitHub git provider — detects and creates branches, lists open PRs on github.com remotes.
+ *
+ * Detection (`detectDefaultBranch`, `getBranch`) shells out to `git ls-remote`
+ * and works with whatever SSH/https credentials git already has.
+ *
+ * Mutation (`createBranch`) and reads (`listOpenPullRequests`) call the GitHub
+ * REST API and require a personal access token in `GITHUB_TOKEN` with `repo` scope.
+ */
+import type { CreateBranchOptions, CreateBranchResult, DetectDefaultBranchOptions, GetBranchOptions, GetBranchResult, GitProvider, ListOpenPullRequestsOptions, OpenPullRequest } from './index.js';
+export declare class GitHubProvider implements GitProvider {
+    detectDefaultBranch({ remoteUrl }: DetectDefaultBranchOptions): Promise<string>;
+    getBranch({ remoteUrl, branchName }: GetBranchOptions): Promise<GetBranchResult>;
+    createBranch({ remoteUrl, branchName, fromSha, }: CreateBranchOptions): Promise<CreateBranchResult>;
+    listOpenPullRequests({ repo, token: explicitToken, }: ListOpenPullRequestsOptions): Promise<OpenPullRequest[]>;
+}

package/dist/lib/git-providers/github.js

@@ -0,0 +1,157 @@
+/**
+ * GitHub git provider — detects and creates branches, lists open PRs on github.com remotes.
+ *
+ * Detection (`detectDefaultBranch`, `getBranch`) shells out to `git ls-remote`
+ * and works with whatever SSH/https credentials git already has.
+ *
+ * Mutation (`createBranch`) and reads (`listOpenPullRequests`) call the GitHub
+ * REST API and require a personal access token in `GITHUB_TOKEN` with `repo` scope.
+ */
+import { execSync } from 'node:child_process';
+import axios from 'axios';
+const GITHUB_API = 'https://api.github.com';
+export class GitHubProvider {
+    async detectDefaultBranch({ remoteUrl }) {
+        let stdout;
+        try {
+            stdout = execSync(`git ls-remote --symref ${remoteUrl} HEAD`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            const err = error;
+            const stderr = err.stderr ? err.stderr.toString().trim() : (err.message ?? 'unknown error');
+            throw new Error(`Unable to detect default branch for ${remoteUrl}: ${stderr}`);
+        }
+        // First line format: "ref: refs/heads/<branch>\tHEAD"
+        const firstLine = stdout.split('\n')[0] ?? '';
+        const match = firstLine.match(/^ref:\s+refs\/heads\/([^\t\s]+)\s+HEAD/);
+        if (!match) {
+            throw new Error(`Unable to detect default branch for ${remoteUrl}: unexpected output "${firstLine}"`);
+        }
+        return match[1];
+    }
+    async getBranch({ remoteUrl, branchName }) {
+        let stdout;
+        try {
+            stdout = execSync(`git ls-remote ${remoteUrl} refs/heads/${branchName}`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            const err = error;
+            const stderr = err.stderr ? err.stderr.toString().trim() : (err.message ?? 'unknown error');
+            throw new Error(`Unable to query branch ${branchName} on ${remoteUrl}: ${stderr}`);
+        }
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0) {
+            return { exists: false };
+        }
+        // Line format: "<sha>\trefs/heads/<branch>"
+        const firstLine = trimmed.split('\n')[0] ?? '';
+        const [sha] = firstLine.split(/\s+/);
+        if (!sha) {
+            return { exists: false };
+        }
+        return { exists: true, sha };
+    }
+    async createBranch({ remoteUrl, branchName, fromSha, }) {
+        const token = process.env.GITHUB_TOKEN;
+        if (!token) {
+            throw new Error('GITHUB_TOKEN env var required for branch creation (set to a GitHub personal access token with repo scope)');
+        }
+        const { owner, repo } = extractOwnerRepo(remoteUrl);
+        const url = `${GITHUB_API}/repos/${owner}/${repo}/git/refs`;
+        try {
+            const response = await axios.post(url, { ref: `refs/heads/${branchName}`, sha: fromSha }, {
+                headers: {
+                    'Accept': 'application/vnd.github+json',
+                    'Authorization': `Bearer ${token}`,
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+            });
+            return { created: true, sha: response.data.object.sha };
+        }
+        catch (error) {
+            const axiosError = error;
+            const status = axiosError.response?.status;
+            const bodyMessage = axiosError.response?.data?.message ?? axiosError.message ?? 'unknown error';
+            // GitHub returns 422 "Reference already exists" when the branch exists
+            if (status === 422 && typeof bodyMessage === 'string' && bodyMessage.includes('Reference already exists')) {
+                return { created: false, sha: '' };
+            }
+            throw new Error(`GitHub createBranch failed (${status ?? 'no-status'}): ${bodyMessage}`);
+        }
+    }
+    async listOpenPullRequests({ repo, token: explicitToken, }) {
+        const token = explicitToken || process.env.GITHUB_TOKEN;
+        if (!token) {
+            throw new Error('GITHUB_TOKEN env var or --token flag required for listing pull requests');
+        }
+        // repo is "owner/repo" format
+        const url = `${GITHUB_API}/repos/${repo}/pulls`;
+        const pullRequests = [];
+        let page = 1;
+        const perPage = 100;
+        // Paginate through all open PRs
+        while (true) {
+            const response = await axios.get(url, {
+                headers: {
+                    'Accept': 'application/vnd.github+json',
+                    'Authorization': `Bearer ${token}`,
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+                params: {
+                    state: 'open',
+                    per_page: perPage,
+                    page,
+                },
+            });
+            for (const pr of response.data) {
+                pullRequests.push({
+                    number: pr.number,
+                    title: pr.title,
+                    sourceBranch: pr.head.ref,
+                    author: pr.user?.login ?? 'unknown',
+                    url: pr.html_url,
+                });
+            }
+            // If we got fewer results than perPage, we've reached the last page
+            if (response.data.length < perPage) {
+                break;
+            }
+            page++;
+        }
+        return pullRequests;
+    }
+}
+/**
+ * Extract owner and repo from a GitHub remote URL.
+ *
+ * Accepts both SSH and HTTPS forms:
+ *   - `https://github.com/owner/repo.git`
+ *   - `git@github.com:owner/repo.git`
+ * Both return `{ owner: 'owner', repo: 'repo' }`.
+ */
+function extractOwnerRepo(remoteUrl) {
+    let path = remoteUrl.trim();
+    if (path.startsWith('git@github.com:')) {
+        path = path.slice('git@github.com:'.length);
+    }
+    else if (path.startsWith('https://github.com/')) {
+        path = path.slice('https://github.com/'.length);
+    }
+    else if (path.startsWith('http://github.com/')) {
+        path = path.slice('http://github.com/'.length);
+    }
+    if (path.endsWith('.git')) {
+        path = path.slice(0, -'.git'.length);
+    }
+    const parts = path.split('/');
+    if (parts.length < 2) {
+        throw new Error(`Invalid GitHub remote URL: ${remoteUrl} (expected owner/repo)`);
+    }
+    return { owner: parts[0], repo: parts[1] };
+}

package/dist/lib/git-providers/gitlab.d.ts

@@ -0,0 +1,16 @@
+/**
+ * GitLab git provider — detects and creates branches on gitlab.com remotes.
+ *
+ * Detection (`detectDefaultBranch`, `getBranch`) shells out to `git ls-remote`
+ * and works with whatever SSH/https credentials git already has.
+ *
+ * Mutation (`createBranch`) calls the GitLab v4 REST API and requires a
+ * personal access token in `GITLAB_TOKEN` with `api` scope.
+ */
+import type { CreateBranchOptions, CreateBranchResult, DetectDefaultBranchOptions, GetBranchOptions, GetBranchResult, GitProvider, ListOpenPullRequestsOptions, OpenPullRequest } from './index.js';
+export declare class GitLabProvider implements GitProvider {
+    detectDefaultBranch({ remoteUrl }: DetectDefaultBranchOptions): Promise<string>;
+    getBranch({ remoteUrl, branchName }: GetBranchOptions): Promise<GetBranchResult>;
+    createBranch({ remoteUrl, branchName, fromSha, }: CreateBranchOptions): Promise<CreateBranchResult>;
+    listOpenPullRequests({ repo, token: explicitToken, }: ListOpenPullRequestsOptions): Promise<OpenPullRequest[]>;
+}

package/dist/lib/git-providers/gitlab.js

@@ -0,0 +1,148 @@
+/**
+ * GitLab git provider — detects and creates branches on gitlab.com remotes.
+ *
+ * Detection (`detectDefaultBranch`, `getBranch`) shells out to `git ls-remote`
+ * and works with whatever SSH/https credentials git already has.
+ *
+ * Mutation (`createBranch`) calls the GitLab v4 REST API and requires a
+ * personal access token in `GITLAB_TOKEN` with `api` scope.
+ */
+import { execSync } from 'node:child_process';
+import axios from 'axios';
+export class GitLabProvider {
+    async detectDefaultBranch({ remoteUrl }) {
+        let stdout;
+        try {
+            stdout = execSync(`git ls-remote --symref ${remoteUrl} HEAD`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            const err = error;
+            const stderr = err.stderr ? err.stderr.toString().trim() : (err.message ?? 'unknown error');
+            throw new Error(`Unable to detect default branch for ${remoteUrl}: ${stderr}`);
+        }
+        // First line format: "ref: refs/heads/<branch>\tHEAD"
+        const firstLine = stdout.split('\n')[0] ?? '';
+        const match = firstLine.match(/^ref:\s+refs\/heads\/([^\t\s]+)\s+HEAD/);
+        if (!match) {
+            throw new Error(`Unable to detect default branch for ${remoteUrl}: unexpected output "${firstLine}"`);
+        }
+        return match[1];
+    }
+    async getBranch({ remoteUrl, branchName }) {
+        let stdout;
+        try {
+            stdout = execSync(`git ls-remote ${remoteUrl} refs/heads/${branchName}`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (error) {
+            const err = error;
+            const stderr = err.stderr ? err.stderr.toString().trim() : (err.message ?? 'unknown error');
+            throw new Error(`Unable to query branch ${branchName} on ${remoteUrl}: ${stderr}`);
+        }
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0) {
+            return { exists: false };
+        }
+        // Line format: "<sha>\trefs/heads/<branch>"
+        const firstLine = trimmed.split('\n')[0] ?? '';
+        const [sha] = firstLine.split(/\s+/);
+        if (!sha) {
+            return { exists: false };
+        }
+        return { exists: true, sha };
+    }
+    async createBranch({ remoteUrl, branchName, fromSha, }) {
+        const token = process.env.GITLAB_TOKEN;
+        if (!token) {
+            throw new Error('GITLAB_TOKEN env var required for branch creation (set to a GitLab personal access token with api scope)');
+        }
+        const projectPath = extractProjectPath(remoteUrl);
+        const encodedPath = encodeURIComponent(projectPath);
+        const url = `https://gitlab.com/api/v4/projects/${encodedPath}/repository/branches`;
+        try {
+            const response = await axios.post(url, { branch: branchName, ref: fromSha }, { headers: { 'PRIVATE-TOKEN': token } });
+            return { created: true, sha: response.data.commit.id };
+        }
+        catch (error) {
+            const axiosError = error;
+            const status = axiosError.response?.status;
+            const body = axiosError.response?.data;
+            const bodyMessage = Array.isArray(body?.message)
+                ? body.message.join(', ')
+                : (body?.message ?? axiosError.message ?? 'unknown error');
+            // GitLab returns 400 with "Branch already exists" when the branch is
+            // present — treat as a non-error so the caller can mark it "already
+            // existed" and keep going.
+            if (status === 400 && typeof bodyMessage === 'string' && bodyMessage.includes('Branch already exists')) {
+                return { created: false, sha: '' };
+            }
+            throw new Error(`GitLab createBranch failed (${status ?? 'no-status'}): ${bodyMessage}`);
+        }
+    }
+    async listOpenPullRequests({ repo, token: explicitToken, }) {
+        const token = explicitToken || process.env.GITLAB_TOKEN;
+        if (!token) {
+            throw new Error('GITLAB_TOKEN env var or --token flag required for listing merge requests');
+        }
+        const encodedPath = encodeURIComponent(repo);
+        const mergeRequests = [];
+        let page = 1;
+        const perPage = 100;
+        // Paginate through all open MRs
+        while (true) {
+            const url = `https://gitlab.com/api/v4/projects/${encodedPath}/merge_requests`;
+            const response = await axios.get(url, {
+                headers: { 'PRIVATE-TOKEN': token },
+                params: {
+                    state: 'opened',
+                    per_page: perPage,
+                    page,
+                },
+            });
+            for (const mr of response.data) {
+                mergeRequests.push({
+                    number: mr.iid,
+                    title: mr.title,
+                    sourceBranch: mr.source_branch,
+                    author: mr.author?.username ?? 'unknown',
+                    url: mr.web_url,
+                });
+            }
+            // If we got fewer results than perPage, we've reached the last page
+            if (response.data.length < perPage) {
+                break;
+            }
+            page++;
+        }
+        return mergeRequests;
+    }
+}
+/**
+ * Extract the GitLab project path from a remote URL.
+ *
+ * Accepts both SSH and HTTPS forms:
+ *   - `https://gitlab.com/dev_squad/repo/web-apps/sign.git`
+ *   - `git@gitlab.com:dev_squad/repo/web-apps/sign.git`
+ * Both return `dev_squad/repo/web-apps/sign`.
+ */
+function extractProjectPath(remoteUrl) {
+    let path = remoteUrl.trim();
+    if (path.startsWith('git@gitlab.com:')) {
+        path = path.slice('git@gitlab.com:'.length);
+    }
+    else if (path.startsWith('https://gitlab.com/')) {
+        path = path.slice('https://gitlab.com/'.length);
+    }
+    else if (path.startsWith('http://gitlab.com/')) {
+        path = path.slice('http://gitlab.com/'.length);
+    }
+    if (path.endsWith('.git')) {
+        path = path.slice(0, -'.git'.length);
+    }
+    return path;
+}

package/dist/lib/git-providers/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Git provider abstraction for branch detection and creation.
+ *
+ * Detection paths (`getBranch`, `detectDefaultBranch`) use `git ls-remote` over
+ * SSH/https and do not require any API token. Only `createBranch` performs a
+ * mutating API call and therefore requires provider credentials (e.g.
+ * `GITLAB_TOKEN`).
+ *
+ * No destructive semantics are exposed — there is no `force` flag anywhere in
+ * this surface. Idempotency is the caller's responsibility: callers must
+ * invoke `getBranch` before `createBranch`.
+ */
+export interface GetBranchOptions {
+    remoteUrl: string;
+    branchName: string;
+}
+export interface GetBranchResult {
+    exists: boolean;
+    sha?: string;
+}
+export interface CreateBranchOptions {
+    remoteUrl: string;
+    branchName: string;
+    fromSha: string;
+}
+export interface CreateBranchResult {
+    created: boolean;
+    sha: string;
+}
+export interface DetectDefaultBranchOptions {
+    remoteUrl: string;
+}
+export interface ListOpenPullRequestsOptions {
+    /** Repository identifier: "owner/repo" for GitHub, project path or numeric ID for GitLab */
+    repo: string;
+    /** Optional API token — overrides env var (GITHUB_TOKEN / GITLAB_TOKEN) */
+    token?: string;
+}
+export interface OpenPullRequest {
+    /** PR/MR number (GitHub) or IID (GitLab) */
+    number: number;
+    title: string;
+    /** Source branch name */
+    sourceBranch: string;
+    /** Author username */
+    author: string;
+    /** Web URL to the PR/MR */
+    url: string;
+}
+export interface GitProvider {
+    detectDefaultBranch(opts: DetectDefaultBranchOptions): Promise<string>;
+    getBranch(opts: GetBranchOptions): Promise<GetBranchResult>;
+    createBranch(opts: CreateBranchOptions): Promise<CreateBranchResult>;
+    listOpenPullRequests(opts: ListOpenPullRequestsOptions): Promise<OpenPullRequest[]>;
+}
+/**
+ * Factory — returns the git provider implementation for a given remote URL.
+ *
+ * Supports both GitLab (gitlab.com) and GitHub (github.com).
+ */
+export declare function getProviderForRemote(remoteUrl: string): GitProvider;
+/**
+ * Factory — returns the git provider implementation for a provider name.
+ *
+ * Used by CLI commands that accept `--provider` flag instead of a remote URL.
+ */
+export declare function getProviderByName(provider: 'github' | 'gitlab'): GitProvider;

package/dist/lib/git-providers/index.js

@@ -0,0 +1,39 @@
+/**
+ * Git provider abstraction for branch detection and creation.
+ *
+ * Detection paths (`getBranch`, `detectDefaultBranch`) use `git ls-remote` over
+ * SSH/https and do not require any API token. Only `createBranch` performs a
+ * mutating API call and therefore requires provider credentials (e.g.
+ * `GITLAB_TOKEN`).
+ *
+ * No destructive semantics are exposed — there is no `force` flag anywhere in
+ * this surface. Idempotency is the caller's responsibility: callers must
+ * invoke `getBranch` before `createBranch`.
+ */
+import { GitHubProvider } from './github.js';
+import { GitLabProvider } from './gitlab.js';
+/**
+ * Factory — returns the git provider implementation for a given remote URL.
+ *
+ * Supports both GitLab (gitlab.com) and GitHub (github.com).
+ */
+export function getProviderForRemote(remoteUrl) {
+    if (remoteUrl.includes('github.com')) {
+        return new GitHubProvider();
+    }
+    if (remoteUrl.includes('gitlab.com')) {
+        return new GitLabProvider();
+    }
+    throw new Error(`Unsupported git provider: ${remoteUrl}`);
+}
+/**
+ * Factory — returns the git provider implementation for a provider name.
+ *
+ * Used by CLI commands that accept `--provider` flag instead of a remote URL.
+ */
+export function getProviderByName(provider) {
+    if (provider === 'github') {
+        return new GitHubProvider();
+    }
+    return new GitLabProvider();
+}