@aient/sourcemaps

Typed native debug artifacts

Version 0.3.4 adds verified Apple dSYM upload to the existing fail-closed native artifact command. Dart AOT upload and the existing upload source-map command are unchanged.

Install the CLI as an exact, lockfile-pinned development dependency in the application repository:

pnpm add -D --save-exact @aient/[email protected]

aient-sourcemaps upload-debug \
  --manifest build/aient-debug-artifacts.json \
  --distribution build/app-release.aab

For an iOS release, invoke the same installed binary against the manifest and IPA produced by that exact build:

pnpm exec aient-sourcemaps upload-debug \
  --manifest build/aient-debug-artifacts.json \
  --distribution build/Runner.ipa

upload-debug reads only strict schema_version: 1 snake_case manifests. It requires top-level service, exact lowercase 40-character commit_sha, release_id, app_version, build_number, variant, distribution, and artifacts. Each item is either dart_aot_dwarf or apple_dsym. An Apple item must select one thin, regular Mach-O DWARF member, use platform ios, include an arm64 or x86_64 architecture, and carry its canonical Mach-O UUID as debug_id; archives, universal objects, symlinks, and identity disagreement fail before any network call. Unknown keys, empty or duplicate artifact identities, unsafe paths, and byte/hash drift also fail closed. --distribution must select the exact AAB or IPA described by the manifest, preventing a rebuilt distributable from reusing stale symbols.

Set the upload-scoped AIENT_API_KEY and optionally AIENT_API_URL; never use a publishable OTLP ingest key. Debug uploads accept credentials only from the environment; --api-url and --dry-run remain supported. Dry-run verifies every local byte and makes no network calls. Successful output contains release identity, object basename, artifact kind, counts, and hash prefixes. Failure output preserves the original error and stack without redaction or truncation so CI retains complete diagnostic evidence. CI callers are responsible for keeping credentials out of exception values and protecting their logs.

The summary distinguishes artifacts accepted and committed to private storage from artifacts for which the server returned explicit enqueued processing evidence. --wait is rejected until Aient exposes a real processing-status receipt. Any per-item failure exits non-zero.

Command-line uploader for Aient source maps.

Use this package from CI after building a production frontend bundle. It scans a build output directory for source maps, resolves the runtime bundle paths Aient will see in minified stack frames, uploads the source map files, and commits them against a service name and git commit SHA.

pnpm dlx @aient/sourcemaps upload .next/static \
  --service web \
  --commit "$GITHUB_SHA" \
  --bundle-prefix /_next/static \
  --fail-on-empty

@aient/sourcemaps is a CLI package. Its internal TypeScript modules are not a public library API.

Requirements

• A production build that emits source maps.
• An Aient source map upload API key in CI. Use AIENT_API_KEY; do not ship this key to browser code.
• A runtime service name that matches telemetry service.name.
• A commit SHA that matches telemetry deployment.commit_sha.
• Runtime stack frame URLs that can be matched by the derived bundle path, usually with --bundle-prefix.

Install

Run directly:

pnpm dlx @aient/sourcemaps upload <directory> --service <service>

Or add it to a project:

pnpm add -D @aient/sourcemaps
pnpm exec aient-sourcemaps upload <directory> --service <service>

Command

aient-sourcemaps upload <directory> --service <service> [options]

<directory> is the build output directory to scan.

Options

| Option | Env var | Required | Default | Description | | --- | --- | --- | --- | --- | | <directory> | - | Yes | - | Build output directory containing source map files. | | --service, -s | - | Yes | - | Runtime service name. Must match telemetry service.name. | | --api-key, -k | AIENT_API_KEY | Yes | - | Aient source map upload key. | | --commit, -c | COMMIT_SHA, GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, CI_COMMIT_SHA | Yes | auto-detected | Git commit SHA. Must match telemetry deployment.commit_sha. | | --pattern | - | No | **/*.js.map | Source map file pattern. | | --bundle-prefix | - | No | none | URL/path prefix prepended to each derived runtime bundle path. | | --api-url | AIENT_API_URL | No | https://aient.ai | Aient API origin. | | --dry-run | - | No | false | List matched files without calling the API or uploading. | | --concurrency | AIENT_SOURCEMAPS_CONCURRENCY | No | 6 | Maximum concurrent file uploads. Must be a positive integer. | | --fail-on-empty | - | No | false | Exit non-zero when no source maps are found. |

Explicit flags win over environment variables.

The CLI accepts the kebab-case flags shown above. Its generated help may display camelCase names such as --bundlePrefix; those aliases work too.

Matching Contract

Aient resolves a minified frame only when all of these values line up:

| Value | Must match | | --- | --- | | --service | The telemetry resource attribute service.name. | | --commit | The telemetry deployment attribute deployment.commit_sha. | | Derived bundle path | The minified stack frame filename/path seen at runtime. |

For Next.js static assets, the build directory is often .next/static, while runtime frame URLs contain /_next/static/.... Use --bundle-prefix /_next/static so uploaded bundle paths match runtime frames.

flowchart LR
  build["CI production build"] --> scan["aient-sourcemaps scans maps"]
  scan --> paths["derive runtime bundle paths"]
  paths --> upload["upload source maps"]
  upload --> resolve["Aient resolves production stack frames"]

Bundle Path Derivation

For each matching source map file, the uploader derives one or more bundlePath values:

1. It scans local .js and .css bundles under <directory> for sourceMappingURL comments.
2. If a bundle points at a known local map, that bundle path is used.
3. If multiple runtime bundles point at one physical map, the uploader creates one upload candidate per runtime bundle.
4. If no runtime bundle references the map, the uploader falls back to stripping the .map suffix. For example, chunks/main.js.map becomes chunks/main.js.
5. If --bundle-prefix is set, it is prepended to the derived bundle path. For example, chunks/main.js becomes /_next/static/chunks/main.js.

Remote, inline, missing, and out-of-directory sourceMappingURL targets are ignored. Query strings and fragments on local sourceMappingURL values are ignored before matching.

The scanner skips tiny empty Next.js/Turbopack map stubs whose JSON explicitly contains sources: [] and no sections, because they cannot improve stack trace resolution.

Pattern Support

The pattern matcher is intentionally small. Supported shapes are:

• **/*.js.map: recursive suffix match.
• *.js.map: flat suffix match.
• **/*.map: recursive match for all map files, including CSS maps.
• exact-file-name.map: exact filename match.

Use --pattern "**/*.map" if you want to include non-JavaScript maps.

