@getexception/cli 0.1.7 → 0.1.8

package/README.md

@@ -16,11 +16,13 @@ yarn getexception sourcemaps upload --dir .getexception-maps --url https://sentr
 
 The Owner creates **Source map upload tokens** in the project's settings. Store the token in the CI secret `GETEXCEPTION_UPLOAD_TOKEN`. It expires after 90 days and can be revoked. Never pass it as a command-line argument or include it in the browser environment, repository, logs or public artifacts. Only trusted build jobs may read this secret.
 
+For GitLab MR previews use short-lived `GETEXCEPTION_GITLAB_ID_TOKEN` instead, after the operator has configured the pinned GitLab trust policy. Run `getexception ci context --url <HTTPS dashboard origin> --project <UUID>` before building; use the returned release, deployment and asset prefix for the actual JavaScript output. Upload and release registration use that identity automatically. Never set both credential variables. See the [GitLab integration guide](../../docs/gitlab-ci.md) for server configuration, exact build isolation and production restrictions. Version 0.1.7 does not support this flow.
+
 `prepare` modifies the **final ESM JavaScript**: it adds a Debug ID, shifts mappings by one line, removes sourceMappingURL comments and moves `.js.map` / `.mjs.map` files out of the public build. The private output directory must not exist and must be outside `dist`. Run this once per fresh build, before compression, SRI signing or deployment. Legacy IIFE/CommonJS bundles are unsupported. If assets are served below an additional base path, pass `--url-prefix <base-path>`; paths must match deployed JavaScript URLs.
 
-Deploy the resulting `dist` unchanged. Upload failure does not undo preparation: keep `.getexception-maps` as a **private, access-controlled CI artifact** and retry `upload` with that same directory. Do not run `prepare` twice or rebuild only the maps. Never publish the private artifact directory alongside the application. Other map formats (for example CSS maps) should also be excluded from the public deploy artifact by your build configuration.
+Deploy the resulting `dist` unchanged. Upload failure does not undo preparation: retry within the same job using the same prepared directory. **Do not save source maps as GitLab artifacts or cache when access has not been verified.** The GitLab identity flow keeps them only in the isolated job workspace and uploads directly to GetException. A retry after that job ends requires a new build with a new job prefix; it cannot replace maps for the old build. Do not run `prepare` twice or rebuild only the maps. Never publish the private artifact directory alongside the application. Other map formats (for example CSS maps) should also be excluded from the public deploy artifact by your build configuration.
 
-`upload` sends an authenticated manifest, uploads files with checksums, then waits for background validation. It supports retries and resuming the same manifest, has a two-minute deadline, and exits nonzero on failure. CI may allow this job to fail for an urgent application release while retaining its private artifact for retry. Raw maps have no download endpoint.
+`upload` sends an authenticated manifest, uploads files with checksums, then waits for background validation. It supports retries and resuming the same manifest, has a two-minute deadline, and exits nonzero on failure. CI may allow an urgent production deployment without maps with an explicit warning. MR previews require all batches to be ready before deploying. Do not retain maps in GitLab artifacts as a fallback. Raw maps have no download endpoint.
 
 Limits: 128 JS files and 128 MiB per upload, 16 MiB per map, 1 GiB per project, 10 GiB per installation. Non-indexed Source Map v3 JSON only; no archives, compression or remote source downloads. Existing events are processed after a late upload. Errors thrown in the browser console have no source file and cannot gain a source snippet from a map.
 

package/dist/index.js

@@ -18985,6 +18985,13 @@ var releaseRegistrationSchema = external_exports.object({
   deployment: deploymentSchema
 }).strict();
 
