@adobe/spacecat-shared-cloud-manager-client 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## @adobe/spacecat-shared-cloud-manager-client-v1.0.0 (2026-02-21)
+
+### Features
+
+* cloud manager client ([#1335](https://github.com/adobe/spacecat-shared/issues/1335)) ([2e4b013](https://github.com/adobe/spacecat-shared/commit/2e4b01359641706d633c16907b8292334581ce39))

package/README.md

@@ -0,0 +1,230 @@
+# Spacecat Shared - Cloud Manager Client
+
+A JavaScript client for Adobe Cloud Manager repository operations. It supports cloning, pulling, pushing, checking out refs, zipping/unzipping repositories, applying patches, and creating pull requests for both **BYOG (Bring Your Own Git)** and **standard** Cloud Manager repositories.
+
+The client is **stateless** with respect to repositories — no repo-specific information is stored on the instance. All repository details (`programId`, `repositoryId`, `imsOrgId`, `repoType`, `repoUrl`) are passed per method call. The only instance-level state is the cached IMS service token (shared across all repos) and generic configuration (CM API base URL, S3 client, git committer identity). This means a single `CloudManagerClient` instance can work across multiple repositories, programs, and IMS orgs within the same session.
+
+## Installation
+
+```bash
+npm install @adobe/spacecat-shared-cloud-manager-client
+```
+
+## Prerequisites
+
+This client executes native git commands and requires the **git binary** available at `/opt/bin/git` (e.g. via an AWS Lambda Layer). The Lambda layer must provide:
+
+- `git` binary at `/opt/bin/git`
+- Git sub-commands (e.g. `git-remote-https`) at `/opt/libexec/git-core/`
+- Shared libraries (`libcurl`, `libexpat`, etc.) at `/opt/lib/`
+
+The client also uses the system `unzip` command (available on AWS Lambda AL2023 runtime) for `unzipRepository`.
+
+The following environment variables are set automatically by the client for Lambda layer compatibility:
+
+| Variable | Value |
+|----------|-------|
+| `PATH` | `/opt/bin:/usr/local/bin:/usr/bin:/bin` |
+| `GIT_EXEC_PATH` | `/opt/libexec/git-core` |
+| `LD_LIBRARY_PATH` | `/opt/lib:/lib64:/usr/lib64` |
+| `GIT_TERMINAL_PROMPT` | `0` |
+
+## Configuration
+
+Create a client from a Helix Universal context (e.g. in a Lambda with the required middleware):
+
+```js
+import CloudManagerClient from '@adobe/spacecat-shared-cloud-manager-client';
+
+const client = CloudManagerClient.createFrom(context);
+```
+
+### Required environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `IMS_HOST` | IMS host (e.g. `ims-na1.adobelogin.com`) |
+| `ASO_CM_REPO_SERVICE_IMS_CLIENT_ID` | IMS client ID for the CM Repo Service |
+| `ASO_CM_REPO_SERVICE_IMS_CLIENT_SECRET` | IMS client secret |
+| `ASO_CM_REPO_SERVICE_IMS_CLIENT_CODE` | IMS authorization code |
+| `CM_REPO_URL` | Cloud Manager Repo API base URL (e.g. `https://cm-repo.example.com`) |
+| `ASO_CODE_AUTOFIX_USERNAME` | Git committer username |
+| `ASO_CODE_AUTOFIX_EMAIL` | Git committer email |
+
+The context must also provide an S3 client via `context.s3.s3Client` (e.g. using `s3Wrapper`).
+
+### Standard repository credentials (optional)
+
+For **standard** (non-BYOG) Cloud Manager repositories, provide credentials via:
+
+| Variable | Description |
+|----------|-------------|
+| `CM_STANDARD_REPO_CREDENTIALS` | JSON string mapping **program ID** to basic-auth credentials per program |
+
+**Format:** A single JSON object. Each key is a Cloud Manager **program ID** (string). Each value is the HTTP basic-auth credential for that program in the form `"username:accessToken"`.
+
+**Example:**
+
+```json
+{
+  "12345": "git-user:personal-access-token-or-password",
+  "67890": "another-user:another-token"
+}
+```
+
+- If `CM_STANDARD_REPO_CREDENTIALS` is omitted or empty, only BYOG repos can be used (clone/pull/push require IMS Bearer token and `imsOrgId`).
+- The value must be valid JSON; invalid JSON throws at `createFrom()`.
+- For a given **programId**, credentials must exist in this map when using `repoType: 'standard'`; otherwise the client throws at clone/pull/push time.
+
+## Repository types
+
+The client supports two authentication modes:
+
+| Type | Auth method | When to use |
+|------|-------------|-------------|
+| **BYOG** (Bring Your Own Git) | IMS Bearer token via `http.extraheader` | GitHub, GitLab, Bitbucket, Azure DevOps (or any `repoType` other than `'standard'`) |
+| **Standard** | Base64 Basic auth via `http.extraheader` | Cloud Manager "standard" (managed) repos |
+
+Both repo types authenticate via `http.extraheader` — no credentials are ever embedded in URLs. Use the same type for `clone`, `pull`, and `push` for a given repo (same `programId`/`repositoryId`).
+
+**Security notes:**
+
+- Clone directories are created via `mkdtempSync` under the OS temp directory, producing unique, unpredictable paths safe from symlink attacks and concurrent-run collisions.
+- Patch files are also written into unique temp directories, cleaned up in a `finally` block.
+- Git error output is sanitized before logging — Bearer tokens, Basic auth headers, `x-api-key`, `x-gw-ims-org-id` values, and basic-auth credentials in URLs are all replaced with `[REDACTED]`. Both `stderr`, `stdout`, and `error.message` are sanitized.
+- All git commands run with a 120-second timeout to prevent hung processes from blocking the Lambda.
+- `GIT_ASKPASS` is explicitly cleared to prevent inherited credential helpers from being invoked.
+
+## Usage
+
+### BYOG repositories (e.g. GitHub, GitLab)
+
+Clone and push use the IMS token and `imsOrgId`; no `CM_STANDARD_REPO_CREDENTIALS` needed.
+
+```js
+const programId = '12345';
+const repositoryId = '67890';
+const imsOrgId = 'your-ims-org@AdobeOrg';
+
+// Clone (optionally checkout a specific ref)
+const clonePath = await client.clone(programId, repositoryId, {
+  imsOrgId,
+  ref: 'release/5.11', // optional — checks out this ref after clone
+});
+
+// Pull latest changes (optional ref checks out the branch before pulling)
+await client.pull(clonePath, programId, repositoryId, { imsOrgId, ref: 'main' });
+
+// Checkout a specific ref (standalone, without pull)
+await client.checkout(clonePath, 'main');
+
+// Create a branch and apply a patch
+await client.createBranch(clonePath, 'main', 'feature/fix');
+
+// Apply a mail-message patch (git am — commit message is embedded in the patch)
+await client.applyPatch(clonePath, 'feature/fix', 's3://bucket/patches/fix.patch');
+
+// Apply a plain diff patch (git apply — commitMessage is required)
+await client.applyPatch(clonePath, 'feature/fix', 's3://bucket/patches/fix.diff', {
+  commitMessage: 'Apply agent suggestion: fix accessibility issue',
+});
+
+// Push (ref is required — specifies the branch to push)
+await client.push(clonePath, programId, repositoryId, { imsOrgId, ref: 'feature/fix' });
+
+// Create PR (BYOG only; uses IMS token)
+const pr = await client.createPullRequest(programId, repositoryId, {
+  imsOrgId,
+  sourceBranch: 'feature/fix',
+  destinationBranch: 'main',
+  title: 'Fix issue',
+  description: 'Automated fix',
+});
+```
+
+### Standard repositories
+
+Use credentials from `CM_STANDARD_REPO_CREDENTIALS` and pass `repoType: 'standard'` and the repo URL.
+
+```js
+const programId = '12345';
+const repositoryId = '67890';
+const imsOrgId = 'your-ims-org@AdobeOrg';
+const repoUrl = 'https://git.cloudmanager.adobe.com/your-org/your-repo.git';
+
+const config = {
+  imsOrgId,
+  repoType: 'standard',
+  repoUrl,
+  ref: 'main', // optional — checks out this ref after clone
+};
+
+// Clone
+const clonePath = await client.clone(programId, repositoryId, config);
+
+// Pull latest changes (optional ref checks out the branch before pulling)
+await client.pull(clonePath, programId, repositoryId, { imsOrgId, repoType: 'standard', repoUrl, ref: 'main' });
+
+// Create a branch and apply a patch
+await client.createBranch(clonePath, 'main', 'feature/fix');
+await client.applyPatch(clonePath, 'feature/fix', 's3://bucket/patches/fix.patch', {
+  commitMessage: 'Apply agent suggestion',
+});
+
+// Push (ref is required — specifies the branch to push)
+await client.push(clonePath, programId, repositoryId, {
+  imsOrgId, repoType: 'standard', repoUrl, ref: 'feature/fix',
+});
+
+// Zip the repository (includes .git history)
+const zipBuffer = await client.zipRepository(clonePath);
+
+// Cleanup
+await client.cleanup(clonePath);
+```
+
+*Note*: For Cloud Manager Standard Repositories, pull requests aren't supported, as there's no upstream.
+
+
+## API overview
+
+- **`clone(programId, repositoryId, config)`** – Clone repo to a unique temp directory. Config: `{ imsOrgId, repoType, repoUrl, ref }`. Optional `ref` checks out a specific branch/tag after clone (failure to checkout does not fail the clone).
+- **`pull(clonePath, programId, repositoryId, config)`** – Pull latest changes into an existing clone. Config: `{ imsOrgId, repoType, repoUrl, ref }`. Optional `ref` checks out the branch before pulling.
+- **`push(clonePath, programId, repositoryId, config)`** – Push a ref to the remote. Config: `{ imsOrgId, repoType, repoUrl, ref }`. The `ref` is **required** and specifies the branch to push.
+- **`checkout(clonePath, ref)`** – Checkout a specific git ref (branch, tag, or SHA) in an existing clone. Unlike the optional checkout in `clone()`, this throws on failure.
+- **`zipRepository(clonePath)`** – Zip the clone (including `.git` history) and return a Buffer.
+- **`unzipRepository(zipBuffer)`** – Extract a ZIP buffer to a new temp directory and return the path. Used for incremental updates (restore a previously-zipped repo from S3, then `pull` with `ref` instead of a full clone). Cleans up on failure.
+- **`createBranch(clonePath, baseBranch, newBranch)`** – Checkout the base branch and create a new branch from it.
+- **`applyPatch(clonePath, branch, s3PatchPath, options?)`** – Download a patch from S3 (`s3://bucket/key` format) and apply it. The patch format is detected automatically from the content, not the file extension. Mail-message patches (content starts with `From `) are applied with `git am`, which creates the commit using the embedded metadata. Plain diffs (content starts with `diff `) are applied with `git apply`, staged with `git add -A`, and committed — `options.commitMessage` is required for this flow. If `commitMessage` is provided with a mail-message patch, it is ignored and a warning is logged. Configures committer identity from `ASO_CODE_AUTOFIX_USERNAME`/`ASO_CODE_AUTOFIX_EMAIL`. Cleans up the temp patch file in a `finally` block.
+- **`cleanup(clonePath)`** – Remove the clone directory. Validates the path starts with the expected temp prefix to prevent accidental deletion.
+- **`createPullRequest(programId, repositoryId, config)`** – Create a PR via the CM Repo API (BYOG only, uses IMS token). Config: `{ imsOrgId, sourceBranch, destinationBranch, title, description }`.
+
+## Exports
+
+Repository type constants (for use when passing `repoType` or checking repo type):
+
+```js
+import CloudManagerClient, { CM_REPO_TYPE } from '@adobe/spacecat-shared-cloud-manager-client';
+
+// CM_REPO_TYPE.GITHUB      → 'github'
+// CM_REPO_TYPE.BITBUCKET    → 'bitbucket'
+// CM_REPO_TYPE.GITLAB       → 'gitlab'
+// CM_REPO_TYPE.AZURE_DEVOPS → 'azure_devops'
+// CM_REPO_TYPE.STANDARD     → 'standard'
+```
+
+## Testing
+
+```bash
+npm run test
+```
+
+## Linting
+
+```bash
+npm run lint
+```
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@adobe/spacecat-shared-cloud-manager-client",
+  "version": "1.0.0",
+  "description": "Shared modules of the Spacecat Services - Cloud Manager Client",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0 <25.0.0",
+    "npm": ">=10.9.0 <12.0.0"
+  },
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "c8 mocha",
+    "lint": "eslint .",
+    "clean": "rm -rf package-lock.json node_modules"
+  },
+  "mocha": {
+    "require": "test/setup-env.js",
+    "reporter": "mocha-multi-reporters",
+    "reporter-options": "configFile=.mocha-multi.json",
+    "spec": "test/**/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/spacecat-shared.git"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/adobe/spacecat-shared/issues"
+  },
+  "homepage": "https://github.com/adobe/spacecat-shared#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@adobe/fetch": "4.2.3",
+    "@adobe/spacecat-shared-ims-client": "1.11.6",
+    "@adobe/spacecat-shared-utils": "1.81.1",
+    "@aws-sdk/client-s3": "3.940.0",
+    "adm-zip": "0.5.16"
+  },
+  "devDependencies": {
+    "aws-sdk-client-mock": "4.1.0",
+    "chai": "6.2.1",
+    "chai-as-promised": "8.0.2",
+    "nock": "14.0.10",
+    "sinon": "21.0.0",
+    "esmock": "2.7.3",
+    "sinon-chai": "4.0.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { UniversalContext } from '@adobe/helix-universal';
+
+export declare const CM_REPO_TYPE: Readonly<{
+  GITHUB: 'github';
+  BITBUCKET: 'bitbucket';
+  GITLAB: 'gitlab';
+  AZURE_DEVOPS: 'azure_devops';
+  STANDARD: 'standard';
+}>;
+
+export interface CloneConfig {
+  imsOrgId: string;
+  repoType: string;
+  repoUrl: string;
+  ref?: string;
+}
+
+export interface PushConfig {
+  imsOrgId: string;
+  repoType: string;
+  repoUrl: string;
+  ref: string;
+}
+
+export interface PullConfig {
+  imsOrgId: string;
+  repoType: string;
+  repoUrl: string;
+  ref?: string;
+}
+
+export interface PullRequestConfig {
+  imsOrgId: string;
+  destinationBranch: string;
+  sourceBranch: string;
+  title: string;
+  description: string;
+}
+
+export default class CloudManagerClient {
+  static createFrom(context: UniversalContext): CloudManagerClient;
+
+  clone(programId: string, repositoryId: string, config: CloneConfig): Promise<string>;
+  push(clonePath: string, programId: string, repositoryId: string, config: PushConfig): Promise<void>;
+  pull(clonePath: string, programId: string, repositoryId: string, config: PullConfig): Promise<void>;
+  checkout(clonePath: string, ref: string): Promise<void>;
+  unzipRepository(zipBuffer: Buffer): Promise<string>;
+  zipRepository(clonePath: string): Promise<Buffer>;
+  createBranch(clonePath: string, baseBranch: string, newBranch: string): Promise<void>;
+  applyPatch(
+    clonePath: string,
+    branch: string,
+    s3PatchPath: string,
+    options?: { commitMessage?: string },
+  ): Promise<void>;
+  cleanup(clonePath: string): Promise<void>;
+  createPullRequest(
+    programId: string,
+    repositoryId: string,
+    config: PullRequestConfig,
+  ): Promise<object>;
+}

package/src/index.js

@@ -0,0 +1,555 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { execFileSync } from 'child_process';
+import {
+  existsSync, mkdtempSync, rmSync, statfsSync, writeFileSync,
+} from 'fs';
+import os from 'os';
+import path from 'path';
+import { hasText, tracingFetch as fetch } from '@adobe/spacecat-shared-utils';
+import { ImsClient } from '@adobe/spacecat-shared-ims-client';
+import { GetObjectCommand } from '@aws-sdk/client-s3';
+import AdmZip from 'adm-zip';
+
+const GIT_BIN = process.env.GIT_BIN_PATH || '/opt/bin/git';
+const CLONE_DIR_PREFIX = 'cm-repo-';
+const PATCH_FILE_PREFIX = 'cm-patch-';
+const GIT_OPERATION_TIMEOUT_MS = 120_000; // 120s — fail fast before Lambda timeout
+
+/**
+ * Repository type constants for Cloud Manager integrations.
+ * Standard repos use basic auth; all others (BYOG) use Bearer token extraheaders.
+ */
+export const CM_REPO_TYPE = Object.freeze({
+  GITHUB: 'github',
+  BITBUCKET: 'bitbucket',
+  GITLAB: 'gitlab',
+  AZURE_DEVOPS: 'azure_devops',
+  STANDARD: 'standard',
+});
+
+// Lambda layer environment: git and its helpers (git-remote-https) live under /opt.
+// Without these, the dynamic linker can't find shared libraries (libcurl, libexpat, …)
+// and git can't locate its sub-commands (git-remote-https for HTTPS transport).
+const GIT_ENV = {
+  ...process.env,
+  PATH: '/opt/bin:/usr/local/bin:/usr/bin:/bin',
+  GIT_EXEC_PATH: '/opt/libexec/git-core',
+  LD_LIBRARY_PATH: '/opt/lib:/lib64:/usr/lib64',
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_ASKPASS: '',
+};
+
+/**
+ * Parses an S3 URI (s3://bucket/key) into bucket and key.
+ * @param {string} s3Path - S3 URI
+ * @returns {{ bucket: string, key: string }}
+ */
+function parseS3Path(s3Path) {
+  let parsed;
+  try {
+    parsed = new URL(s3Path);
+  } catch {
+    throw new Error(`Invalid S3 path: ${s3Path}. Expected format: s3://bucket/key`);
+  }
+  if (parsed.protocol !== 's3:' || !parsed.hostname || !parsed.pathname.slice(1)) {
+    throw new Error(`Invalid S3 path: ${s3Path}. Expected format: s3://bucket/key`);
+  }
+  return { bucket: parsed.hostname, key: parsed.pathname.slice(1) };
+}
+
+export default class CloudManagerClient {
+  /**
+   * Creates a CloudManagerClient from a Universal context.
+   * @param {Object} context - Universal function context
+   * @returns {CloudManagerClient}
+   */
+  static createFrom(context) {
+    const { log = console } = context;
+    const {
+      IMS_HOST: imsHost,
+      ASO_CM_REPO_SERVICE_IMS_CLIENT_ID: clientId,
+      ASO_CM_REPO_SERVICE_IMS_CLIENT_SECRET: clientSecret,
+      ASO_CM_REPO_SERVICE_IMS_CLIENT_CODE: clientCode,
+      CM_REPO_URL: cmRepoUrl,
+      CM_STANDARD_REPO_CREDENTIALS: standardRepoCredentialsRaw,
+      ASO_CODE_AUTOFIX_USERNAME: gitUsername,
+      ASO_CODE_AUTOFIX_EMAIL: gitUserEmail,
+    } = context.env;
+
+    const s3Client = context.s3?.s3Client;
+    if (!s3Client) {
+      throw new Error('CloudManagerClient requires S3 client. Ensure s3Wrapper is configured.');
+    }
+
+    if (!hasText(imsHost) || !hasText(clientId) || !hasText(clientSecret) || !hasText(clientCode)) {
+      throw new Error('CloudManagerClient requires IMS_HOST, ASO_CM_REPO_SERVICE_IMS_CLIENT_ID,'
+        + ' ASO_CM_REPO_SERVICE_IMS_CLIENT_SECRET, and ASO_CM_REPO_SERVICE_IMS_CLIENT_CODE.');
+    }
+
+    if (!hasText(cmRepoUrl)) {
+      throw new Error('CloudManagerClient requires CM_REPO_URL.');
+    }
+
+    if (!hasText(gitUsername) || !hasText(gitUserEmail)) {
+      throw new Error('CloudManagerClient requires ASO_CODE_AUTOFIX_USERNAME and ASO_CODE_AUTOFIX_EMAIL.');
+    }
+
+    // Optional: credentials for standard (non-BYOG) CM repos.
+    // JSON object mapping programId to "username:accessToken".
+    let standardRepoCredentials = {};
+    if (hasText(standardRepoCredentialsRaw)) {
+      try {
+        standardRepoCredentials = JSON.parse(standardRepoCredentialsRaw);
+      } catch (e) {
+        throw new Error('CM_STANDARD_REPO_CREDENTIALS must be valid JSON.');
+      }
+    }
+
+    // Create ImsClient for token management (handles caching internally)
+    const imsClient = ImsClient.createFrom({
+      env: {
+        IMS_HOST: imsHost,
+        IMS_CLIENT_ID: clientId,
+        IMS_CLIENT_CODE: clientCode,
+        IMS_CLIENT_SECRET: clientSecret,
+      },
+      log,
+    });
+
+    return new CloudManagerClient({
+      clientId,
+      cmRepoUrl,
+      standardRepoCredentials,
+      gitUsername,
+      gitUserEmail,
+    }, imsClient, s3Client, log);
+  }
+
+  constructor(config, imsClient, s3Client, log = console) {
+    this.config = config;
+    this.imsClient = imsClient;
+    this.s3Client = s3Client;
+    this.log = log;
+  }
+
+  // --- Private helpers ---
+
+  /**
+   * Logs /tmp disk usage (total, used, free) for capacity monitoring.
+   * Uses statfsSync — a single syscall with negligible cost.
+   * @param {string} operation - The operation that just completed (e.g. 'clone', 'pull')
+   */
+  #logTmpDiskUsage(operation) {
+    const { bsize, blocks, bfree } = statfsSync(os.tmpdir());
+    const totalMB = Math.round((bsize * blocks) / (1024 * 1024));
+    const freeMB = Math.round((bsize * bfree) / (1024 * 1024));
+    const usedMB = totalMB - freeMB;
+    this.log.info(`[${operation}] /tmp disk usage: ${usedMB} MB used, ${freeMB} MB free, ${totalMB} MB total`);
+  }
+
+  /**
+   * Looks up basic-auth credentials for a standard (non-BYOG) CM repository.
+   * @param {string} programId - CM Program ID
+   * @returns {string} "username:accessToken"
+   */
+  #getStandardRepoCredentials(programId) {
+    const credentials = this.config.standardRepoCredentials[programId];
+    if (!credentials) {
+      throw new Error(`No standard repo credentials found for programId: ${programId}. Check CM_STANDARD_REPO_CREDENTIALS.`);
+    }
+    return credentials;
+  }
+
+  /**
+   * Builds the git -c http.extraheader arguments for CM repo auth.
+   * @param {string} imsOrgId - IMS Organization ID
+   * @returns {Promise<string[]>} Array of git config args
+   */
+  async #getCMRepoServiceCredentials(imsOrgId) {
+    const { access_token: token } = await this.imsClient.getServiceAccessToken();
+    const { cmRepoUrl, clientId } = this.config;
+
+    return [
+      '-c', `http.${cmRepoUrl}.extraheader=Authorization: Bearer ${token}`,
+      '-c', `http.${cmRepoUrl}.extraheader=x-api-key: ${clientId}`,
+      '-c', `http.${cmRepoUrl}.extraheader=x-gw-ims-org-id: ${imsOrgId}`,
+    ];
+  }
+
+  /**
+   * Constructs the git repository URL for a CM repo.
+   * @param {string} programId
+   * @param {string} repositoryId
+   * @returns {string}
+   */
+  #getRepoUrl(programId, repositoryId) {
+    return `${this.config.cmRepoUrl}/api/program/${programId}/repository/${repositoryId}.git`;
+  }
+
+  /**
+   * Executes a git command.
+   * @param {string[]} args - Arguments to pass to git
+   * @param {Object} [options] - execFileSync options
+   * @returns {string} stdout
+   */
+  #execGit(args, options = {}) {
+    try {
+      return execFileSync(GIT_BIN, args, {
+        encoding: 'utf-8', env: GIT_ENV, timeout: GIT_OPERATION_TIMEOUT_MS, ...options,
+      });
+    } catch (error) {
+      if (error.killed) {
+        this.log.error(`Git command timed out after ${GIT_OPERATION_TIMEOUT_MS / 1000}s`);
+        throw new Error(`Git command timed out after ${GIT_OPERATION_TIMEOUT_MS / 1000}s`);
+      }
+      // Sanitize tokens and credentials from all error output sources
+      const rawMessage = [error.stderr, error.stdout, error.message]
+        .filter(Boolean)
+        .join('\n');
+      const sanitized = rawMessage
+        .replace(/Bearer [^\s"]+/g, 'Bearer [REDACTED]')
+        .replace(/:\/\/[^@]+@/g, '://***@')
+        .replace(/x-api-key: [^\s"]+/g, 'x-api-key: [REDACTED]')
+        .replace(/x-gw-ims-org-id: [^\s"]+/g, 'x-gw-ims-org-id: [REDACTED]')
+        .replace(/Authorization: Basic [^\s"]+/g, 'Authorization: Basic [REDACTED]');
+      this.log.error(`Git command failed: ${sanitized}`);
+      throw new Error(`Git command failed: ${sanitized}`);
+    }
+  }
+
+  /**
+   * Builds authenticated git arguments for a remote command (clone, push, or pull).
+   *
+   * Both repo types use http.extraheader for authentication:
+   * - Standard repos: Basic auth header via extraheader on the repo URL
+   * - BYOG repos: Bearer token + API key + IMS org ID via extraheader on the CM Repo URL
+   *
+   * @param {string} command - The git command ('clone', 'push', or 'pull')
+   * @param {string} programId - CM Program ID
+   * @param {string} repositoryId - CM Repository ID
+   * @param {Object} config - Repository auth configuration
+   * @param {string} config.imsOrgId - IMS Organization ID
+   * @param {string} config.repoType - Repository type ('standard' or VCS type)
+   * @param {string} config.repoUrl - Repository URL
+   * @returns {Promise<string[]>} Array of git arguments
+   */
+  async #buildAuthGitArgs(command, programId, repositoryId, { imsOrgId, repoType, repoUrl } = {}) {
+    if (repoType === CM_REPO_TYPE.STANDARD) {
+      const credentials = this.#getStandardRepoCredentials(programId);
+      const basicAuth = Buffer.from(credentials).toString('base64');
+      return [
+        '-c', `http.${repoUrl}.extraheader=Authorization: Basic ${basicAuth}`,
+        command, repoUrl,
+      ];
+    }
+
+    const cmRepoServiceCredentials = await this.#getCMRepoServiceCredentials(imsOrgId);
+    const byogRepoUrl = this.#getRepoUrl(programId, repositoryId);
+    return [...cmRepoServiceCredentials, command, byogRepoUrl];
+  }
+
+  /**
+   * Clones a Cloud Manager repository to /tmp.
+   *
+   * Both repo types authenticate via http.extraheader (no credentials in the URL):
+   * - BYOG repos: Bearer token + API key + IMS org ID via CM Repo URL
+   * - Standard repos: Basic auth header via the repo URL
+   *
+   * If a ref is provided, the clone will be checked out to that ref after cloning.
+   * Checkout failures are logged but do not cause the clone to fail, so the caller
+   * always gets a usable working copy (on the default branch if checkout fails).
+   *
+   * @param {string} programId - CM Program ID
+   * @param {string} repositoryId - CM Repository ID
+   * @param {Object} config - Clone configuration
+   * @param {string} config.imsOrgId - IMS Organization ID
+   * @param {string} config.repoType - Repository type ('standard' or VCS type)
+   * @param {string} config.repoUrl - Repository URL
+   * @param {string} [config.ref] - Optional. Git ref to checkout after clone (branch, tag, or SHA)
+   * @returns {Promise<string>} The local clone path
+   */
+  async clone(programId, repositoryId, {
+    imsOrgId, repoType, repoUrl, ref,
+  } = {}) {
+    const clonePath = mkdtempSync(path.join(os.tmpdir(), CLONE_DIR_PREFIX));
+
+    try {
+      this.log.info(`Cloning CM repository: program=${programId}, repo=${repositoryId}, type=${repoType}`);
+
+      const args = await this.#buildAuthGitArgs('clone', programId, repositoryId, { imsOrgId, repoType, repoUrl });
+      this.#execGit([...args, clonePath]);
+      this.log.info(`Repository cloned to ${clonePath}`);
+      this.#logTmpDiskUsage('clone');
+
+      // Checkout the requested ref if provided
+      if (hasText(ref)) {
+        try {
+          this.#execGit(['checkout', ref], { cwd: clonePath });
+          this.log.info(`Checked out ref '${ref}' in ${clonePath}`);
+        } catch (error) {
+          this.log.error(`Failed to checkout ref '${ref}': ${error.message}. Continuing with default branch.`);
+        }
+      }
+
+      return clonePath;
+    } catch (error) {
+      rmSync(clonePath, { recursive: true, force: true });
+      throw error;
+    }
+  }
+
+  /**
+   * Zips the entire cloned repository including .git history.
+   * Downstream services that read the ZIP from S3 need the full git history.
+   * @param {string} clonePath - Path to the cloned repository
+   * @returns {Promise<Buffer>} ZIP file as a Buffer
+   */
+  async zipRepository(clonePath) {
+    if (!existsSync(clonePath)) {
+      throw new Error(`Clone path does not exist: ${clonePath}`);
+    }
+
+    this.log.info(`Zipping repository at ${clonePath}`);
+    const zip = new AdmZip();
+    zip.addLocalFolder(clonePath);
+    return zip.toBuffer();
+  }
+
+  /**
+   * Creates a new branch from a base branch.
+   * @param {string} clonePath - Path to the cloned repository
+   * @param {string} baseBranch - Base branch name
+   * @param {string} newBranch - New branch name
+   */
+  async createBranch(clonePath, baseBranch, newBranch) {
+    this.log.info(`Creating branch ${newBranch} from ${baseBranch}`);
+    this.#execGit(['checkout', baseBranch], { cwd: clonePath });
+    this.#execGit(['checkout', '-b', newBranch], { cwd: clonePath });
+  }
+
+  /**
+   * Downloads a patch from S3 and applies it to the given branch.
+   * Supports two patch formats, detected automatically from the content:
+   * - Mail-message format (starts with "From "): applied via git am, which
+   *   creates the commit using embedded metadata (author, date, message).
+   * - Plain diff format (starts with "diff "): applied via git apply, then
+   *   staged and committed. A commitMessage option is required for this flow.
+   * @param {string} clonePath - Path to the cloned repository
+   * @param {string} branch - Branch to apply the patch on
+   * @param {string} s3PatchPath - S3 URI of the patch file (s3://bucket/key)
+   * @param {object} [options] - Optional settings
+   * @param {string} [options.commitMessage] - Commit message for plain diff patches. Required
+   *   when the patch is a plain diff. Ignored for mail-message patches (git am uses the
+   *   embedded commit message); a warning is logged if provided with a mail-message patch.
+   */
+  async applyPatch(clonePath, branch, s3PatchPath, options = {}) {
+    const { bucket, key } = parseS3Path(s3PatchPath);
+    const patchDir = mkdtempSync(path.join(os.tmpdir(), PATCH_FILE_PREFIX));
+    const patchFile = path.join(patchDir, 'applied.patch');
+    const { gitUsername, gitUserEmail } = this.config;
+
+    try {
+      // Download patch from S3
+      this.log.info(`Downloading patch from s3://${bucket}/${key}`);
+      const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+      const response = await this.s3Client.send(command);
+      const patchContent = await response.Body.transformToString();
+      writeFileSync(patchFile, patchContent);
+
+      // Configure committer identity
+      this.#execGit(['config', 'user.name', gitUsername], { cwd: clonePath });
+      this.#execGit(['config', 'user.email', gitUserEmail], { cwd: clonePath });
+
+      // Checkout branch
+      this.#execGit(['checkout', branch], { cwd: clonePath });
+
+      // Detect format from content and apply accordingly
+      const isMailMessage = patchContent.startsWith('From ');
+      const { commitMessage } = options;
+
+      if (isMailMessage) {
+        // Mail-message format: git am creates the commit using embedded metadata
+        if (commitMessage) {
+          this.log.warn('commitMessage is ignored for mail-message patches; git am uses the embedded commit message');
+        }
+        this.#execGit(['am', patchFile], { cwd: clonePath });
+      } else {
+        // Plain diff format: apply, stage, and commit
+        if (!commitMessage) {
+          throw new Error('commitMessage is required when applying a plain diff patch');
+        }
+        this.#execGit(['apply', patchFile], { cwd: clonePath });
+        this.#execGit(['add', '-A'], { cwd: clonePath });
+        this.#execGit(['commit', '-m', commitMessage], { cwd: clonePath });
+      }
+
+      this.log.info(`Patch applied and committed on branch ${branch}`);
+    } finally {
+      // Clean up temp patch directory and file
+      if (existsSync(patchDir)) {
+        rmSync(patchDir, { recursive: true, force: true });
+      }
+    }
+  }
+
+  /**
+   * Pushes the current branch to the remote CM repository.
+   * Commits are expected to already exist (e.g. via applyPatch).
+   *
+   * For BYOG repos: uses Bearer token + API key + IMS org ID via extraheader.
+   * For standard repos: uses Basic auth via extraheader.
+   *
+   * @param {string} clonePath - Path to the cloned repository
+   * @param {string} programId - CM Program ID
+   * @param {string} repositoryId - CM Repository ID
+   * @param {Object} config - Push configuration
+   * @param {string} config.imsOrgId - IMS Organization ID
+   * @param {string} config.repoType - Repository type ('standard' or VCS type)
+   * @param {string} config.repoUrl - Repository URL
+   * @param {string} config.ref - Git ref (branch) to push
+   */
+  async push(clonePath, programId, repositoryId, {
+    imsOrgId, repoType, repoUrl, ref,
+  } = {}) {
+    const pushArgs = await this.#buildAuthGitArgs('push', programId, repositoryId, { imsOrgId, repoType, repoUrl });
+    pushArgs.push(ref);
+    this.#execGit(pushArgs, { cwd: clonePath });
+    this.log.info('Changes pushed successfully');
+    this.#logTmpDiskUsage('push');
+  }
+
+  /**
+   * Pulls the latest changes from the remote CM repository into an existing clone.
+   *
+   * For BYOG repos: uses Bearer token + API key + IMS org ID via extraheader.
+   * For standard repos: uses Basic auth via extraheader.
+   *
+   * If a ref is provided, the ref is checked out before pulling so that
+   * the pull updates the correct branch.
+   *
+   * @param {string} clonePath - Path to the cloned repository
+   * @param {string} programId - CM Program ID
+   * @param {string} repositoryId - CM Repository ID
+   * @param {Object} config - Pull configuration
+   * @param {string} config.imsOrgId - IMS Organization ID
+   * @param {string} config.repoType - Repository type ('standard' or VCS type)
+   * @param {string} config.repoUrl - Repository URL
+   * @param {string} [config.ref] - Optional. Git ref to checkout before pull (branch, tag, or SHA)
+   */
+  async pull(clonePath, programId, repositoryId, {
+    imsOrgId, repoType, repoUrl, ref,
+  } = {}) {
+    if (hasText(ref)) {
+      this.#execGit(['checkout', ref], { cwd: clonePath });
+      this.log.info(`Checked out ref '${ref}' before pull`);
+    }
+    const pullArgs = await this.#buildAuthGitArgs('pull', programId, repositoryId, { imsOrgId, repoType, repoUrl });
+    this.#execGit(pullArgs, { cwd: clonePath });
+    this.log.info('Changes pulled successfully');
+    this.#logTmpDiskUsage('pull');
+  }
+
+  /**
+   * Checks out a specific git ref (branch, tag, or SHA) in an existing repository.
+   *
+   * @param {string} clonePath - Path to the cloned repository
+   * @param {string} ref - Git ref to checkout (branch, tag, or SHA)
+   */
+  async checkout(clonePath, ref) {
+    this.log.info(`Checking out ref '${ref}' in ${clonePath}`);
+    this.#execGit(['checkout', ref], { cwd: clonePath });
+  }
+
+  /**
+   * Extracts a ZIP buffer into a new unique temp directory.
+   * Used to restore a previously-zipped repository from S3
+   * for incremental updates (checkout + pull) instead of a full clone.
+   *
+   * @param {Buffer} zipBuffer - ZIP file content as a Buffer
+   * @returns {Promise<string>} Path to the extracted repository
+   */
+  async unzipRepository(zipBuffer) {
+    const extractPath = mkdtempSync(path.join(os.tmpdir(), CLONE_DIR_PREFIX));
+
+    try {
+      const zip = new AdmZip(zipBuffer);
+      zip.extractAllTo(extractPath, true);
+      this.log.info(`Repository extracted to ${extractPath}`);
+      return extractPath;
+    } catch (error) {
+      rmSync(extractPath, { recursive: true, force: true });
+      throw new Error(`Failed to unzip repository: ${error.message}`);
+    }
+  }
+
+  /**
+   * Removes a cloned repository from the temp directory.
+   * @param {string} clonePath - Path to remove
+   */
+  async cleanup(clonePath) {
+    const expectedPrefix = path.join(os.tmpdir(), CLONE_DIR_PREFIX);
+    if (!clonePath || !clonePath.startsWith(expectedPrefix)) {
+      throw new Error(`Invalid clone path for cleanup: ${clonePath}. Must be a cm-repo temp directory.`);
+    }
+
+    if (existsSync(clonePath)) {
+      rmSync(clonePath, { recursive: true, force: true });
+      this.log.info(`Cleaned up ${clonePath}`);
+    }
+  }
+
+  /**
+   * Creates a pull request in a CM repository via the CM Repo REST API.
+   * @param {string} programId - CM Program ID
+   * @param {string} repositoryId - CM Repository ID
+   * @param {Object} config - PR configuration
+   * @param {string} config.imsOrgId - IMS Organization ID
+   * @param {string} config.destinationBranch - Branch to merge into (base)
+   * @param {string} config.sourceBranch - Branch that contains the changes (head)
+   * @param {string} config.title - PR title
+   * @param {string} config.description - PR description
+   * @returns {Promise<Object>}
+   */
+  async createPullRequest(programId, repositoryId, {
+    imsOrgId, destinationBranch, sourceBranch, title, description,
+  }) {
+    const { access_token: token } = await this.imsClient.getServiceAccessToken();
+    const url = `${this.config.cmRepoUrl}/api/program/${programId}/repository/${repositoryId}/pullRequests`;
+
+    this.log.info(`Creating PR for program=${programId}, repo=${repositoryId}: ${title}`);
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+        'x-api-key': this.config.clientId,
+        'x-gw-ims-org-id': imsOrgId,
+      },
+      body: JSON.stringify({
+        title,
+        sourceBranch,
+        destinationBranch,
+        description,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Pull request creation failed: ${response.status} - ${errorText}`);
+    }
+
+    return response.json();
+  }
+}