@simplysf/simply-cicd-core 0.2.0

package/lib/vcs/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/vcs/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuC,CAAC;AAEjE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAqB,EAAE,OAA2B;IACpF,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACtC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB,CAAC,IAAqB,EAAE,OAA2B;IAClF,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAc,6CAA6C,KAAK,GAAG,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC"}

package/lib/vcs/types.d.ts

@@ -0,0 +1,136 @@
+/** The set of source-control-hosting platforms `simply-cicd` knows how to talk to. */
+export type VcsProviderKind = 'gitlab' | 'github';
+/** A repository/project, normalized across VCS platforms. */
+export type VcsProject = {
+    id: number;
+    /**
+     * How this provider addresses the project in its own API: the numeric ID for GitLab,
+     * `owner/repo` for GitHub. Prefer this over `id` when passing a project to provider methods.
+     */
+    key: string;
+    name: string;
+    pathWithNamespace: string;
+    defaultBranch?: string;
+    archived: boolean;
+    empty: boolean;
+    isFork: boolean;
+    /** The raw, platform-specific API response this was derived from. */
+    raw: unknown;
+};
+/**
+ * A project as accepted by `VcsProvider` methods: either a normalized `VcsProject` or a bare
+ * provider-native key (a GitLab numeric ID, a GitHub `owner/repo`).
+ */
+export type VcsProjectRef = string | number | Pick<VcsProject, 'key'>;
+/** A branch, normalized across VCS platforms. */
+export type VcsBranch = {
+    name: string;
+    raw: unknown;
+};
+/** The result of a file-content commit, normalized across VCS platforms. */
+export type VcsCommit = {
+    id?: string;
+    raw: unknown;
+};
+/** A single commit as returned by a ref-to-ref comparison, normalized across VCS platforms. */
+export type VcsCommitLogEntry = {
+    sha?: string;
+    message: string;
+    raw: unknown;
+};
+/**
+ * A merge/pull request, normalized across VCS platforms. `iid` is the number the platform shows
+ * users and accepts in its per-request endpoints — GitLab's `iid`, GitHub's PR `number`.
+ */
+export type VcsMergeRequest = {
+    id: number;
+    iid: number;
+    title: string;
+    description?: string;
+    sourceBranch: string;
+    targetBranch: string;
+    webUrl?: string;
+    raw: unknown;
+};
+/** A project/repo-level CI variable, normalized across VCS platforms. */
+export type VcsProjectVariable = {
+    key: string;
+    value: string;
+    raw: unknown;
+};
+/**
+ * What a platform calls a proposed change, for user-facing log and message text. GitLab says
+ * "merge request"/"MR"; GitHub says "pull request"/"PR".
+ */
+export type VcsTerminology = {
+    changeRequest: string;
+    changeRequestShort: string;
+    /** What the platform calls the repo-scoped CI variables read by `getProjectVariables`. */
+    projectVariable: string;
+};
+/** The upstream repository identity, as read from the platform's own CI environment variables. */
+export type VcsCiContext = {
+    projectPath?: string;
+    projectId?: string;
+};
+/** Everything a provider needs to talk to a specific instance of its platform. */
+export type VcsProviderOptions = {
+    /** The instance hostname, e.g. `gitlab.com` or `github.com`. */
+    host?: string;
+    token: string;
+    /** Overrides the provider's derived API base URL. Rarely needed outside self-hosted instances. */
+    apiUrl?: string;
+    /**
+     * What kind of token `token` is, so the provider can pick the right auth header. Only GitLab
+     * distinguishes: a personal/project access token uses `PRIVATE-TOKEN`, a `CI_JOB_TOKEN` uses
+     * `JOB-TOKEN`. Defaults to `'personal'`. GitHub ignores this — a `GITHUB_TOKEN` and a PAT both
+     * authenticate the same way.
+     */
+    tokenKind?: 'personal' | 'job';
+};
+/**
+ * A source-control-hosting platform client, abstracted so that commands never encode one
+ * platform's API shape, URL scheme, or vocabulary.
+ */
+export interface VcsProvider {
+    readonly kind: VcsProviderKind;
+    /** The platform's vocabulary, for composing user-facing text. */
+    readonly terminology: VcsTerminology;
+    /** The instance hostname this provider was built for. */
+    readonly host: string;
+    /** The API base URL this provider talks to, derived from the host unless overridden. */
+    readonly apiUrl: string;
+    /** Reads the upstream repository's identity from this platform's CI environment variables. */
+    getCiContext(): VcsCiContext;
+    /** Lists all projects/repos under a group/org, including subgroups where the platform has them. */
+    listProjects(groupId: string | number): Promise<VcsProject[]>;
+    /** Fetches the raw content of a file from a project at a given ref. */
+    getFileContent(project: VcsProjectRef, filePath: string, ref: string): Promise<string>;
+    /** Lists the commits reachable from `to` but not from `from` (e.g. between two tags/SHAs). */
+    compareRefs(project: VcsProjectRef, from: string, to: string): Promise<VcsCommitLogEntry[]>;
+    /** Returns whether a branch exists in a project. */
+    branchExists(project: VcsProjectRef, branchName: string): Promise<boolean>;
+    /** Creates a branch from a reference point (usually the project's default branch). */
+    createBranch(project: VcsProjectRef, branchName: string, ref: string): Promise<VcsBranch>;
+    /** Commits new content for a single file to a branch. */
+    commitFile(project: VcsProjectRef, branchName: string, commitMessage: string, filePath: string, content: string): Promise<VcsCommit>;
+    /** Finds an existing open merge/pull request with the given source and target branch, if any. */
+    findOpenMergeRequest(project: VcsProjectRef, sourceBranch: string, targetBranch: string): Promise<VcsMergeRequest | undefined>;
+    /** Creates a new merge/pull request. */
+    createMergeRequest(project: VcsProjectRef, sourceBranch: string, targetBranch: string, title: string, description: string, labels?: string[]): Promise<VcsMergeRequest>;
+    /** Updates an existing merge/pull request's title, description, and labels. */
+    updateMergeRequest(project: VcsProjectRef, mergeRequest: VcsMergeRequest, title: string, description: string, labels?: string[]): Promise<VcsMergeRequest>;
+    /** Fetches project/repo-level CI variables. Returns an empty array if unreadable. */
+    getProjectVariables(project: VcsProjectRef): Promise<VcsProjectVariable[]>;
+    /**
+     * Builds the browser URL for a merge/pull request, given the project's own web URL. The path
+     * differs per platform — GitLab nests it under `/-/merge_requests/`, GitHub under `/pull/`.
+     */
+    buildChangeRequestUrl(projectUrl: string, changeRequestIid: string | number): string;
+    /** Builds a token-authenticated remote URL suitable for push/tag operations (e.g. `git remote add`). */
+    buildAuthenticatedRemoteUrl(token: string, projectPath: string): string;
+    /** Builds a CI-job-token-authenticated remote URL suitable for a read-only `git clone`. */
+    buildCiCloneUrl(ciJobToken: string, projectPath: string): string;
+}
+/** Constructs a provider for one instance of a platform. */
+export type VcsProviderFactory = (options: VcsProviderOptions) => VcsProvider;

