react-native-cache-build-gitlab 1.0.5 → 1.0.7

package/README.md

@@ -4,10 +4,13 @@ GitLab Generic Package provider for [RockJS](https://rockjs.dev) with single pac
 
 ## Features
 
-✅ **Single Package Storage**: All native builds (iOS & Android) stored in one package  
-✅ **Fingerprint-based Lookup**: Fast artifact retrieval by filename matching  
-✅ **CI/CD Ready**: Works seamlessly with GitLab CI  
-✅ **Cost Effective**: Reduces package registry clutter
+📦 **Single Package Storage**: Stores all native builds (iOS & Android) in a single GitLab Generic Package.
+
+🧾 **Fingerprint-based Lookup**: Fast artifact retrieval by filename matching.
+
+🤖️ **CI/CD Ready**: Works seamlessly with GitLab CI.
+
+🪙 **Cost Effective**: Reduces package registry clutter by grouping artifacts.
 
 ## Installation
 
@@ -17,56 +20,100 @@ npm install react-native-cache-build-gitlab
 yarn add react-native-cache-build-gitlab
 ```
 
+## ⚠️ Prerequisites & Configuration
+
+**Important:** You must configure your project according to the [RockJS documentation](https://www.rockjs.dev/docs/cli/migrating-from-community-cli).
+
+Before using this provider, you need to set up authentication. This provider uses `CI_JOB_TOKEN` as the default environment variable for authentication.
+
+### **1. Create a Personal Access Token**
+
+- Go to **GitLab** → **Edit profile** → **Personal access tokens**.
+- Click **Add new token**.
+- Give the token a name and expiration date (recommended).
+- Select scopes you need (commonly: `read_api`, `read_repository`, `write_repository`).
+- Create the token and copy it now — GitLab shows it only once.
+
+![img.png](assets/example_PAT.png)
+
+### **2. Expose the token as an environment variable**
+
+The provider expects the token in the `CI_JOB_TOKEN` environment variable
+
+#### Temporary (Current Shell)
+
+```bash
+export CI_JOB_TOKEN=glt-abc123...
+```
+
+#### Permanent (macOS/Linux - Zsh):
+
+```bash
+echo 'export CI_JOB_TOKEN=glt-abc123...' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Note:** In GitLab CI pipelines, `CI_JOB_TOKEN` is automatically injected, so you don't need to configure it manually there.
+
 ## Usage
 
 In your `rock.config.mjs`:
 
 ```ts
-import {platformIOS} from "@rock-js/platform-ios";
-import {platformAndroid} from "@rock-js/platform-android";
-import {providerGitLab} from "react-native-cache-build-gitlab";
-import {pluginMetro} from "@rock-js/plugin-metro";
+import { platformIOS } from "@rock-js/platform-ios";
+import { platformAndroid } from "@rock-js/platform-android";
+import { providerGitLab } from "react-native-cache-build-gitlab";
+import { pluginMetro } from "@rock-js/plugin-metro";
 
 export default {
-    bundler: pluginMetro(),
-    platforms: {
-        ios: platformIOS(),
-        android: platformAndroid(),
-    },
-    remoteCacheProvider: providerGitLab({
-        packageName: "mobile-artifacts",
-        baseUrl: "https://gitlab.example.com",
-        projectId: 1234,
-        token: process.env.CI_JOB_TOKEN,
-        tokenHeader: process.env.CI ? "JOB-TOKEN" : "PRIVATE-TOKEN",
-    }),
-    fingerprint: {
-        ignorePaths: [
-            "ios/Podfile.lock",
-            "ios/**/xcuserdata",
-            "ios/**/project.pbxproj",
-            // Add more paths to ignore as needed
-        ],
-    },
+  bundler: pluginMetro(),
+  platforms: {
+    ios: platformIOS(),
+    android: platformAndroid(),
+  },
+  remoteCacheProvider: providerGitLab({
+    packageName: "mobile-artifacts",
+    registryServer: "https://your-gitlab-instance.com",
+    projectId: 1234,
+    /*
+     * token: process.env.CI_JOB_TOKEN (default)
+     * tokenHeader: process.env.CI ? "JOB-TOKEN" : "PRIVATE-TOKEN" (default)
+     * */
+  }),
+  fingerprint: {
+    ignorePaths: [
+      "ios/Podfile.lock",
+      "ios/**/xcuserdata",
+      "ios/**/project.pbxproj",
+      // Add more paths to ignore as needed
+    ],
+  },
 };
 ```
 
 ## Configuration
 
-| Option        | Type                             | Description                                                                                     |
-| ------------- | -------------------------------- |-------------------------------------------------------------------------------------------------|
-| `packageName` | `string`                         | Package name in GitLab Generic Package Registry                                                 |
-| `baseUrl`     | `string`                         | GitLab instance URL                                                                             |
-| `projectId`   | `number`                         | GitLab project ID                                                                               |
-| `token`       | `string`                         | GitLab personal access token (`CI_JOB_TOKEN` on CI), You have to export `CI_JOB_TOKEN` in local |
-|               |                                  |                                                                                                 |
-| `tokenHeader` | `"JOB-TOKEN" \| "PRIVATE-TOKEN"` | Token type                                                                                      |
+| Option           | Type     | Description                                                                                |
+| ---------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `packageName`    | `string` | Package name in GitLab Generic Package Registry                                            |
+| `registryServer` | `string` | GitLab instance URL                                                                        |
+| `projectId`      | `number` | GitLab project ID                                                                          |
+| `token`          | `string` | (Optional) Auth token. Defaults to `process.env.CI_JOB_TOKEN`                              |
+| `tokenHeader`    | `string` | (Optional) Auth token header. Defaults to `process.env.CI ? "JOB-TOKEN" : "PRIVATE-TOKEN"` |
 
 ## How It Works
 
 ### Upload (CI)
 
-All builds are uploaded to a **single package** with version `1.0.0` (Can change version if needed) at *Package Registry*.:
+When your CI pipeline runs, you can use a script to upload the build artifacts to the GitLab Package Registry. (See the `example` folder in the repository for the `upload-cache-remote.sh` script).
+
+![img.png](assets/ci.png)
+
+### Registry Structure
+
+All builds are uploaded to a single package version (e.g., 1.0.0).
+
+![img.png](assets/registry.png)
 
 ```
 mobile-artifacts@1.0.0/
@@ -75,13 +122,19 @@ mobile-artifacts@1.0.0/
   └── ...
 ```
 
-### Download (Local/CI)
+### Download (Local)
 
-When running:
+When you run `bun rock:run-ios` or `bun rock:run-android`:
 
-1. Calculate project fingerprint
-2. Search for file containing the fingerprint
-3. Download and extract
+1. Rock calculates the **project fingerprint**.
+2. The provider searches the GitLab Package for a file containing that fingerprint.
+3. If found, it downloads and extracts the artifact automatically.
+
+> Android:
+> ![img.png](assets/run-android.png)
+
+> iOS:
+> ![img.png](assets/run-ios.png)
 
 ## GitLab CI Example
 
@@ -89,16 +142,33 @@ When running:
 build_android_cache:
   stage: build
   script:
-    - bun run build:android --variant=devDebug
-    - CACHE_DIR="$(ls -1dt .rock/cache/remote-build/rock-android-* | head -n1)"
-    - sh scripts/upload-cache-remote.sh "${CACHE_DIR}" rock-android-devDebug-{FP}.zip android
-```
+    - |
+      bun run rock:build-android 
+
+      CACHE_DIR="$(ls -1dt .rock/cache/remote-build/${NAME_PREFIX}-* | head -n1 || true)"
 
-## Differences from Official Provider
+      if [[ -z "${CACHE_DIR}" || ! -d "${CACHE_DIR}" ]]; then
+        echo "No cache output under .rock/cache/remote-build/${NAME_PREFIX}-*"
+        exit 1
+      fi
+      echo "CACHE_DIR=${CACHE_DIR}"
 
-The official `@rock-js/provider-gitlab` creates **one package per fingerprint**, which can clutter the package registry.
+      FP="${CACHE_DIR##*-}"
+      echo "Fingerprint: ${FP}"
+
+      if ! compgen -G "${CACHE_DIR}"/*.apk > /dev/null; then
+        echo "No .apk found in ${CACHE_DIR}"
+        ls -la "${CACHE_DIR}" || true
+        exit 1
+      fi
+
+      FILE_UPLOAD_NAME="${NAME_PREFIX}-${FP}.zip"
+      echo "FILE_UPLOAD_NAME=${FILE_UPLOAD_NAME}"
+
+      sh scripts/upload-cache-remote.sh "${CACHE_DIR}" "${FILE_UPLOAD_NAME}" android
+```
 
-This provider stores **all builds in one package** (version `1.0.4`), using filename-based lookup instead of version-based lookup.
+> **_You can refer to the CI gitlab config in folder example_**
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-cache-build-gitlab",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "main": "dist/index.js",
   "type": "module",
   "types": "dist/index.d.ts",

package/dist/index.d.ts

@@ -1 +0,0 @@
-export { providerGitLab } from "./provider-gitlab/providerGitlab.js";

package/dist/index.js

@@ -1 +0,0 @@
-export { providerGitLab } from "./provider-gitlab/providerGitlab.js";

package/dist/provider-gitlab/artifacts.d.ts

@@ -1,19 +0,0 @@
-import { type RemoteArtifact } from "@rock-js/tools";
-export type GitLabRepoDetails = {
-    baseUrl: string;
-    projectId: number | string;
-    token: string;
-    tokenHeader: "PRIVATE-TOKEN" | "JOB-TOKEN";
-    packageName: string;
-};
-export type GitLabArtifact = {
-    packageId: number;
-    fileId: number;
-    name: string;
-    version: string;
-    sizeInBytes: number;
-    createdAt: string;
-    downloadUrl: string;
-};
-export declare function fetchGitLabArtifactsByName(name: string | undefined, repo: GitLabRepoDetails, limit?: number, version?: string): Promise<GitLabArtifact[]>;
-export declare function deleteGitLabArtifacts(artifacts: GitLabArtifact[], repo: GitLabRepoDetails, artifactNameForLog?: string): Promise<RemoteArtifact[]>;

package/dist/provider-gitlab/artifacts.js

@@ -1,106 +0,0 @@
-import { cacheManager, color, colorLink, logger, RockError, } from "@rock-js/tools";
-const PAGE_SIZE = 100;
-function headersFor(repo) {
-    return {
-        [repo.tokenHeader]: repo.token,
-        Accept: "application/json",
-    };
-}
-async function httpJson(url, repo) {
-    const res = await fetch(url, { headers: headersFor(repo) });
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        const info = `${res.status} ${res.statusText}${body ? ` — ${body}` : ""}`;
-        if (res.status === 401 || res.status === 403) {
-            cacheManager.remove("gitlabToken");
-            throw new RockError(`GitLab auth failed.\nUpdate token under ${color.bold("remoteCacheProvider")} in ${colorLink("rock.config.mjs")}. Local uses ${color.bold("PRIVATE-TOKEN")}, CI uses ${color.bold("JOB-TOKEN")}.\nURL: ${colorLink(url)}\nError: ${info}`);
-        }
-        if (res.status === 404) {
-            throw new RockError(`GitLab 404.\nCheck baseUrl/projectId/packageName or token perms.\nURL: ${colorLink(url)}`);
-        }
-        throw new RockError(`GitLab request failed: ${info}`);
-    }
-    return (await res.json());
-}
-function genericDownloadUrl(repo, packageName, version, fileName) {
-    const { baseUrl, projectId } = repo;
-    return `${baseUrl}/api/v4/projects/${encodeURIComponent(String(projectId))}/packages/generic/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}/${encodeURIComponent(fileName)}`;
-}
-export async function fetchGitLabArtifactsByName(name, repo, limit, version) {
-    if (!repo?.token) {
-        throw new RockError("Missing GitLab token. Valid repoDetails.token & tokenHeader pass.");
-    }
-    const perPage = Math.min(limit ?? PAGE_SIZE, PAGE_SIZE);
-    let page = 1;
-    const packages = [];
-    while (true) {
-        const url = `${repo.baseUrl}/api/v4/projects/${encodeURIComponent(String(repo.projectId))}/packages` +
-            `?package_type=generic&per_page=${perPage}&page=${page}` +
-            (name ? `&package_name=${encodeURIComponent(name)}` : "");
-        const chunk = await httpJson(url, repo);
-        if (!chunk.length)
-            break;
-        packages.push(...chunk);
-        if (chunk.length < perPage)
-            break;
-        page += 1;
-    }
-    const artifacts = [];
-    for (const pkg of packages) {
-        if (pkg.package_type !== "generic" || !pkg.version)
-            continue;
-        // Don't filter by version here - we'll filter by filename later
-        let fPage = 1;
-        while (true) {
-            const filesUrl = `${repo.baseUrl}/api/v4/projects/${encodeURIComponent(String(repo.projectId))}` +
-                `/packages/${pkg.id}/package_files?per_page=${PAGE_SIZE}&page=${fPage}`;
-            const files = await httpJson(filesUrl, repo);
-            if (!files.length)
-                break;
-            for (const file of files) {
-                // If version (fingerprint) is provided, filter by filename containing it
-                if (version && !file.file_name.includes(version))
-                    continue;
-                artifacts.push({
-                    packageId: pkg.id,
-                    fileId: file.id,
-                    name: pkg.name,
-                    version: pkg.version,
-                    sizeInBytes: file.size,
-                    createdAt: file.created_at,
-                    downloadUrl: genericDownloadUrl(repo, pkg.name, pkg.version, file.file_name),
-                });
-            }
-            if (files.length < PAGE_SIZE)
-                break;
-            fPage += 1;
-        }
-    }
-    artifacts.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
-    return artifacts;
-}
-export async function deleteGitLabArtifacts(artifacts, repo, artifactNameForLog) {
-    const deleted = [];
-    try {
-        for (const artifact of artifacts) {
-            const url = `${repo.baseUrl}/api/v4/projects/${encodeURIComponent(String(repo.projectId))}/packages/${artifact.packageId}/package_files/${artifact.fileId}`;
-            const res = await fetch(url, {
-                method: "DELETE",
-                headers: headersFor(repo),
-            });
-            if (!res.ok) {
-                logger.warn(`Delete failed packageId=${artifact.packageId}, fileId=${artifact.fileId}: ${res.status} ${res.statusText}`);
-                continue;
-            }
-            deleted.push({
-                name: `${artifact.name}@${artifact.version}`,
-                url: artifact.downloadUrl,
-                id: String(artifact.fileId),
-            });
-        }
-        return deleted;
-    }
-    catch (error) {
-        throw new RockError(`Failed to delete GitLab artifacts${artifactNameForLog ? ` for "${artifactNameForLog}"` : ""}`, { cause: error });
-    }
-}

