@getargus/build-tools 0.0.0-stage → 0.3.0

package/dist/cli-Poqz5E1p.d.cts

@@ -0,0 +1,317 @@
+import { B as BuildPlatform } from './ids-T7ddcOxQ.cjs';
+
+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 };