@almadar/integrations 2.8.0 → 2.10.0

package/dist/integrations/github/index.d.ts

@@ -51,6 +51,80 @@ interface GitHubPushParams extends IntegrationParams {
     /** Working directory (defaults to workspace root) */
     workDir?: string;
 }
+/**
+ * GitHub `git init` parameters. Used to initialize an empty workspace
+ * directory as a git repo before the first commit/push to a freshly
+ * created remote.
+ */
+interface GitHubInitParams extends IntegrationParams {
+    /** Working directory to initialize. */
+    workDir: string;
+    /** Initial branch name (default: 'main'). */
+    initialBranch?: string;
+}
+/**
+ * GitHub `git pull` parameters. Used for cross-device workspace freshness
+ * — when a workspace is found locally but the linked repo may have moved
+ * ahead via commits from another device.
+ */
+interface GitHubPullParams extends IntegrationParams {
+    /** Branch name to pull. */
+    branchName: string;
+    /** Working directory (defaults to workspace root). */
+    workDir?: string;
+    /** Fast-forward only (default: true). When false, allows merge. */
+    ffOnly?: boolean;
+}
+/**
+ * GitHub `git remote add` parameters.
+ */
+interface GitHubAddRemoteParams extends IntegrationParams {
+    /** Remote name — typically 'origin'. */
+    name: string;
+    /** Remote URL (e.g., https://github.com/owner/repo). */
+    url: string;
+    /** Working directory (defaults to workspace root). */
+    workDir?: string;
+}
+/**
+ * GitHub `git config user.{name,email}` parameters. Set per-repo so
+ * individual commits don't need env-var juggling.
+ */
+interface GitHubSetUserConfigParams extends IntegrationParams {
+    /** `user.name` value. */
+    userName: string;
+    /** `user.email` value. */
+    userEmail: string;
+    /** Scope: 'local' (per-repo, default) or 'global'. */
+    scope?: 'local' | 'global';
+    /** Working directory (defaults to workspace root). Required for scope='local'. */
+    workDir?: string;
+}
+/**
+ * GitHub `git branch -M` parameters. Renames the current branch (or
+ * forces it to the new name when one already exists with that name).
+ * Used to align a workspace's local branch with the linked repo's
+ * default branch — `git init` defaults to `master` on older git
+ * versions, while every new GitHub repo defaults to `main`, so the
+ * first push needs the names to match.
+ */
+interface GitHubRenameBranchParams extends IntegrationParams {
+    /** New branch name (the current branch is renamed to this). */
+    newName: string;
+    /** Working directory (defaults to workspace root). */
+    workDir: string;
+}
+/**
+ * Pull outcome. Discriminates "the pull happened and updated state"
+ * from "no-op due to <reason>" so callers can route on it without
+ * stringy stderr parsing.
+ */
+interface GitHubPullResult {
+    /** True when the working tree advanced (one or more commits pulled). */
+    updated: boolean;
+    /** Reason a non-update pull returned. */
+    reason?: 'no-upstream' | 'conflict' | 'network' | 'up-to-date';
+}
 /**
  * GAP-104/105: GitHub create repository parameters.
  * Provider-agnostic: the same interface shape works for GitLab, Bitbucket, etc.
@@ -192,35 +266,6 @@ interface GitHubRateLimit {
     reset: number;
 }
 
-/**
- * Git CLI operations for GitHub integration
- */
-
-/**
- * Clone a repository
- */
-declare function cloneRepo(params: GitHubCloneParams, token: string): Promise<void>;
-/**
- * Create a new branch
- */
-declare function createBranch(params: GitHubCreateBranchParams, workDir: string): Promise<void>;
-/**
- * Commit changes
- */
-declare function commit(params: GitHubCommitParams, workDir: string): Promise<void>;
-/**
- * Push branch to remote
- */
-declare function push(params: GitHubPushParams, workDir: string, token: string): Promise<void>;
-/**
- * Get current branch name
- */
-declare function getCurrentBranch(workDir: string): Promise<string>;
-/**
- * Check if working directory has uncommitted changes
- */
-declare function hasUncommittedChanges(workDir: string): Promise<boolean>;
-
 /**
  * GitHub REST API client
  */
@@ -316,6 +361,84 @@ declare function parseRepoUrl(repoUrl: string): {
     repo: string;
 };
 