package/dist/provider-gitlab/config.d.ts

@@ -1,8 +0,0 @@
-import { GitLabRepoDetails } from "./artifacts";
-export type DetectGitLabRepoInput = Partial<GitLabRepoDetails> & {
-    baseUrl?: string;
-    projectId?: number | string;
-    token?: string;
-    tokenHeader?: "JOB-TOKEN" | "PRIVATE-TOKEN";
-};
-export declare function detectGitLabRepoDetails(override?: DetectGitLabRepoInput): Promise<GitLabRepoDetails>;

package/dist/provider-gitlab/config.js

@@ -1,21 +0,0 @@
-import { RockError } from "@rock-js/tools";
-export async function detectGitLabRepoDetails(override) {
-    const baseUrl = override?.baseUrl;
-    const projectId = override?.projectId;
-    const token = override?.token;
-    const tokenHeader = override?.tokenHeader;
-    const packageName = override?.packageName;
-    if (!projectId) {
-        throw new RockError("Missing GitLab projectId. Set GITLAB_PROJECT_ID or pass in override.");
-    }
-    if (!token) {
-        throw new RockError("Missing GitLab token. Use CI_JOB_TOKEN or GITLAB_TOKEN.");
-    }
-    return {
-        baseUrl,
-        projectId,
-        token,
-        tokenHeader,
-        packageName,
-    };
-}

