@interfere/cli 0.0.2-canary.0 → 0.0.2-canary.1

package/README.md

@@ -1,23 +1,100 @@
 # @interfere/cli
 
-> **Status: canary.** Pre-1.0 surface, expect breaking changes. Pin to a specific `10.0.0-canary.N` in CI.
-
-Command-line tool for [Interfere](https://interfere.com) release workflows.
+Command-line tool for [Interfere](https://interfere.com) release workflows. Uploads source maps and registers releases so the collector accepts spans from your deployments.
 
 ## Install
 
 ```sh
+npm install -D @interfere/cli
+# or
 bun add -d @interfere/cli
+# or
+pnpm add -D @interfere/cli
 ```
 
 ## Usage
 
-After your build step, publish release metadata:
+Run after your build step to upload source maps and preflight the release:
 
 ```sh
-INTERFERE_API_KEY=interfere_ak_… bunx interfere sourcemaps upload ./dist
+interfere sourcemaps upload ./dist
+```
+
+Typically added as a `postbuild` script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "interfere sourcemaps upload ./dist"
+  }
+}
+```
+
+### What it does
+
+1. Derives a release slug from the commit SHA (same algorithm the SDK uses at runtime)
+2. Registers the release with the collector (`POST /v1/releases/`)
+3. Discovers `.js.map` files in the target directory
+4. Uploads source maps via presigned URLs
+5. Marks the release as preflight-confirmed so the collector accepts spans for it
+
+### Options
+
+```text
+interfere sourcemaps upload <dir> [options]
+
+Options:
+  --release <slug>     Override the release slug (default: derived from commit SHA)
+  --url <api-url>      Interfere collector URL (default: $INTERFERE_API_URL)
+  --auth-token <key>   Interfere API key (default: $INTERFERE_API_KEY)
+  --skip-preflight     Don't mark the release preflight-confirmed after upload
+  -h, --help           Show help
+  --version            Show version
+```
+
+## Environment Variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `INTERFERE_API_KEY` | Yes | Authenticates with the collector. Format: `interfere_ak_*` |
+| `INTERFERE_SOURCE_ID` | No | Override the commit SHA used to derive the release slug. Falls back to `VERCEL_GIT_COMMIT_SHA`, `GITHUB_SHA`, or `git rev-parse HEAD`. |
+| `INTERFERE_API_URL` | No | Override the default collector URL |
+
+## How release identity works
+
+The CLI and the SDK independently derive the same release slug from the commit SHA using a shared `deriveReleaseSlug()` function. For this to work, both must see the same SHA:
+
+- **At build time (CLI):** reads from `INTERFERE_SOURCE_ID`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, or `git rev-parse HEAD`
+- **At runtime (SDK):** reads from the same env vars or git
+
+In Docker deployments where `.git` isn't in the image, set `INTERFERE_SOURCE_ID` in the runtime environment to the same commit SHA used during the build.
+
+## Examples
+
+### GitHub Actions
+
+```yaml
+- name: Build
+  run: npm run build
+
+- name: Upload source maps
+  run: npx interfere sourcemaps upload ./dist
+  env:
+    INTERFERE_API_KEY: ${{ secrets.INTERFERE_API_KEY }}
+    # GITHUB_SHA is automatically available
 ```
 
-Slug is auto-derived from the commit SHA (same algorithm the SDK uses at runtime). Full docs at <https://interfere.com/docs>.
+### Docker
+
+```dockerfile
+ARG GIT_SHA
+ENV INTERFERE_SOURCE_ID=$GIT_SHA
+
+COPY dist/ ./dist/
+CMD ["node", "dist/main.js"]
+```
 
-For SDK 0.x migrations, keep the `INTERFERE_API_KEY` env var name but replace old `ak_*` values with the `interfere_ak_*` Interfere API key from the dashboard.
+```sh
+docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .
+```

package/dist/package.mjs

@@ -1 +1 @@
-var name=`@interfere/cli`,version=`0.0.2-canary.0`;export{name,version};
+var name=`@interfere/cli`,version=`0.0.2-canary.1`;export{name,version};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interfere/cli",
-  "version": "0.0.2-canary.0",
+  "version": "0.0.2-canary.1",
   "license": "MIT",
   "description": "Command-line tool for Interfere. Uploads source maps and confirms releases as part of your CI deploy.",
   "keywords": [