Upload Flow

For a normal upload run:

1. Discover source maps and derive bundle paths.
2. Resolve --service through GET /api/sourcemaps/service-config?name=....
3. Preflight uploads through POST /api/sourcemaps/create-upload/bulk.
4. Hash each source map with SHA-256 before upload.
5. Skip artifacts that Aient reports as already committed with the same hash.
6. Upload changed files to presigned object-storage URLs with PUT.
7. Commit uploaded artifacts through POST /api/sourcemaps/commit/bulk.
8. Print a summary and exit non-zero if any upload failed.

Bulk create and commit requests are chunked at 100 items. If the bulk create-upload endpoint is unavailable on an older Aient deployment, the CLI falls back to single-file create/upload/commit endpoints. It does not fall back after files have already been uploaded and bulk commit fails, because that could duplicate side effects.

API requests to Aient retry transient failures with delays of 500 ms, 2 seconds, and 5 seconds. Retryable HTTP statuses are 408, 429, 502, 503, and 504. Presigned object-storage PUT requests are not retried by the CLI.

CI Examples

GitHub Actions

name: Upload source maps

on:
  push:
    branches: [main]

jobs:
  sourcemaps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: |
          pnpm dlx @aient/sourcemaps upload .next/static \
            --service web \
            --commit "$GITHUB_SHA" \
            --bundle-prefix /_next/static \
            --fail-on-empty
        env:
          AIENT_API_KEY: ${{ secrets.AIENT_SOURCEMAPS_API_KEY }}

Vercel

pnpm dlx @aient/sourcemaps upload .next/static \
  --service web \
  --commit "$VERCEL_GIT_COMMIT_SHA" \
  --bundle-prefix /_next/static \
  --fail-on-empty

Generic Vite or SPA Build

pnpm dlx @aient/sourcemaps upload dist \
  --service web \
  --commit "$COMMIT_SHA" \
  --pattern "**/*.js.map" \
  --fail-on-empty

If runtime stack frames include a public asset prefix, add it:

pnpm dlx @aient/sourcemaps upload dist/assets \
  --service web \
  --commit "$COMMIT_SHA" \
  --bundle-prefix /assets

Exit Behavior

The CLI exits non-zero when:

• --api-key is missing and AIENT_API_KEY is unset.
• --commit is missing and no supported commit environment variable or local git SHA can be detected.
• --concurrency or AIENT_SOURCEMAPS_CONCURRENCY is not a positive integer.
• --fail-on-empty is set and no source maps are found.
• One or more source map uploads fail.
• Service-config lookup or a required API call fails.

--dry-run never calls the Aient API and never uploads files.

Troubleshooting

No Source Map Files Found

Check that the production build emits source maps and that <directory> points at the directory containing them. For Next.js static browser maps this is usually .next/static.

Use:

pnpm dlx @aient/sourcemaps upload .next/static \
  --service web \
  --dry-run

Uploaded But Frames Are Still Minified

Verify all matching fields:

• --service equals telemetry service.name.
• --commit equals telemetry deployment.commit_sha.
• --bundle-prefix makes uploaded bundle paths match production stack frame paths.
• The deployed code was built from the same commit whose source maps were uploaded.

Missing API Key

Set AIENT_API_KEY in CI secrets or pass --api-key. The key is a server-side upload credential and must not be exposed to browser bundles, public logs, or client-side environment variables.

Rate Limits Or Temporary API Failures

Lower concurrency:

AIENT_SOURCEMAPS_CONCURRENCY=2 pnpm dlx @aient/sourcemaps upload .next/static \
  --service web \
  --commit "$COMMIT_SHA" \
  --bundle-prefix /_next/static

Maintainer Notes

The package build emits dist/cli.mjs from src/cli.ts. Before publishing or changing behavior, run:

pnpm --filter @aient/sourcemaps test
pnpm --filter @aient/sourcemaps type-check
pnpm --filter @aient/sourcemaps build