@getexception/cli 0.1.7 → 0.1.9

package/README.md

@@ -16,11 +16,17 @@ 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.
+
+The current CI context contract is **version 2**; CLI 0.1.8 must be upgraded to use it. The Owner selects **Production only** or **Production and MR** under project settings and adds trusted fork project IDs/paths. No container restart is needed. A context includes `sourceMaps: {enabled: true}` or, for a trusted preview with maps disabled, `{enabled: false, reason: "preview_disabled"}`. An unlisted preview source receives only `{version: 2, sourceMaps: {enabled: false, reason: "source_not_allowed"}}` with no build context or release-registration permission. Skip responses mean build/deploy without maps, not disable SDK events. Invalid credentials, HTTP failures and unknown contracts remain errors. A trusted context can still register its release while maps are disabled. Production never receives a skip response.
+
+Permanent upload tokens cannot be created or used for projects with GitLab authentication configured. They remain available for other trusted CI integrations. Forks may upload only their own preview job's maps; the main repository remains the only production source. Actual map read access is never granted to CI.
+
 `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 with maps enabled 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.
 
@@ -31,9 +37,11 @@ MIT. See `THIRD-PARTY-NOTICES.md`.
 Register the environment after a successful deployment, with the same project token. This works independently of source-map upload:
 
 ```bash
-yarn getexception releases register --url https://sentry.frontend.sndsy.ru --project "$GETEXCEPTION_PROJECT_ID" --release "account@$CI_COMMIT_SHA" --environment staging --repository-id "$CI_MERGE_REQUEST_PROJECT_ID" --merge-request "$CI_MERGE_REQUEST_IID"
+yarn getexception releases register --url https://sentry.frontend.sndsy.ru --project "$GETEXCEPTION_PROJECT_ID" --release "account@$CI_COMMIT_SHA" --environment staging --repository-id "$CI_MERGE_REQUEST_TARGET_PROJECT_ID" --merge-request "$CI_MERGE_REQUEST_IID"
 ```
 
 Use the GitLab target repository's numeric project ID and the MR IID belonging to it. Standard merge-request pipelines provide these [predefined GitLab variables](https://docs.gitlab.com/ci/variables/predefined_variables/); custom preview pipelines must supply the actual pair explicitly. For production, use `--environment production` and omit both MR options. Repeated registration is safe. One SHA may have both production and staging contexts; this records release history, not current deployment status. Old events only establish an environment and cannot reveal an MR number.
 
+With GitLab build authentication, use the exact `release` and `deployment` returned by `ci context` instead of constructing registration metadata yourself. `CI_MERGE_REQUEST_PROJECT_ID` is not a substitute for the target project in a fork workflow.
+
 Debug IDs are deterministic for identical JS, maps and paths, regardless of the release SHA. The server reuses private bytes within the project and `upload` skips files it already has. Every release still sends its own manifest. Changed JavaScript requires its matching map: there is no fallback to the latest production map. Ready maps older than 30 days are eligible for cleanup only when their release has no retained events or pending inbox events. Shared files survive until all references expire.

package/dist/index.js

@@ -18985,6 +18985,33 @@ 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();
+var sourceMaps = external_exports.discriminatedUnion("enabled", [
+  external_exports.object({ enabled: external_exports.literal(true) }).strict(),
+  external_exports.object({
+    enabled: external_exports.literal(false),
+    reason: external_exports.literal("preview_disabled")
+  }).strict()
+]);
+var ciContextSchema = external_exports.union([
+  buildContextSchema.extend({ version: external_exports.literal(2), sourceMaps }).refine(
+    (context) => context.sourceMaps.enabled || context.deployment.environment === "staging",
+    "Only preview builds may skip source maps"
+  ),
+  external_exports.object({
+    version: external_exports.literal(2),
+    sourceMaps: external_exports.object({
+      enabled: external_exports.literal(false),
+      reason: external_exports.literal("source_not_allowed")
+    }).strict()
+  }).strict()
+]);
+
 // packages/protocol/src/index.ts
 var safeFrameSchema = external_exports.object({
   filename: external_exports.string().max(512),
@@ -19163,25 +19190,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 +19322,18 @@ 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 ciContextSchema.parse(
+    await projectApi(
+      address,
+      project,
+      credential,
+      transport
+    )("/ci?version=2", "POST")
+  );
+}
+
 // packages/cli/src/index.ts
 async function main() {
   const { values, positionals } = parseArgs({
@@ -19285,30 +19353,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 +19398,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 +19406,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.9",
   "description": "Private source map uploads for GetException",
   "type": "module",
   "license": "MIT",