@getargus/build-tools 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Argus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+# @getargus/build-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Argus' own build integration — it replaces vendor Metro / Next wrappers. Node only, no
+dependencies. Four jobs:
+
+0. **Setup**: `npx @getargus/build-tools init` detects Next.js / Node / Expo and writes the
+   instrumentation files, the config wrapper and the env names ([Setup](#setup-argus-build-init)).
+1. **Identity**: generate an artifact set id at build start (`artifacts-v1.md` §1).
+2. **Injection**: get that id into the bundle as *source* that goes through the bundler, so the
+   bundle and its source map stay consistent. Built output, `.map` files and Hermes bytecode are
+   never patched.
+3. **Upload**: find the artifacts a build produced, decide which artifact set each belongs to,
+   and upload them — for Next.js at the end of `next build`, with no extra CI step.
+
+> **Status.** The Next.js path is verified against real `next build` runs of Next 15.5 (webpack
+> and Turbopack, also `output: 'standalone'`) with a local artifacts server: both sets uploaded
+> once, browser maps gone afterwards. `init` was run in a fresh Next app that was then built for
+> real. No real Metro, EAS, Xcode or Gradle build has been run through this package. See
+> [Verification status](#verification-status).
+
+## Setup: `argus-build init`
+
+```
+npx @getargus/build-tools init            # show what would be written (asks before writing on a terminal)
+npx @getargus/build-tools init --yes      # write
+npx @getargus/build-tools init --yes --dsn 'https://<ingest key>@<host>'
+npx @getargus/build-tools init --dry-run  # never writes, whatever else is given
+```
+
+Reads `package.json` in the current directory (in a monorepo: run it inside the app's package;
+`--dir <path>` points elsewhere) and prints every file it writes, in full.
+
+| Project | Written | Printed for you to do |
+|---|---|---|
+| Next.js (app or pages router, `src/` or not, TS or JS) | `instrumentation.ts` (`register` + `onRequestError`), `instrumentation-client.ts`, `withArgus()` around the export of `next.config.*` (or a new `next.config.mjs`), the variable names in `.env.example` | install command, where to set the DSN and the upload variables |
+| Node (ESM or CommonJS, TS or JS) | `argus.ts` / `.js` / `.mjs` / `.cjs` with `init()` (in `src/` when it exists), `ARGUS_DSN=` in `.env.example` | install command, the `import './argus.js'` line for the entry file |
+| Expo / React Native | nothing | packages, the `app.json` plugin entry, the `metro.config.js` lines, the upload command |
+
+What it will not do:
+
+* **Overwrite a file.** An existing `instrumentation.*` or `argus.*` is left alone and the snippet
+  to merge is printed. `next.config.*` is rewritten only when its export is a single
+  `export default <identifier>` / `module.exports = <identifier>`; any other shape (an object
+  literal, another wrapper, a function) gets the two-line diff printed instead.
+* **Put a secret in a tracked file.** `.env.example` gets names without values. `--dsn` writes to
+  `.env.local` (Next) or `.env` (Node) only if git ignores that file; otherwise the lines are
+  printed.
+* **Install anything.** The command for the detected package manager (`packageManager` field,
+  else the nearest lockfile: pnpm, yarn, bun, npm) is printed.
+* **Change anything on a second run.** Files that already use Argus are reported as `ok`.
+
+Without `--yes` and without a terminal (CI, a pipe) it only prints the plan.
+
+## Programmatic API
+
+```ts
+import {
+  newArtifactSetId, isValidArtifactSetId, resolveArtifactSetId,
+  artifactSetPrelude, writeArtifactSetModule /* alias: injectArtifactSetId */,
+  planNext, planExpoExport, planNative, planFiles, uploadArgs, formatCommand, runUploads,
+  uploadNextBuild,              // what withArgus runs at the end of `next build`
+  planInit, applyInit, runInit, // `argus-build init` as functions
+} from '@getargus/build-tools';
+import { withArgus } from '@getargus/build-tools/metro';   // Metro config helper
+import { withArgus } from '@getargus/build-tools/next';    // Next.js config helper
+```
+
+* `newArtifactSetId(prefix)` → `<prefix>-<uuidv7 hex>`, same format as `argus artifacts new-id`.
+* `resolveArtifactSetId(option, platform, env)` — `ARGUS_ARTIFACT_SET_ID_<PLATFORM>` →
+  `ARGUS_ARTIFACT_SET_ID` → option. Environment wins so CI can inject the id; the
+  `@getargus/expo` config plugin follows the same rule for the native side.
+* `writeArtifactSetModule({ file, artifactSetId })` writes a generated source file defining
+  `globalThis.__ARGUS_ARTIFACT_SET_ID__`. It is idempotent and refuses to overwrite any file it
+  did not generate.
+* `plan*()` return `UploadPlan`s (one artifact set, one platform, explicit file list, warnings);
+  `uploadArgs(plan)` turns one into CLI arguments; `runUploads(plans)` executes them in order and
+  stops at the first failure.
+
+### Metro (React Native / Expo)
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+const { withArgus } = require('@getargus/build-tools/metro');
+module.exports = withArgus(getDefaultConfig(__dirname), { /* artifactSetId: { ios, android } */ });
+```
+
+Writes `<projectRoot>/.argus/argus-artifact-set.<platform>.js` when the config is evaluated and
+appends the matching file to `serializer.getPolyfills({ platform })`, after the existing
+polyfills. A polyfill is part of the bundle Metro serialises and of the map it composes, and it
+runs before any module — before Hermes compiles anything. Add `.argus/` to `.gitignore`.
+
+An artifact set has one platform. A single-platform build (EAS build, `expo run:*`) can use
+`ARGUS_ARTIFACT_SET_ID`; a process that bundles several platforms (`expo export`) needs
+`ARGUS_ARTIFACT_SET_ID_IOS` and `ARGUS_ARTIFACT_SET_ID_ANDROID`. A platform without an id is
+bundled unchanged and a warning is printed once.
+
+### Next.js
+
+```js
+// next.config.mjs
+import { withArgus } from '@getargus/build-tools/next';
+export default withArgus({ /* your config */ }, { /* options */ });
+```
+
+With `ARGUS_URL` and `ARGUS_UPLOAD_KEY` in the environment of `next build`, that is all: the
+build gets an artifact set id, compiles it in, uploads the browser and the server source maps to
+their two sets and removes the browser maps from the output. Without those variables nothing is
+uploaded and nothing is printed.
+
+* **Id.** Adds `env.NEXT_PUBLIC_ARGUS_ARTIFACT_SET_ID` (browser set) and
+  `env.ARGUS_SERVER_ARTIFACT_SET_ID` (server set, default `<id>-node`). Next inlines `env` values
+  at build time; no DefinePlugin and no post-processing. Pass them to the SDKs:
+  `initClient({ artifactSetId: process.env.NEXT_PUBLIC_ARGUS_ARTIFACT_SET_ID })` in the browser,
+  `register({ artifactSetId: process.env.ARGUS_SERVER_ARTIFACT_SET_ID })` on the server
+  (`argus-build init` writes both). The id comes from `ARGUS_ARTIFACT_SET_ID[_WEB]`, else the
+  `artifactSetId` option; a build that uploads and has neither generates one
+  (`next-<uuidv7>`) and keeps it in `ARGUS_ARTIFACT_SET_ID_WEB`, so Next's build workers compile
+  in the same id the upload uses. Do not hard-code an id: a set is one build.
+* **Upload** — `upload: 'auto' | true | false` (default `'auto'`: when both variables are set).
+  It runs in Next's `compiler.runAfterProductionCompile` hook: once per `next build`, in the main
+  process, after the server, edge and client compilers (webpack or Turbopack) have written their
+  output, before type checking and static generation. `ARGUS_RELEASE` and `ARGUS_GIT_SHA` are
+  put on the manifest. **Needs Next 15.4+**; on an older Next a warning says so once and you run
+  `argus-build upload next --delete-maps` after the build.
+* **A failed upload** — `onUploadError: 'warn' | 'fail'` (default `'warn'`): the reason is
+  printed and the build continues, because a monitoring outage must not block a deploy. `'fail'`
+  fails the build.
+* **Browser maps** — `productionBrowserSourceMaps` is set unless you set it yourself; Next then
+  writes `.next/static/**/*.js.map` **and would serve them**. `deleteBrowserMapsAfterUpload`
+  (default: true when `withArgus` turned the maps on, false when your config did) removes them
+  when the upload step is over — also after a failed upload that only warned, since that build
+  goes on to be deployed. With `onUploadError: 'fail'` they are left for a retry. **A build
+  without upload credentials emits no browser maps**; when you upload in a separate step, pass
+  `browserSourceMaps: true` and run `argus-build upload next --delete-maps` before deploying.
+* **Server maps** — `serverSourceMaps` sets `devtool: 'source-map'` for the production server
+  compilation (your `webpack` hook is chained). Default: on when the build uploads, off
+  otherwise. Turbopack writes server maps on its own. If you run Node with
+  `--enable-source-maps`, stacks are already mapped and marked `premapped` by `@getargus/node`;
+  do not rely on both.
+* **Names** — browser chunks are named `<urlPrefix>static/...`; `urlPrefix` defaults to
+  `/_next/` below the path of `assetPrefix`, else `basePath`.
+
+### Expo / React Native: upload after the build
+
+There is no Metro upload hook yet; run one command after the build, with `ARGUS_URL` and
+`ARGUS_UPLOAD_KEY` set:
+
+```sh
+# after `expo export` (OTA update); ids are the ones the bundles were built with
+npx argus-build upload expo-export --ios-set-id "$ARGUS_ARTIFACT_SET_ID_IOS" --android-set-id "$ARGUS_ARTIFACT_SET_ID_ANDROID"
+
+# after an EAS / native build (needs the argus binary for dSYMs and mapping.txt)
+npx argus-build upload ios     --set-id "$ARGUS_ARTIFACT_SET_ID" --dir <xcarchive or dSYMs folder>
+npx argus-build upload android --set-id "$ARGUS_ARTIFACT_SET_ID" --dir android/app/build
+```
+
+On EAS, the `eas-build-on-success` npm script is the place for it.
+
+## CLI
+
+```
+argus-build init [--dsn <dsn>] [--yes] [--dry-run] [--dir <project>]   # see Setup
+argus-build new-id [--prefix <p>]
+argus-build prelude --set-id <id> --out <file>
+argus-build collect <target> [options]      # print the per-set file list and the argus commands; no network
+argus-build upload  <target> [options]      # upload each set (--dry-run, --print, --transport)
+```
+
+The upload key is read from `ARGUS_UPLOAD_KEY`; it is never put on a command line. `ARGUS_URL`
+selects the server.
+
+**No binary needed for JavaScript.** Sets that contain only source maps and bundles (`next`,
+`expo-export`, `files` with JS) are uploaded from Node over HTTP: manifest, missing blobs,
+finalize. Re-running uploads nothing that is already there, and the command fails unless the set
+ends up `ready`. Sets with native symbols (dSYM, ELF, R8 mapping) go through the `argus` binary,
+which validates them with the server's own parser; `ARGUS_BIN` / `--argus-bin` selects it and
+also forces it for JS sets. `--transport http|cli|auto` (env `ARGUS_UPLOAD_TRANSPORT`) overrides
+the choice.
+
+| Target | Artifact sets | Files | Naming (`--strip-prefix` / `--url-prefix`) |
+|---|---|---|---|
+| `next` | `next:browser` → `--set-id`, platform `web` | `.next/static/**/*.js` + `.js.map` (pairs only) | `/_next/static/chunks/app-123.js` (`.next` / `/_next/`; change with `--url-prefix` for a basePath) |
+| | `next:server` → `--server-set-id` (default `<id>-node`), platform `node` | `.next/server/**/*.js` + `.js.map` | `.next/server/app/page.js` (project dir / none) |
+| `expo-export` | one per platform: `--ios-set-id`, `--android-set-id`; `--ota`, `--update-id`, `--runtime-version`, `--parent-set-id` | the bundle named in `dist/metadata.json` + its `.map` | `entry-<hash>.hbc` (file name) |
+| `ios` | `--set-id`, platform `ios` | every `*.dSYM` under `--dir` (passed as directories), `*.jsbundle.map` / `*.bundle.map` and the bundle next to it | `main.jsbundle` (file name) |
+| `android` | `--set-id`, platform `android` | `mapping.txt`, `*.bundle.map`, the bundle (`--bundle`), `.so` with `--native-libs` | `index.android.bundle` (file name) |
+| `files` | `--set-id`, `--platform` | `*.map` + generated file under `--dir` | as given |
+
+Browser and server chunks of a Next build never share a set: same file names can exist in both,
+and the server resolves a frame by artifact set + name. `next --delete-maps` removes the browser
+`.map` files from `.next/static` after **all** uploads succeeded.
+
+Turbopack names a browser chunk's map after the map's own hash (`21…80.js` →
+`4b…ca.js.map`); such a map is paired with its chunk through the chunk's `sourceMappingURL`
+comment and uploaded under the chunk's name. Only the HTTP transport can say that; the `argus`
+binary names a map after its file, so do not force `ARGUS_BIN` for a Turbopack build.
+
+Update id for `expo-export`: taken from `--update-id` / `--ios-update-id` / `--android-update-id`,
+else from `metadata.json` if it has `fileMetadata.<platform>.updateId|id` or a top-level
+`updateId|id`. A stock `expo export` `metadata.json` is not known to contain one, so pass the id
+your update server assigned; without it the plan still works (matching is by artifact set id) and
+a warning is printed.
+
+## Verification status
+
+| Integration point | State |
+|---|---|
+| Id format, validation, env precedence | unit-tested |
+| Generated prelude defines the global; generated file is idempotent; foreign files are never overwritten | unit-tested (evaluated in a `vm` context) |
+| Metro `withArgus`: polyfill list composition per platform, chaining, missing id | unit-tested against a structural config. **Not run in Metro**: that Metro (as shipped with Expo SDK 57) transforms a file under `<projectRoot>/.argus/`, includes it in the bundle and its source map, that Expo's serializer honours `getPolyfills` on every platform, and that the global is readable from Hermes bytecode |
+| Next `withArgus`: `env`, source map flags, webpack hook chaining, config functions | unit-tested against plain objects, and run in `next build` (Next 15.5.29, `examples/next-trpc`): the generated id was found in both the browser and the server bundles and equals the uploaded set ids |
+| Next upload at the end of the build | **run for real** against a local artifacts-v1 server, webpack: 2 manifests, 2 finalizes, each blob PUT once, 0 `.map` left under `.next/static`, server maps kept. Same with `--turbopack` and with `output: 'standalone'`. A 503 server: build passes with a warning by default and fails with `onUploadError: 'fail'`. No credentials: no output, no hook. **Not verified**: Next 15.4 itself (the hook was checked to exist in its package, not run), Next 16, rspack, `experimental-build-mode`, and symbolication of a Turbopack frame on the real server |
+| `argus-build init` | unit-tested in temp directories (detection, file contents, no overwrite, dry run, idempotency, DSN only into git-ignored files); run in a fresh TypeScript `src/` app-router project whose result passed a real `next build` including type checking, and in a minimal ESM Node project. **Not verified**: that the first event reaches a server from those projects (no server was run), the Expo steps, the pages router beyond detection |
+| File discovery and set separation for Next / Expo export / iOS / Android | unit-tested on fixture trees shaped like the documented outputs; the Next layout also on real `.next` output of 15.5 (webpack and Turbopack). **Not verified**: `expo export` of SDK 57, Xcode / Gradle / EAS artifact locations |
+| CLI arguments | unit-tested; additionally accepted by the real `argus artifacts upload --dry-run`, whose manifest showed the expected `platform`, `is_embedded`, `update_id`, `parent_artifact_set_id`, `name` and `bundle_name` for web, Next and Expo-export fixtures |
+| dSYM / `mapping.txt` / `.so` handling by the Rust CLI | not exercised here (fixtures are placeholders, not real symbol files) |
+| Whether the names produced here equal the file names in real runtime stack frames (OTA bundles loaded by expo-updates from its own storage path in particular) | **not verified**; if they differ, symbolication reports `missing_artifact` rather than a wrong line |
+| A real upload followed by symbolication of a known frame | not done |

package/bin/argus-build.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+// Thin launcher kept outside dist/ so the bin link exists before the package is built.
+require('../dist/cli.cjs')
+  .main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  });

package/dist/cli-C6Vb06ix.d.ts

@@ -0,0 +1,317 @@
+import { B as BuildPlatform } from './ids-T7ddcOxQ.js';
+
+type ArtifactFileKind = 'sourcemap' | 'js_bundle' | 'dsym' | 'proguard' | 'elf';
+/** Mirrors `classify` in crates/cli/src/upload.rs (hermes maps are detected by the CLI from content). */
+declare function classifyArtifact(path: string): ArtifactFileKind | undefined;
+/** Recursive file list, sorted, symlinks not followed. */
+declare function walkFiles(dir: string, opts?: {
+    skipDirs?: ReadonlySet<string>;
+}): string[];
+interface UploadMeta {
+    release?: string | undefined;
+    dist?: string | undefined;
+    nativeRelease?: string | undefined;
+    nativeBuild?: string | undefined;
+    runtimeVersion?: string | undefined;
+    gitSha?: string | undefined;
+}
+interface UploadPlan extends UploadMeta {
+    /** e.g. `next:browser`, `expo-export:ios`, `native:android`. */
+    label: string;
+    artifactSetId: string;
+    platform: BuildPlatform;
+    /** Absolute paths handed to the CLI. A `.dSYM` bundle is passed as its directory. */
+    paths: string[];
+    /** Every file that will be part of the set, with its kind — what `collect` prints. */
+    files: {
+        path: string;
+        kind: ArtifactFileKind;
+        size: number;
+    }[];
+    /** `--strip-prefix`: removed from JS paths to form the name frames are matched against. */
+    stripPrefix?: string | undefined;
+    /** `--url-prefix`: prepended to that name. */
+    urlPrefix?: string | undefined;
+    /**
+     * Source map → generated file, for maps not named `<generated file>.map` (Turbopack chunks).
+     * Only the HTTP transport honours it; the argus CLI names a map after its own file name.
+     */
+    generatedFor?: Record<string, string> | undefined;
+    /** OTA update (not embedded in a native binary). */
+    ota?: boolean | undefined;
+    updateId?: string | undefined;
+    /** Artifact set of the native build this OTA update runs on (native symbols are resolved there). */
+    parentSetId?: string | undefined;
+    warnings: string[];
+}
+interface NextPlanOptions extends UploadMeta {
+    /** Project directory containing the build output. Default `process.cwd()`. */
+    projectDir?: string;
+    /** Build output directory relative to the project. Default `.next`. */
+    distDir?: string;
+    /** Artifact set of the browser chunks. */
+    artifactSetId: string;
+    /** Artifact set of the server chunks. Default `<artifactSetId>-node`. */
+    serverArtifactSetId?: string;
+    /** Public path the browser loads chunks from. Default `/_next/` (add your basePath / assetPrefix path). */
+    urlPrefix?: string;
+    /** Upload the generated JS next to each map. Default true. */
+    includeBundles?: boolean;
+}
+declare function planNext(options: NextPlanOptions): UploadPlan[];
+/** Deletes browser `.map` files from the build output so they are never deployed or served. Returns the removed paths. */
+declare function browserSourceMaps(projectDir: string, distDir?: string): string[];
+type MobilePlatform = 'ios' | 'android';
+interface ExpoExportPlanOptions extends UploadMeta {
+    /** Output directory of `expo export`. Default `dist`. */
+    exportDir?: string;
+    /** One artifact set per platform (an artifact set has exactly one platform). */
+    artifactSetIds: Partial<Record<MobilePlatform, string>>;
+    /** Limit to these platforms. Default: every platform in `metadata.json` that has an id. */
+    platforms?: MobilePlatform[];
+    /** OTA update id per platform (or one string for a single platform). Falls back to `metadata.json` when it carries one. */
+    updateId?: string | Partial<Record<MobilePlatform, string>>;
+    /** Artifact set of the native build the update targets, per platform. */
+    parentSetIds?: Partial<Record<MobilePlatform, string>>;
+}
+/**
+ * One plan per platform from `expo export` output: the bundle named by
+ * `metadata.json → fileMetadata.<platform>.bundle` and its `.map` (export with
+ * `--dump-sourcemap` / `--source-maps`). Marked `--ota` with update id, runtime version and the
+ * parent (native build) set.
+ */
+declare function planExpoExport(options: ExpoExportPlanOptions): UploadPlan[];
+interface NativePlanOptions extends UploadMeta {
+    platform: MobilePlatform;
+    artifactSetId: string;
+    /**
+     * Directories / files to search: an `.xcarchive`, a `dSYMs` folder, `ios/build`,
+     * `android/app/build`, an EAS artifacts folder, or explicit files.
+     */
+    searchPaths: string[];
+    /** Embedded JS bundle and its (Hermes-composed) source map, when not found by the search. */
+    bundle?: string;
+    sourcemap?: string;
+    /** Android: also upload unstripped `.so` files found under the search paths. Default false. */
+    includeNativeLibs?: boolean;
+}
+/**
+ * The embedded build of one platform — one artifact set holding
+ *  - iOS: every `.dSYM` bundle + `main.jsbundle(.map)`;
+ *  - Android: R8 `mapping.txt` + `index.android.bundle(.map)` (+ unstripped `.so` on request).
+ * JS files keep their file name (`index.android.bundle`), which is what Hermes frames report.
+ */
+declare function planNative(options: NativePlanOptions): UploadPlan;
+interface FilesPlanOptions extends UploadMeta {
+    artifactSetId: string;
+    platform: BuildPlatform;
+    /** Files or directories; directories are searched for `*.map` with their generated file. */
+    paths: string[];
+    stripPrefix?: string;
+    urlPrefix?: string;
+    includeBundles?: boolean;
+}
+/** Any bundler output (esbuild, Vite, a worker build…): source maps plus their generated files. */
+declare function planFiles(options: FilesPlanOptions): UploadPlan;
+/**
+ * Arguments for the Rust CLI: `argus artifacts upload …` (flags as defined in
+ * crates/cli/src/upload.rs). The upload key is never put on the command line; the CLI reads
+ * `ARGUS_UPLOAD_KEY` (and `ARGUS_URL`) from the environment.
+ */
+declare function uploadArgs(plan: UploadPlan, opts?: {
+    dryRun?: boolean;
+    url?: string;
+}): string[];
+/** The name a JS file gets in the manifest (`bundle_name`), mirroring the CLI's rule. For display and tests. */
+declare function manifestName(plan: Pick<UploadPlan, 'stripPrefix' | 'urlPrefix' | 'generatedFor'>, file: string): string;
+/** A copy-pasteable shell command for a plan (paths relative to `cwd` when inside it). */
+declare function formatCommand(bin: string, args: string[], cwd?: string): string;
+
+type ProjectKind = 'next' | 'expo' | 'react-native' | 'node';
+type PackageManager = 'pnpm' | 'yarn' | 'npm' | 'bun';
+interface ProjectInfo {
+    kind: ProjectKind;
+    dir: string;
+    /** Package name from `package.json`, for messages only. */
+    name: string | undefined;
+    typescript: boolean;
+    /** `"type": "module"` in package.json. */
+    esm: boolean;
+    packageManager: PackageManager;
+    /** All dependency names (dependencies + devDependencies). */
+    deps: Set<string>;
+    /** Next: `src` when the app lives in `src/`, else ``. Node: `src` when that directory exists. */
+    sourceDir: string;
+    /** Next only. */
+    router?: 'app' | 'pages' | undefined;
+    nextConfig?: string | undefined;
+    /** Next only: `[major, minor]` of the installed (else declared) version. */
+    nextVersion?: [number, number] | undefined;
+    /** Node only: `main` of package.json when it names a file. */
+    main?: string | undefined;
+}
+interface PackageJson {
+    name?: unknown;
+    type?: unknown;
+    main?: unknown;
+    packageManager?: unknown;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/** Lockfile next to package.json, else in a parent (a workspace keeps one lockfile at its root). */
+declare function detectPackageManager(dir: string, pkg?: PackageJson): PackageManager;
+/** Reads `package.json` in `dir` (only there: in a monorepo, run it inside the app's package). */
+declare function detectProject(dir: string): ProjectInfo;
+interface InitAction {
+    /** `create`/`append`/`modify` write; `ok` is already in place; `manual` is printed for the user to do. */
+    type: 'create' | 'append' | 'modify' | 'ok' | 'manual';
+    /** Path relative to the project directory. */
+    file: string;
+    /** One line: what and why. */
+    summary: string;
+    /** create: the whole file. append: the text added at the end. modify: the whole new file. */
+    content?: string;
+    /** What is shown for the action: the new file, the appended lines, a diff or a snippet. */
+    preview?: string;
+}
+interface InitPlan {
+    project: ProjectInfo;
+    actions: InitAction[];
+    /** Missing packages, as the command for the project's package manager. */
+    install: string | undefined;
+    /** What is left for the user, in order. */
+    nextSteps: string[];
+}
+interface InitOptions {
+    /** Project directory. Default `process.cwd()`. */
+    dir?: string;
+    /** Written to a git-ignored local env file (`.env.local` for Next, `.env` for Node); never to a tracked file. */
+    dsn?: string;
+}
+/** Decides what to do. Reads the project, writes nothing. */
+declare function planInit(options?: InitOptions): InitPlan;
+/** Applies the writing actions of a plan. Refuses to replace a file that appeared since planning. */
+declare function applyInit(plan: InitPlan): string[];
+type RenderMode = 'applied' | 'dry-run' | 'preview';
+/** The full report of a plan. */
+declare function renderInit(plan: InitPlan, mode: RenderMode): string;
+interface RunInitOptions extends InitOptions {
+    /** Write without asking. */
+    yes?: boolean;
+    /** Never write. Wins over `yes`. */
+    dryRun?: boolean;
+    /** Asked once when neither flag is given and there is something to write. Absent: do not ask, do not write. */
+    confirm?: (question: string) => Promise<boolean>;
+    out?: (text: string) => void;
+}
+/** Plan, show, and write when allowed. Returns the plan and the files written. */
+declare function runInit(options?: RunInitOptions): Promise<{
+    plan: InitPlan;
+    written: string[];
+}>;
+
+type HttpFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string | Uint8Array;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+interface HttpUploadOptions {
+    /** Server base URL, e.g. `https://argus.example.com`. */
+    url: string;
+    /** Upload key (kind `upload`). */
+    uploadKey: string;
+    dryRun?: boolean;
+    fetch?: HttpFetch;
+    log?: (line: string) => void;
+}
+interface ManifestFileEntry {
+    kind: 'sourcemap' | 'hermes_sourcemap' | 'js_bundle';
+    name: string;
+    bundle_name?: string;
+    sha256: string;
+    size: number;
+}
+interface Found {
+    path: string;
+    file: ManifestFileEntry;
+}
+/** True when every file of the plan can be uploaded without the CLI. */
+declare function isJsOnlyPlan(plan: UploadPlan): boolean;
+/** Builds the manifest for a JS-only plan. Exported for tests and `--dry-run`. */
+declare function buildManifest(plan: UploadPlan): Promise<{
+    manifest: Record<string, unknown>;
+    found: Found[];
+}>;
+/**
+ * Creates the set, uploads the blobs the server does not have yet and finalizes. Idempotent:
+ * re-running with identical files uploads nothing. Throws unless the set ends up `ready`.
+ */
+declare function uploadPlanOverHttp(plan: UploadPlan, options: HttpUploadOptions): Promise<{
+    status: string;
+    uploaded: number;
+    files: number;
+}>;
+
+interface RunResult {
+    plan: UploadPlan;
+    command: string;
+    code: number;
+}
+interface RunOptions {
+    /** The `argus` binary. Default: `$ARGUS_BIN`, else `argus` on PATH. */
+    bin?: string;
+    /** Pass `--dry-run`: the CLI prints the manifest and uploads nothing. */
+    dryRun?: boolean;
+    /** Server base URL (`--url`). Default: the CLI's own `ARGUS_URL` handling. */
+    url?: string;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    /**
+     * `http`: upload from Node (JS artifacts only). `cli`: run the `argus` binary. Default `auto`
+     * (env `ARGUS_UPLOAD_TRANSPORT`): HTTP for JS-only sets unless `ARGUS_BIN` names a binary,
+     * the CLI for sets with native symbols.
+     */
+    transport?: 'auto' | 'http' | 'cli';
+    /** HTTP client for the `http` transport, replaceable in tests. */
+    fetch?: HttpFetch;
+    /** Process launcher, replaceable in tests. Resolves with the exit code. */
+    exec?: (bin: string, args: string[], opts: {
+        env: Record<string, string | undefined>;
+        cwd: string;
+    }) => Promise<number>;
+    log?: (line: string) => void;
+}
+/**
+ * Uploads the plans one after another and stops at the first failure (a build must not be
+ * promoted with a half-uploaded artifact set). Credentials come from the environment
+ * (`ARGUS_UPLOAD_KEY`); they are never placed on the command line.
+ */
+declare function runUploads(plans: UploadPlan[], options?: RunOptions): Promise<RunResult[]>;
+
+declare const USAGE = "argus-build <command>\n\n  init [--dsn <dsn>] [--yes] [--dry-run] [--dir <project>]\n                                            set a Next.js / Node / Expo project up for Argus: prints every file it\n                                            would write; writes with --yes (or after asking, on a terminal); never\n                                            overwrites a file, never installs anything\n  new-id [--prefix <p>]                     print a new artifact set id (same format as `argus artifacts new-id`)\n  prelude --set-id <id> --out <file>        write the generated module that defines globalThis.__ARGUS_ARTIFACT_SET_ID__\n  collect <target> [options]                print what would be uploaded, per artifact set (no network)\n  upload  <target> [options]                upload each artifact set (JS sets over HTTP, native symbols via the argus CLI)\n\nTargets\n  next          --set-id <web id> [--server-set-id <id>] [--dir <project>] [--dist-dir .next] [--url-prefix /_next/]\n                browser chunks and server chunks go to two different sets (default server id: <web id>-node)\n  expo-export   --ios-set-id <id> --android-set-id <id> [--dir dist] [--platform ios|android]\n                [--update-id <id> | --ios-update-id <id> --android-update-id <id>]\n                [--parent-set-id <id> | --ios-parent-set-id <id> --android-parent-set-id <id>] [--runtime-version <v>]\n  ios           --set-id <id> --dir <xcarchive | dSYMs | build dir>... [--bundle <main.jsbundle>] [--sourcemap <map>]\n  android       --set-id <id> --dir <android/app/build>... [--bundle <f>] [--sourcemap <map>] [--native-libs]\n  files         --set-id <id> --platform <ios|android|web|node> --dir <dir or file>... [--strip-prefix <p>] [--url-prefix <p>]\n\nCommon options\n  --release <r> --dist <d> --native-release <v> --native-build <b> --runtime-version <v> --git-sha <sha>\n  --no-bundles          upload source maps only (next, files)\n  --json                collect: machine readable output\n  --dry-run             upload: print the manifests and upload nothing\n  --print               upload: only print the commands\n  --transport <t>       upload: http (from Node, JS artifacts only), cli (the argus binary) or auto (default:\n                        http for JS-only sets, cli for native symbols)\n  --delete-maps         upload next: delete browser .map files from the build output after a successful upload\n  --argus-bin <path>    the argus binary (default $ARGUS_BIN, else \"argus\")\n  --url <base url>      server (default: $ARGUS_URL as read by the argus CLI)\n\nEnvironment: ARGUS_UPLOAD_KEY (upload key; never passed on the command line), ARGUS_URL, ARGUS_BIN, ARGUS_GIT_SHA.\n";
+interface ParsedArgs {
+    positionals: string[];
+    flags: Record<string, string | boolean | undefined>;
+    multi: Record<string, string[]>;
+}
+declare function parseArgs(argv: string[]): ParsedArgs;
+/** Builds the upload plans for a target from CLI arguments. Exported for tests. */
+declare function plansFor(target: string, args: ParsedArgs, env?: Record<string, string | undefined>, cwd?: string): UploadPlan[];
+/** Human readable listing of the plans: what `collect` prints. */
+declare function renderPlans(plans: UploadPlan[], bin: string, cwd: string): string;
+interface CliIo {
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    exec?: RunOptions['exec'];
+    /** `init`: asks before writing. Default: a y/N prompt when stdin and stdout are terminals, else no prompt. */
+    confirm?: RunInitOptions['confirm'];
+}
+/** Runs the CLI. Returns the process exit code; never throws. */
+declare function main(argv: string[], io?: CliIo): Promise<number>;
+
+export { type ArtifactFileKind as A, runUploads as B, uploadArgs as C, uploadPlanOverHttp as D, type ExpoExportPlanOptions as E, type FilesPlanOptions as F, walkFiles as G, type HttpFetch as H, type InitAction as I, type CliIo as J, type ParsedArgs as K, USAGE as L, type MobilePlatform as M, type NativePlanOptions as N, parseArgs as O, type PackageManager as P, plansFor as Q, type RunOptions as R, renderPlans as S, type UploadMeta as U, type HttpUploadOptions as a, type InitOptions as b, type InitPlan as c, type NextPlanOptions as d, type ProjectInfo as e, type ProjectKind as f, type RunInitOptions as g, type RunResult as h, type UploadPlan as i, applyInit as j, browserSourceMaps as k, buildManifest as l, classifyArtifact as m, detectPackageManager as n, detectProject as o, formatCommand as p, isJsOnlyPlan as q, manifestName as r, planExpoExport as s, planFiles as t, planInit as u, planNative as v, planNext as w, renderInit as x, main as y, runInit as z };