package/dist/provider-gitlab/providerGitlab.d.ts

@@ -1,36 +0,0 @@
-import type { RemoteArtifact, RemoteBuildCache } from "@rock-js/tools";
-import { type GitLabRepoDetails } from "./artifacts.js";
-export declare class GitLabBuildCache implements RemoteBuildCache {
-    name: string;
-    repoDetails: GitLabRepoDetails | null;
-    constructor(config?: {
-        baseUrl: string;
-        projectId: number | string;
-        token?: string;
-        tokenHeader?: "JOB-TOKEN" | "PRIVATE-TOKEN";
-        packageName: string;
-    });
-    getRepoDetails(): Promise<GitLabRepoDetails>;
-    list({ artifactName, limit, }: {
-        artifactName?: string;
-        limit?: number;
-    }): Promise<RemoteArtifact[]>;
-    download({ artifactName, }: {
-        artifactName: string;
-    }): Promise<Response>;
-    delete({ artifactName, limit, skipLatest, }: {
-        artifactName: string;
-        limit?: number;
-        skipLatest?: boolean;
-    }): Promise<RemoteArtifact[]>;
-    upload(): Promise<RemoteArtifact & {
-        getResponse: (buffer: Buffer | ((baseUrl: string) => Buffer), contentType?: string | undefined) => Response;
-    }>;
-}
-export declare const providerGitLab: (options?: {
-    baseUrl: string;
-    projectId: number;
-    token?: string;
-    tokenHeader?: "PRIVATE-TOKEN" | "JOB-TOKEN";
-    packageName: string;
-}) => () => RemoteBuildCache;