package/lib/vcs/types.js

@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed 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 CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/vcs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/vcs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@simplysf/simply-cicd-core",
+  "description": "ALM issue linking (Jira, GitLab Issues) and VCS API clients (GitHub, GitLab) — the library layer behind @simplysf/simply-cicd, published separately for direct consumption (e.g. a bot or script) without the CLI framework",
+  "version": "0.2.0",
+  "author": "@ClayChipps",
+  "homepage": "https://github.com/SimplySF/simply-node",
+  "bugs": "https://github.com/SimplySF/simply-node/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SimplySF/simply-node",
+    "directory": "packages/simply-cicd-core"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "/lib"
+  ],
+  "keywords": [
+    "force",
+    "salesforce",
+    "sfdx",
+    "salesforcedx",
+    "sfdx-plugin",
+    "sf-plugin",
+    "sf",
+    "cicd"
+  ],
+  "license": "Apache-2.0",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "type": "module",
+  "dependencies": {},
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.10",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "wireit": {
+    "build": {
+      "dependencies": [
+        "compile",
+        "lint"
+      ]
+    },
+    "compile": {
+      "command": "tsc -p . --pretty --incremental",
+      "files": [
+        "src/**/*.ts",
+        "**/tsconfig.json",
+        "../../tsconfig.json"
+      ],
+      "output": [
+        "lib/**",
+        "*.tsbuildinfo"
+      ],
+      "clean": "if-file-deleted"
+    },
+    "format": {
+      "command": "prettier --write \"+(src|test)/**/*.+(ts|js|json)\"",
+      "files": [
+        "src/**/*.ts",
+        "test/**/*.ts",
+        ".prettier*"
+      ],
+      "output": []
+    },
+    "lint": {
+      "command": "eslint src test --color --cache --cache-location .eslintcache",
+      "files": [
+        "src/**/*.ts",
+        "test/**/*.ts",
+        "**/.eslint*",
+        "**/tsconfig.json",
+        "../../eslint.config.mjs",
+        "../../tsconfig.json"
+      ],
+      "output": []
+    },
+    "test": {
+      "dependencies": [
+        "test:compile",
+        "test:only",
+        "lint"
+      ]
+    },
+    "test:compile": {
+      "command": "tsc -p \"./test\" --pretty",
+      "files": [
+        "test/**/*.ts",
+        "**/tsconfig.json",
+        "../../tsconfig.json"
+      ],
+      "output": []
+    },
+    "test:only": {
+      "command": "vitest run --project simply-cicd-core",
+      "env": {
+        "FORCE_COLOR": "2"
+      },
+      "files": [
+        "test/**/*.ts",
+        "src/**/*.ts",
+        "**/tsconfig.json",
+        "../../tsconfig.json",
+        "vitest.config.ts"
+      ],
+      "output": []
+    }
+  },
+  "scripts": {
+    "build": "wireit",
+    "compile": "wireit",
+    "fix-license": "eslint src test --fix --rule \"header/header: [2]\"",
+    "format": "wireit",
+    "lint": "wireit",
+    "test": "wireit",
+    "test:coverage": "vitest run --coverage --project simply-cicd-core",
+    "test:only": "wireit",
+    "test:watch": "vitest watch --project simply-cicd-core"
+  }
+}