+// packages/protocol/src/ci.ts
+var buildContextSchema = external_exports.object({
+  release: releaseNameSchema,
+  assetPrefix: external_exports.string().regex(/^assets\/ge-gl-[1-9][0-9]*-[1-9][0-9]*\/$/),
+  deployment: deploymentSchema
+}).strict();
+
 // packages/protocol/src/index.ts
 var safeFrameSchema = external_exports.object({
   filename: external_exports.string().max(512),
@@ -19163,25 +19170,54 @@ import { setTimeout as delay2 } from "timers/promises";
 
 // packages/cli/src/api.ts
 import { setTimeout as delay } from "timers/promises";
+
+// packages/cli/src/credentials.ts
+function ciCredential(env = process.env) {
+  if (env.GETEXCEPTION_GITLAB_ID_TOKEN && env.GETEXCEPTION_UPLOAD_TOKEN) {
+    throw new Error("Choose one CI authentication method");
+  }
+  return env.GETEXCEPTION_GITLAB_ID_TOKEN ? { gitlabIdToken: env.GETEXCEPTION_GITLAB_ID_TOKEN } : env.GETEXCEPTION_UPLOAD_TOKEN ?? "";
+}
+function authorizationHeader(credential) {
+  if (typeof credential === "string") {
+    if (!/^[a-f0-9]{64}$/.test(credential)) {
+      throw new Error(
+        "Set GETEXCEPTION_UPLOAD_TOKEN or GETEXCEPTION_GITLAB_ID_TOKEN"
+      );
+    }
+    return `Bearer ${credential}`;
+  }
+  if (credential.gitlabIdToken.length > 16384 || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(
+    credential.gitlabIdToken
+  )) {
+    throw new Error("Invalid GitLab build identity");
+  }
+  return `GitLab ${credential.gitlabIdToken}`;
+}
+
+// packages/cli/src/api.ts
 function projectApi(address, project, token, transport = fetch) {
   const url2 = new URL(address);
   if (url2.protocol !== "https:" || url2.username || url2.password || url2.search || url2.hash || url2.pathname !== "/") {
     throw new Error("Use the HTTPS dashboard origin");
   }
-  if (!external_exports.string().uuid().safeParse(project).success || !/^[a-f0-9]{64}$/.test(token)) {
-    throw new Error("Set a valid project ID and GETEXCEPTION_UPLOAD_TOKEN");
+  if (!external_exports.string().uuid().safeParse(project).success) {
+    throw new Error("Set a valid project ID");
   }
+  const authorization = authorizationHeader(token);
   const base = `${url2.origin}/api/v1/projects/${project}`;
   const deadline = Date.now() + 12e4;
   return async function request(path, method = "GET", body) {
     for (let attempt = 0; attempt < 3; attempt++) {
       if (Date.now() >= deadline) {
-        throw new Error("Upload timed out; retain private artifacts and retry");
+        throw new Error(
+          "Upload timed out; retry within the job or run a new build"
+        );
       }
       const response = await transport(base + path, {
         method,
         headers: {
-          Authorization: `Bearer ${token}`,
+          Authorization: authorization,
           "Content-Type": "application/json"
         },
         body,
@@ -19266,6 +19302,13 @@ async function registerRelease(address, project, token, value, transport = fetch
   )("/releases", "POST", JSON.stringify(input2));
 }
 
+// packages/cli/src/ci.ts
+async function buildContext(address, project, credential, transport = fetch) {
+  return buildContextSchema.parse(
+    await projectApi(address, project, credential, transport)("/ci", "POST")
+  );
+}
+
 // packages/cli/src/index.ts
 async function main() {
   const { values, positionals } = parseArgs({
@@ -19285,30 +19328,33 @@ async function main() {
   });
   if (values.help) {
     process.stdout.write(
-      "getexception sourcemaps prepare --dir dist --output ../private-maps --release app@<40-character-SHA> [--url-prefix assets]\ngetexception sourcemaps upload --dir ../private-maps --url https://dashboard.example --project <UUID>\ngetexception releases register --url https://dashboard.example --project <UUID> --release app@<40-character-SHA> --environment <production|staging|development> [--repository-id <GitLab project ID> --merge-request <IID>]\nToken: GETEXCEPTION_UPLOAD_TOKEN environment variable. Prepare modifies ESM JavaScript and removes public .js.map files.\n"
+      "getexception sourcemaps prepare --dir dist --output ../private-maps --release app@<40-character-SHA> [--url-prefix assets]\ngetexception sourcemaps upload --dir ../private-maps --url https://dashboard.example --project <UUID>\ngetexception releases register --url https://dashboard.example --project <UUID> --release app@<40-character-SHA> --environment <production|staging|development> [--repository-id <GitLab project ID> --merge-request <IID>]\ngetexception ci context --url https://dashboard.example --project <UUID>\nAuthentication: GETEXCEPTION_UPLOAD_TOKEN or GETEXCEPTION_GITLAB_ID_TOKEN, never both. Prepare modifies ESM JavaScript and removes public .js.map files.\n"
+    );
+    return;
+  }
+  if (positionals.length === 2 && positionals[0] === "ci" && positionals[1] === "context" && values.url && values.project) {
+    process.stdout.write(
+      JSON.stringify(
+        await buildContext(values.url, values.project, ciCredential())
+      ) + "\n"
     );
     return;
   }
   if (positionals.length === 2 && positionals[0] === "releases" && positionals[1] === "register" && values.url && values.project) {
     const hasReview = values["repository-id"] !== void 0 || values["merge-request"] !== void 0;
-    await registerRelease(
-      values.url,
-      values.project,
-      process.env.GETEXCEPTION_UPLOAD_TOKEN ?? "",
-      {
-        release: values.release,
-        deployment: {
-          environment: values.environment,
-          ...hasReview ? {
-            review: {
-              provider: "gitlab",
-              repositoryId: Number(values["repository-id"]),
-              number: Number(values["merge-request"])
-            }
-          } : {}
-        }
+    await registerRelease(values.url, values.project, ciCredential(), {
+      release: values.release,
+      deployment: {
+        environment: values.environment,
+        ...hasReview ? {
+          review: {
+            provider: "gitlab",
+            repositoryId: Number(values["repository-id"]),
+            number: Number(values["merge-request"])
+          }
+        } : {}
       }
-    );
+    });
     process.stdout.write("Release environment registered.\n");
     return;
   }
@@ -19327,12 +19373,7 @@ async function main() {
 `
     );
   } else if (positionals[1] === "upload" && values.url && values.project) {
-    await uploadMaps(
-      values.dir,
-      values.url,
-      values.project,
-      process.env.GETEXCEPTION_UPLOAD_TOKEN ?? ""
-    );
+    await uploadMaps(values.dir, values.url, values.project, ciCredential());
     process.stdout.write("Source maps validated and ready.\n");
   } else {
     throw new Error("Invalid command");
@@ -19340,7 +19381,7 @@ async function main() {
 }
 void main().catch(() => {
   process.stderr.write(
-    "Command failed. Check options (--help), CI token, limits and private artifacts; retry upload without rebuilding.\n"
+    "Command failed. Check options (--help), CI authentication, limits and build scope. Never publish maps as CI artifacts.\n"
   );
   process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getexception/cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Private source map uploads for GetException",
   "type": "module",
   "license": "MIT",