+/**
+ * Git CLI operations for GitHub integration
+ */
+
+/**
+ * Clone a repository
+ */
+declare function cloneRepo(params: GitHubCloneParams, token: string): Promise<void>;
+/**
+ * Create a new branch
+ */
+declare function createBranch(params: GitHubCreateBranchParams, workDir: string): Promise<void>;
+/**
+ * Commit changes
+ */
+declare function commit(params: GitHubCommitParams, workDir: string): Promise<void>;
+/**
+ * Push branch to remote
+ */
+declare function push(params: GitHubPushParams, workDir: string, token: string): Promise<void>;
+/**
+ * Get current branch name
+ */
+declare function getCurrentBranch(workDir: string): Promise<string>;
+/**
+ * Check if working directory has uncommitted changes
+ */
+declare function hasUncommittedChanges(workDir: string): Promise<boolean>;
+/**
+ * Initialize a git repository in `workDir`. No-op when `.git/` already
+ * exists. The default initial branch is `main` to match what GitHub
+ * creates for new repos.
+ */
+declare function init(params: GitHubInitParams): Promise<void>;
+/**
+ * Add a remote to the repository. Used after `init` to attach the
+ * freshly-created GitHub remote as `origin`.
+ */
+declare function addRemote(params: GitHubAddRemoteParams): Promise<void>;
+/**
+ * Set `user.name` and `user.email` for git commits. Scope defaults to
+ * per-repo (`--local`) so each workspace can carry the GitHub identity
+ * of the user who owns it — global config would clobber the developer's
+ * own machine settings.
+ */
+declare function setUserConfig(params: GitHubSetUserConfigParams): Promise<void>;
+/**
+ * Pull from the remote. Returns a structured outcome so callers can
+ * tell "the workspace advanced" from "nothing changed because <X>"
+ * without parsing git's stderr. Best-effort posture: network / conflict
+ * / no-upstream all resolve cleanly rather than throwing — the caller
+ * decides whether to surface the no-op as user-facing.
+ */
+declare function pull(params: GitHubPullParams, token: string): Promise<GitHubPullResult>;
+/**
+ * Return the current HEAD commit sha (full 40-char). Throws when the
+ * workspace has no commits yet (caller decides whether that's an error
+ * or an "init, then commit, then read" sequencing issue).
+ */
+declare function getHeadSha(workDir: string): Promise<string>;
+/**
+ * Return the current HEAD commit as a `GitHubCommit` shape. Reuses the
+ * canonical type from the REST module (no parallel `LocalCommit`
+ * interface). `stats` is absent — that's GitHub-API-only and would
+ * require a separate fetch to populate.
+ *
+ * The format string uses NUL (`%x00`) as a field separator so commit
+ * messages containing newlines / pipes can't break parsing.
+ */
+declare function getHeadCommit(workDir: string): Promise<GitHubCommit>;
+/**
+ * Rename the current branch with `git branch -M <newName>`. The `-M`
+ * (capital) flag forces the rename even if a branch with that name
+ * already exists, which is fine for our use case (aligning a fresh
+ * local workspace's branch with the linked repo's default branch).
+ */
+declare function renameCurrentBranch(params: GitHubRenameBranchParams): Promise<void>;
+
 /**
  * GitHub Integration for Almadar
  * Provides git operations and GitHub API access for the agent
@@ -372,4 +495,4 @@ declare class GitHubIntegration extends BaseIntegration {
     private getAPIConfig;
 }
 
-export { type GitHubAPIConfig, type GitHubCloneParams, type GitHubComment, type GitHubCommit, type GitHubCommitParams, type GitHubCreateBranchParams, type GitHubCreatePRParams, type GitHubCreateRepoParams, type GitHubGetIssueParams, type GitHubGetPRCommentsParams, GitHubIntegration, type GitHubIssue, type GitHubListIssuesParams, type GitHubPullRequest, type GitHubPushParams, type GitHubRateLimit, type GitHubRepoCreated, cloneRepo, commit, createBranch, createPR, createRepo, getCommitDiff, getCurrentBranch, getFileAtCommit, getIssue, getPRComments, getRateLimit, hasUncommittedChanges, listCommits, listIssues, listRepoTree, parseRepoUrl, push, readRepoFile };
+export { type GitHubAPIConfig, type GitHubAddRemoteParams, type GitHubCloneParams, type GitHubComment, type GitHubCommit, type GitHubCommitParams, type GitHubCreateBranchParams, type GitHubCreatePRParams, type GitHubCreateRepoParams, type GitHubGetIssueParams, type GitHubGetPRCommentsParams, type GitHubInitParams, GitHubIntegration, type GitHubIssue, type GitHubListIssuesParams, type GitHubPullParams, type GitHubPullRequest, type GitHubPullResult, type GitHubPushParams, type GitHubRateLimit, type GitHubRenameBranchParams, type GitHubRepoCreated, type GitHubSetUserConfigParams, addRemote, cloneRepo, commit, createBranch, createPR, createRepo, getCommitDiff, getCurrentBranch, getFileAtCommit, getHeadCommit, getHeadSha, getIssue, getPRComments, getRateLimit, hasUncommittedChanges, init, listCommits, listIssues, listRepoTree, parseRepoUrl, pull, push, readRepoFile, renameCurrentBranch, setUserConfig };

package/dist/integrations/github/index.js

@@ -374,6 +374,145 @@ async function hasUncommittedChanges(workDir) {
     );
   }
 }
+async function init(params) {
+  const { workDir, initialBranch = "main" } = params;
+  try {
+    await execGit(["init", "-b", initialBranch], workDir);
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to git init: ${error instanceof Error ? error.message : String(error)}`,
+      "SERVICE_ERROR",
+      { workDir, error }
+    );
+  }
+}
+async function addRemote(params) {
+  const { name, url, workDir } = params;
+  const cwd = workDir || params.workDir;
+  if (!cwd) {
+    throw new IntegrationError(
+      `addRemote requires workDir`,
+      "VALIDATION_ERROR",
+      { params }
+    );
+  }
+  try {
+    await execGit(["remote", "add", name, url], cwd);
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to add remote ${name}: ${error instanceof Error ? error.message : String(error)}`,
+      "SERVICE_ERROR",
+      { name, error }
+    );
+  }
+}
+async function setUserConfig(params) {
+  const { userName, userEmail, scope = "local", workDir } = params;
+  const scopeFlag = scope === "global" ? "--global" : "--local";
+  if (scope === "local" && !workDir) {
+    throw new IntegrationError(
+      `setUserConfig with scope='local' requires workDir`,
+      "VALIDATION_ERROR",
+      { params }
+    );
+  }
+  const cwd = workDir ?? process.cwd();
+  try {
+    await execGit(["config", scopeFlag, "user.name", userName], cwd);
+    await execGit(["config", scopeFlag, "user.email", userEmail], cwd);
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to set git user config: ${error instanceof Error ? error.message : String(error)}`,
+      "SERVICE_ERROR",
+      { error }
+    );
+  }
+}
+async function pull(params, token) {
+  const { branchName, ffOnly = true, workDir } = params;
+  const cwd = workDir || params.workDir;
+  if (!cwd) {
+    return { updated: false, reason: "no-upstream" };
+  }
+  let credHelper = null;
+  try {
+    credHelper = await createTempCredentialHelper(token);
+    const args = ["pull"];
+    if (ffOnly) args.push("--ff-only");
+    args.push("origin", branchName);
+    const { stdout } = await execGit(args, cwd, {
+      GIT_ASKPASS: credHelper,
+      GIT_TERMINAL_PROMPT: "0"
+    });
+    const updated = !/^Already up to date\.?\s*$/m.test(stdout.trim());
+    return updated ? { updated: true } : { updated: false, reason: "up-to-date" };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/no upstream|no such ref|couldn't find remote ref/i.test(message)) {
+      return { updated: false, reason: "no-upstream" };
+    }
+    if (/conflict|not possible to fast-forward|divergent/i.test(message)) {
+      return { updated: false, reason: "conflict" };
+    }
+    return { updated: false, reason: "network" };
+  } finally {
+    if (credHelper) {
+      try {
+        await promises.unlink(credHelper);
+      } catch {
+      }
+    }
+  }
+}
+async function getHeadSha(workDir) {
+  try {
+    const { stdout } = await execGit(["rev-parse", "HEAD"], workDir);
+    return stdout.trim();
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to get HEAD sha: ${error instanceof Error ? error.message : String(error)}`,
+      "SERVICE_ERROR",
+      { error }
+    );
+  }
+}
+async function getHeadCommit(workDir) {
+  try {
+    const FORMAT = "%H%x00%an%x00%ae%x00%aI%x00%B";
+    const { stdout } = await execGit(
+      ["show", "--no-patch", `--format=${FORMAT}`, "HEAD"],
+      workDir
+    );
+    const [sha, name, email, date, ...messageParts] = stdout.split("\0");
+    return {
+      sha: sha.trim(),
+      message: messageParts.join("\0").trimEnd(),
+      author: {
+        name: name?.trim() ?? "",
+        email: email?.trim() ?? "",
+        date: date?.trim() ?? ""
+      }
+    };
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to read HEAD commit: ${error instanceof Error ? error.message : String(error)}`,
+      "SERVICE_ERROR",
+      { error }
+    );
+  }
+}
+async function renameCurrentBranch(params) {
+  const { newName, workDir } = params;
+  try {
+    await execGit(["branch", "-M", newName], workDir);
+  } catch (error) {
+    throw new IntegrationError(
+      `Failed to rename branch to ${newName}: ${error instanceof Error ? error.message : String(error)}`,
+      "SERVICE_ERROR",
+      { newName, error }
+    );
+  }
+}
 
 // src/integrations/github/github-api.ts
 async function githubFetch(endpoint, config, options = {}) {
@@ -806,6 +945,6 @@ var GitHubIntegration = class extends BaseIntegration {
   }
 };
 
-export { GitHubIntegration, cloneRepo, commit, createBranch, createPR, createRepo, getCommitDiff, getCurrentBranch, getFileAtCommit, getIssue, getPRComments, getRateLimit, hasUncommittedChanges, listCommits, listIssues, listRepoTree, parseRepoUrl, push, readRepoFile };
+export { GitHubIntegration, addRemote, cloneRepo, commit, createBranch, createPR, createRepo, getCommitDiff, getCurrentBranch, getFileAtCommit, getHeadCommit, getHeadSha, getIssue, getPRComments, getRateLimit, hasUncommittedChanges, init, listCommits, listIssues, listRepoTree, parseRepoUrl, pull, push, readRepoFile, renameCurrentBranch, setUserConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map