package/dist/provider-gitlab/providerGitlab.js

@@ -1,78 +0,0 @@
-import { deleteGitLabArtifacts, fetchGitLabArtifactsByName, } from "./artifacts.js";
-import { detectGitLabRepoDetails } from "./config.js";
-function parseRockArtifact(artifactName) {
-    if (!artifactName)
-        return {};
-    const maybe = artifactName.split("-").pop();
-    if (/^[a-f0-9]{40}$/.test(maybe))
-        return { fingerprint: maybe };
-    return {};
-}
-export class GitLabBuildCache {
-    name = "GitLab";
-    repoDetails = null;
-    constructor(config) {
-        if (config) {
-            const token = config.token ?? process.env.CI_JOB_TOKEN;
-            const tokenHeader = config.tokenHeader ?? (process.env.CI ? "JOB-TOKEN" : "PRIVATE-TOKEN");
-            if (!token) {
-                throw new Error("GitLab token is required. Set CI_JOB_TOKEN (CI) or GITLAB_PRIVATE_TOKEN/PRIVATE_TOKEN (local).");
-            }
-            this.repoDetails = {
-                packageName: config.packageName,
-                baseUrl: config.baseUrl,
-                projectId: config.projectId,
-                token,
-                tokenHeader,
-            };
-        }
-    }
-    async getRepoDetails() {
-        if (!this.repoDetails) {
-            this.repoDetails = await detectGitLabRepoDetails();
-        }
-        return this.repoDetails;
-    }
-    async list({ artifactName, limit, }) {
-        const repo = await this.getRepoDetails();
-        const { fingerprint } = parseRockArtifact(artifactName);
-        const artifacts = await fetchGitLabArtifactsByName(repo.packageName, repo, limit, fingerprint);
-        return artifacts.map((artifact) => ({
-            name: `${artifact.name}@${artifact.version}`,
-            url: artifact.downloadUrl,
-            id: `${artifact.packageId}:${artifact.fileId}`,
-        }));
-    }
-    async download({ artifactName, }) {
-        const repo = await this.getRepoDetails();
-        const { fingerprint } = parseRockArtifact(artifactName);
-        if (!fingerprint)
-            throw new Error("artifactName is required");
-        const list = await fetchGitLabArtifactsByName(repo.packageName, repo, 1, fingerprint);
-        if (list.length === 0) {
-            throw new Error(`No GitLab artifact found for "${artifactName}"${fingerprint ? ` (version=${fingerprint})` : ""}`);
-        }
-        const url = list[0].downloadUrl;
-        return fetch(url, {
-            headers: {
-                [repo.tokenHeader]: repo.token,
-                "Accept-Encoding": "identity",
-            },
-            redirect: "follow",
-        });
-    }
-    async delete({ artifactName, limit, skipLatest, }) {
-        const repo = await this.getRepoDetails();
-        const { fingerprint } = parseRockArtifact(artifactName);
-        const artifacts = await fetchGitLabArtifactsByName(repo.packageName, repo, limit, fingerprint);
-        if (artifacts.length === 0) {
-            throw new Error(`No GitLab artifact found for "${artifactName}"${fingerprint ? ` (version=${fingerprint})` : ""}`);
-        }
-        const list = skipLatest ? artifacts.slice(1) : artifacts;
-        return deleteGitLabArtifacts(list, repo, artifactName);
-    }
-    async upload() {
-        throw new Error("Uploading via RemoteBuildCache is not yet implemented.");
-    }
-}
-export const providerGitLab = (options) => () => new GitLabBuildCache(options);