@rootnode-app/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @rootnode-app/cli
 
-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.
+Upload the files that turn release crashes into real code lines —
+iOS dSYMs, Android ProGuard/R8 mappings, native debug files and JS source maps —
+to [Rootnode](https://rootnode.app). Authenticates with the app's analytics
+key; nothing else to configure.
+
+## Expo / EAS (automatic)
+
+```jsonc
+// app.json → "expo"
+"plugins": ["@rootnode-app/react-native"]
+
+// package.json → "scripts"
+"eas-build-on-success": "npx @rootnode-app/cli eas"
+```
+
+After every successful EAS build it finds that build's dSYMs, mapping, bundle
+and source map and uploads them under the release the SDK reports
+(`bundleId@version+build`). Uses `EXPO_PUBLIC_ROOTNODE_KEY` (or `ROOTNODE_KEY`).
+Never fails the build unless you pass `--strict`.
+
+## Any build
+
+```bash
+export ROOTNODE_KEY=rn_…
+npx @rootnode-app/cli upload-symbols --target ios ./build/App.xcarchive
+npx @rootnode-app/cli upload-symbols --target android app/build/outputs/mapping/release/mapping.txt
+npx @rootnode-app/cli upload-sourcemaps --target react-native \
+  --bundle index.android.bundle --map index.android.bundle.map \
+  --release com.acme.shop@2.1.0+47 --dist 47
+```
+
+`--target`: which target of the app the crashes come from (`react-native`
+default, `ios`, `android`, …). `--host` for self-hosted Rootnode.
+
+Symbols apply to crashes received **after** the upload — upload during the
+build, not after the first crash. Check the result in the panel: Setup →
+target → Symbols.
+
+MIT © Doğan Aktı. Bundles the BSD-3-licensed upload engine at a pinned version.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const discover_1 = require("./discover");
+const plan_1 = require("./plan");
+async function resolveTarget(o) {
+    const res = await fetch(`${o.host}/api/0/rootnode/targets/${encodeURIComponent(o.target)}`, {
+        headers: { Authorization: `Bearer ${o.key}` },
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (res.status === 401)
+        throw new Error('the key was rejected — use the app\'s analytics key (rn_…)');
+    if (!res.ok || !body.organization || !body.project)
+        throw new Error(body.detail ?? `target lookup failed (http ${res.status})`);
+    return { organization: body.organization, project: body.project };
+}
+function uploaderPath() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require('@sentry/cli').getPath();
+}
+/** The uploader talks about itself; our users only ever deal with Rootnode. */
+const rebrand = (text) => text.replace(/\bsentry-cli\b/gi, 'rootnode').replace(/\bSentry\b/g, 'Rootnode');
+function execute(runs, env) {
+    let ok = true;
+    for (const r of runs) {
+        console.log(`rootnode: uploading ${r.label}…`);
+        const p = (0, child_process_1.spawnSync)(uploaderPath(), r.args, { stdio: ['inherit', 'pipe', 'pipe'], env: { ...process.env, ...env }, encoding: 'utf8' });
+        process.stdout.write(rebrand(p.stdout ?? ''));
+        process.stderr.write(rebrand(p.stderr ?? ''));
+        if (p.status !== 0) {
+            ok = false;
+            console.error(`rootnode: ${r.label} failed (exit ${p.status ?? p.signal})`);
+        }
+    }
+    return ok;
+}
+function runsFor(out) {
+    const runs = (0, plan_1.symbolRuns)(out.debugPaths);
+    if (out.bundle && out.map && out.release)
+        runs.push((0, plan_1.sourcemapRun)(out.bundle, out.map, out.release, out.dist));
+    return runs;
+}
+async function main(argv) {
+    const cmd = (0, plan_1.parseArgs)(argv, process.env);
+    const o = cmd.options;
+    if (cmd.name === 'help') {
+        console.log(plan_1.HELP);
+        return 0;
+    }
+    if (!o.key)
+        throw new Error('no key — pass --key rn_… or set ROOTNODE_KEY (EXPO_PUBLIC_ROOTNODE_KEY works too)');
+    if (cmd.name === 'eas') {
+        // EAS runs this hook once per platform; outside EAS both are tried.
+        const platform = process.env.EAS_BUILD_PLATFORM;
+        const root = process.cwd();
+        const outs = [platform !== 'android' && (0, discover_1.discoverIos)(root), platform !== 'ios' && (0, discover_1.discoverAndroid)(root)].filter(Boolean);
+        for (const out of outs)
+            for (const n of out.notes)
+                console.log(`rootnode: ${out.platform}: ${n}`);
+        const runs = outs.flatMap(runsFor);
+        if (!runs.length) {
+            console.log('rootnode: nothing to upload');
+            return 0;
+        }
+        try {
+            const ok = execute(runs, (0, plan_1.uploaderEnv)(o, await resolveTarget(o)));
+            return ok || !o.strict ? 0 : 1;
+        }
+        catch (e) {
+            console.error(`rootnode: ${e.message}`);
+            return o.strict ? 1 : 0; // an upload problem must not fail a good build
+        }
+    }
+    const target = await resolveTarget(o);
+    if (cmd.name === 'upload-symbols') {
+        if (!o.paths.length)
+            throw new Error('give the dSYM / .xcarchive / .so folder / mapping.txt paths');
+        return execute((0, plan_1.symbolRuns)(o.paths), (0, plan_1.uploaderEnv)(o, target)) ? 0 : 1;
+    }
+    if (!o.bundle || !o.map || !o.release)
+        throw new Error('upload-sourcemaps needs --bundle, --map and --release');
+    return execute([(0, plan_1.sourcemapRun)(o.bundle, o.map, o.release, o.dist)], (0, plan_1.uploaderEnv)(o, target)) ? 0 : 1;
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    console.error(`rootnode: ${e.message}`);
+    process.exit(1);
+});

package/dist/discover.d.ts

@@ -0,0 +1,19 @@
+/** What one native build left behind that crash readability needs. */
+export interface BuildOutputs {
+    platform: 'ios' | 'android';
+    debugPaths: string[];
+    bundle: string | null;
+    map: string | null;
+    release: string | null;
+    dist: string | null;
+    notes: string[];
+}
+export type PlistReader = (file: string) => Record<string, any> | null;
+/** Info.plist may be binary — plutil (present on every macOS build machine) reads both. */
+export declare const readPlist: PlistReader;
+/** iOS: the .xcarchive EAS/xcodebuild produced under ios/build, plus the map our config plugin writes next to it. */
+/** Newest .xcarchive in Xcode's Archives folder (where fastlane/gym archives by default), if made in the last 3 hours. */
+export declare function newestXcodeArchive(home: string, now?: number): string | null;
+export declare function discoverIos(root: string, plist?: PlistReader, home?: string, override?: string | undefined): BuildOutputs;
+/** Android: R8 mapping, the release bundle + its (Hermes-composed) source map, version from build.gradle. */
+export declare function discoverAndroid(root: string): BuildOutputs;

package/dist/discover.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPlist = void 0;
+exports.newestXcodeArchive = newestXcodeArchive;
+exports.discoverIos = discoverIos;
+exports.discoverAndroid = discoverAndroid;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const plan_1 = require("./plan");
+/** Info.plist may be binary — plutil (present on every macOS build machine) reads both. */
+const readPlist = (file) => {
+    try {
+        return JSON.parse((0, child_process_1.execFileSync)('plutil', ['-convert', 'json', '-o', '-', file], { encoding: 'utf8' }));
+    }
+    catch {
+        return null;
+    }
+};
+exports.readPlist = readPlist;
+const dirs = (p) => ((0, fs_1.existsSync)(p) ? (0, fs_1.readdirSync)(p).filter((n) => (0, fs_1.statSync)((0, path_1.join)(p, n)).isDirectory()) : []);
+const first = (...paths) => paths.find((p) => (0, fs_1.existsSync)(p)) ?? null;
+/** iOS: the .xcarchive EAS/xcodebuild produced under ios/build, plus the map our config plugin writes next to it. */
+/** Newest .xcarchive in Xcode's Archives folder (where fastlane/gym archives by default), if made in the last 3 hours. */
+function newestXcodeArchive(home, now = Date.now()) {
+    const base = (0, path_1.join)(home, 'Library', 'Developer', 'Xcode', 'Archives');
+    const all = dirs(base).flatMap((day) => dirs((0, path_1.join)(base, day)).filter((n) => n.endsWith('.xcarchive')).map((n) => (0, path_1.join)(base, day, n)));
+    const fresh = all.map((p) => ({ p, t: (0, fs_1.statSync)(p).mtimeMs })).filter((x) => now - x.t < 3 * 3600_000);
+    return fresh.sort((a, b) => b.t - a.t)[0]?.p ?? null;
+}
+function discoverIos(root, plist = exports.readPlist, home = (0, os_1.homedir)(), override = process.env.ROOTNODE_IOS_ARCHIVE) {
+    const out = { platform: 'ios', debugPaths: [], bundle: null, map: null, release: null, dist: null, notes: [] };
+    const buildDir = (0, path_1.join)(root, 'ios', 'build');
+    const local = dirs(buildDir).find((n) => n.endsWith('.xcarchive'));
+    const arch = override || (local ? (0, path_1.join)(buildDir, local) : newestXcodeArchive(home));
+    if (!arch || !(0, fs_1.existsSync)(arch)) {
+        out.notes.push('no .xcarchive under ios/build or in Xcode Archives — nothing to upload for iOS (set ROOTNODE_IOS_ARCHIVE to point at one)');
+        return out;
+    }
+    const archive = arch.split('/').pop();
+    const dsyms = (0, path_1.join)(arch, 'dSYMs');
+    if ((0, fs_1.existsSync)(dsyms))
+        out.debugPaths.push(dsyms);
+    else
+        out.notes.push(`${archive} has no dSYMs folder (is DEBUG_INFORMATION_FORMAT dwarf-with-dsym?)`);
+    const apps = (0, path_1.join)(arch, 'Products', 'Applications');
+    const appName = dirs(apps).find((n) => n.endsWith('.app'));
+    if (appName)
+        out.bundle = first((0, path_1.join)(apps, appName, 'main.jsbundle'));
+    out.map = first((0, path_1.join)(buildDir, 'main.jsbundle.map'));
+    if (out.bundle && !out.map)
+        out.notes.push('no ios/build/main.jsbundle.map — add the "@rootnode-app/react-native" plugin to app.json so the build writes it');
+    const info = plist((0, path_1.join)(arch, 'Info.plist'))?.ApplicationProperties;
+    if (info?.CFBundleIdentifier && info?.CFBundleShortVersionString && info?.CFBundleVersion) {
+        out.release = (0, plan_1.releaseName)(info.CFBundleIdentifier, info.CFBundleShortVersionString, String(info.CFBundleVersion));
+        out.dist = String(info.CFBundleVersion);
+    }
+    else
+        out.notes.push('could not read the version from the archive Info.plist');
+    return out;
+}
+/** Android: R8 mapping, the release bundle + its (Hermes-composed) source map, version from build.gradle. */
+function discoverAndroid(root) {
+    const out = { platform: 'android', debugPaths: [], bundle: null, map: null, release: null, dist: null, notes: [] };
+    const app = (0, path_1.join)(root, 'android', 'app');
+    const b = (0, path_1.join)(app, 'build');
+    if (!(0, fs_1.existsSync)(b)) {
+        out.notes.push('no android/app/build — nothing to upload for Android');
+        return out;
+    }
+    const mapping = first((0, path_1.join)(b, 'outputs', 'mapping', 'release', 'mapping.txt'));
+    if (mapping)
+        out.debugPaths.push(mapping);
+    const nativeLibs = first((0, path_1.join)(b, 'intermediates', 'merged_native_libs', 'release'));
+    if (nativeLibs)
+        out.debugPaths.push(nativeLibs);
+    out.bundle = first((0, path_1.join)(b, 'generated', 'assets', 'react', 'release', 'index.android.bundle'), (0, path_1.join)(b, 'generated', 'assets', 'createBundleReleaseJsAndAssets', 'index.android.bundle'));
+    out.map = first((0, path_1.join)(b, 'generated', 'sourcemaps', 'react', 'release', 'index.android.bundle.map'), (0, path_1.join)(b, 'generated', 'sourcemaps', 'react', 'release', 'index.android.bundle.packager.map'));
+    const gradle = first((0, path_1.join)(app, 'build.gradle'), (0, path_1.join)(app, 'build.gradle.kts'));
+    const text = gradle ? (0, fs_1.readFileSync)(gradle, 'utf8') : '';
+    const id = text.match(/applicationId\s*=?\s*["']([^"']+)["']/)?.[1];
+    const code = text.match(/versionCode\s*=?\s*(\d+)/)?.[1];
+    const name = text.match(/versionName\s*=?\s*["']([^"']+)["']/)?.[1];
+    if (id && code && name) {
+        out.release = (0, plan_1.releaseName)(id, name, code);
+        out.dist = code;
+    }
+    else
+        out.notes.push('could not read applicationId / versionName / versionCode from android/app/build.gradle');
+    return out;
+}

package/dist/plan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure planning for the Rootnode CLI: which upload runs to make, with which
+ * arguments. The uploader underneath is sentry-cli 2.58.2 (BSD-3, pinned —
+ * later versions are FSL); nothing here touches the network or the disk.
+ */
+export interface Options {
+    key: string | null;
+    host: string;
+    target: string;
+    release: string | null;
+    dist: string | null;
+    bundle: string | null;
+    map: string | null;
+    strict: boolean;
+    paths: string[];
+}
+export type Command = {
+    name: 'upload-symbols' | 'upload-sourcemaps' | 'eas' | 'help';
+    options: Options;
+};
+export interface UploadTarget {
+    organization: string;
+    project: string;
+}
+export interface Run {
+    label: string;
+    args: string[];
+}
+export declare const DEFAULT_HOST = "https://rootnode.app";
+export declare function parseArgs(argv: string[], env: Record<string, string | undefined>): Command;
+/** Environment for the uploader: our host, the app's analytics key, the resolved org/project. */
+export declare function uploaderEnv(o: Options, t: UploadTarget): Record<string, string>;
+/** ProGuard/R8 mapping files go through their own upload; everything else is a debug file (dSYM, .so, archive). */
+export declare function symbolRuns(paths: string[]): Run[];
+/** A Hermes/JS bundle with its source map, tied to the release the SDK reports. */
+export declare function sourcemapRun(bundle: string, map: string, release: string, dist: string | null): Run;
+/** The release name the React Native SDK reports: bundleId@version+build. */
+export declare const releaseName: (id: string, version: string, build: string) => string;
+export declare const HELP = "rootnode \u2014 upload symbols so release crashes show real code lines\n\n  rootnode eas\n      After an EAS build (package.json \"eas-build-on-success\": \"rootnode eas\"):\n      finds this build's dSYMs, ProGuard mapping and JS bundle + source map and\n      uploads them. Never fails the build unless --strict.\n\n  rootnode upload-symbols <path...>\n      dSYM folders, .xcarchive, unstripped .so folders, mapping.txt.\n\n  rootnode upload-sourcemaps --bundle <file> --map <file> --release <name> [--dist <build>]\n\nOptions\n  --key <rn_\u2026>      the app's analytics key (default: ROOTNODE_KEY or EXPO_PUBLIC_ROOTNODE_KEY)\n  --target <name>   which target of the app: react-native (default), ios, android\u2026\n  --host <url>      default https://rootnode.app\n  --strict          exit non-zero when an upload fails";

package/dist/plan.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Pure planning for the Rootnode CLI: which upload runs to make, with which
+ * arguments. The uploader underneath is sentry-cli 2.58.2 (BSD-3, pinned —
+ * later versions are FSL); nothing here touches the network or the disk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = exports.releaseName = exports.DEFAULT_HOST = void 0;
+exports.parseArgs = parseArgs;
+exports.uploaderEnv = uploaderEnv;
+exports.symbolRuns = symbolRuns;
+exports.sourcemapRun = sourcemapRun;
+exports.DEFAULT_HOST = 'https://rootnode.app';
+function parseArgs(argv, env) {
+    const [name = 'help', ...rest] = argv;
+    const o = {
+        key: env.ROOTNODE_KEY ?? env.EXPO_PUBLIC_ROOTNODE_KEY ?? null,
+        host: (env.ROOTNODE_HOST ?? exports.DEFAULT_HOST).replace(/\/$/, ''),
+        target: env.ROOTNODE_TARGET ?? 'react-native',
+        release: null,
+        dist: null,
+        bundle: null,
+        map: null,
+        strict: false,
+        paths: [],
+    };
+    const flags = {
+        '--key': (v) => (o.key = v),
+        '--host': (v) => (o.host = v.replace(/\/$/, '')),
+        '--target': (v) => (o.target = v),
+        '--release': (v) => (o.release = v),
+        '--dist': (v) => (o.dist = v),
+        '--bundle': (v) => (o.bundle = v),
+        '--map': (v) => (o.map = v),
+    };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        const [flag, inline] = a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+        if (flag === '--strict')
+            o.strict = true;
+        else if (flags[flag]) {
+            const v = inline ?? rest[++i];
+            if (v === undefined)
+                throw new Error(`${flag} needs a value`);
+            flags[flag](v);
+        }
+        else if (a.startsWith('--'))
+            throw new Error(`unknown option ${a}`);
+        else
+            o.paths.push(a);
+    }
+    const known = ['upload-symbols', 'upload-sourcemaps', 'eas', 'help', '--help', '-h'];
+    if (!known.includes(name))
+        throw new Error(`unknown command "${name}" — run: rootnode help`);
+    return { name: name.startsWith('-') ? 'help' : name, options: o };
+}
+/** Environment for the uploader: our host, the app's analytics key, the resolved org/project. */
+function uploaderEnv(o, t) {
+    return {
+        SENTRY_URL: o.host,
+        SENTRY_AUTH_TOKEN: o.key ?? '',
+        SENTRY_ORG: t.organization,
+        SENTRY_PROJECT: t.project,
+        SENTRY_DISABLE_UPDATE_CHECK: 'true',
+    };
+}
+/** ProGuard/R8 mapping files go through their own upload; everything else is a debug file (dSYM, .so, archive). */
+function symbolRuns(paths) {
+    const mappings = paths.filter((p) => /mapping\.txt$/i.test(p));
+    const debug = paths.filter((p) => !mappings.includes(p));
+    const runs = [];
+    if (debug.length)
+        runs.push({ label: `debug files (${debug.length})`, args: ['debug-files', 'upload', ...debug] });
+    for (const m of mappings)
+        runs.push({ label: 'ProGuard mapping', args: ['upload-proguard', m] });
+    return runs;
+}
+/** A Hermes/JS bundle with its source map, tied to the release the SDK reports. */
+function sourcemapRun(bundle, map, release, dist) {
+    return {
+        label: `source map (${release}${dist ? `, build ${dist}` : ''})`,
+        args: ['sourcemaps', 'upload', '--release', release, ...(dist ? ['--dist', dist] : []), '--bundle', bundle, '--bundle-sourcemap', map],
+    };
+}
+/** The release name the React Native SDK reports: bundleId@version+build. */
+const releaseName = (id, version, build) => `${id}@${version}+${build}`;
+exports.releaseName = releaseName;
+exports.HELP = `rootnode — upload symbols so release crashes show real code lines
+
+  rootnode eas
+      After an EAS build (package.json "eas-build-on-success": "rootnode eas"):
+      finds this build's dSYMs, ProGuard mapping and JS bundle + source map and
+      uploads them. Never fails the build unless --strict.
+
+  rootnode upload-symbols <path...>
+      dSYM folders, .xcarchive, unstripped .so folders, mapping.txt.
+
+  rootnode upload-sourcemaps --bundle <file> --map <file> --release <name> [--dist <build>]
+
+Options
+  --key <rn_…>      the app's analytics key (default: ROOTNODE_KEY or EXPO_PUBLIC_ROOTNODE_KEY)
+  --target <name>   which target of the app: react-native (default), ios, android…
+  --host <url>      default ${exports.DEFAULT_HOST}
+  --strict          exit non-zero when an upload fails`;

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@rootnode-app/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Rootnode command line: upload dSYMs, ProGuard mappings, native debug files and source maps so release crashes show real code lines.",
+  "license": "MIT",
+  "author": "Doğan Aktı",
+  "homepage": "https://rootnode.app/docs/integration.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doganakti/rootnode.git",
+    "directory": "sdk/cli"
+  },
+  "bin": {
+    "rootnode": "dist/bin.js"
+  },
+  "main": "dist/plan.js",
+  "types": "dist/plan.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "dependencies": {
+    "@sentry/cli": "2.58.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  }
+}