@lynxship/cli 0.1.7 → 0.1.10

package/README.md

@@ -2,14 +2,14 @@
 
 Build, sign, store, submit and update LynxJS applications from the terminal.
 
-LynxShip connects a real Rspeedy bundle to the native Android or iOS build
-toolchain, verifies the resulting signature, uploads immutable artifacts to
-Cloudflare R2 and exposes an expiring download URL with a compact terminal QR
-code.
+LynxShip connects a real Rspeedy bundle to the selected Lynx target, runs the
+official target toolchain, verifies the artifact where the platform exposes an
+official verifier, uploads immutable artifacts to Cloudflare R2 and exposes an
+expiring download URL with a compact terminal QR code.
 
-> LynxShip is currently beta software. Android local builds are exercised
-> end-to-end. iOS builds require macOS and Xcode. Store submission still uses
-> the developer's own Google Play or App Store Connect credentials.
+> LynxShip never fabricates a target artifact. Android and iOS require their
+> native hosts; HarmonyOS requires the official Hvigor/DevEco host; Web and
+> Desktop require the project's official Rspeedy/Lynxtron configuration.
 
 ## Install
 
@@ -33,8 +33,29 @@ The package exposes the `lynxship` executable.
 - Android builds on Windows, macOS or Linux: JDK 17, Android SDK command-line
   tools, `adb`, build tools and an executable project Gradle wrapper.
 - iOS builds: macOS, Xcode and Xcode command-line tools.
+- HarmonyOS builds: an official Lynx Harmony host, DevEco/OpenHarmony SDK,
+  `ohpm`, the project `hvigorw` wrapper, Java and the official HAP signing tool.
+- Web builds: the project's Web environment (`environments.web`) or an
+  explicit `build:web` script that produces one `*.web.bundle` in `dist/`,
+  `build/web/` or `build/`.
+- Desktop builds: the official Lynxtron host/builder, or an Electron Builder
+  host with `pack`, `build:desktop` or `build:app`, on a supported target OS.
 - Cloudflare R2 credentials for artifact storage.
 
+After a native host exists, inspect and repair the Android toolchain with:
+
+```bash
+lynxship doctor --project-dir ./my-lynx-app --platform android
+lynxship doctor --project-dir ./my-lynx-app --platform android --fix
+```
+
+The Android doctor reads the project's wrapper and Android Gradle Plugin before
+checking Java, the SDK path, `compileSdk`, Build Tools, `adb`, `apksigner` and
+licenses. The wrapper is authoritative; a machine-wide Gradle installation is
+not required. `--fix` may install missing SDK packages with `sdkmanager` only
+after confirmation. It never silently installs Android Studio or a JDK, edits
+Gradle files, changes the wrapper or touches signing credentials.
+
 ## First configuration
 
 Run these once on each development or CI machine:
@@ -119,8 +140,11 @@ init                 Initialize or link a project
 doctor               Check the local toolchain and project
 dev                  Run Rspeedy dev with Lynx Explorer QR/HMR
 preview              Preview the production bundle locally
+devtool doctor       Check Lynx DevTool and development runtime
+trace doctor         Check Lynx Trace prerequisites
+recorder doctor      Check Lynx Recorder prerequisites
 build create         Build, sign and upload an artifact
-build all            Build Android and iOS on a macOS host
+build all            Build Android, iOS, HarmonyOS, Web and Desktop
 build list           List build jobs
 build status <id>    Inspect one build job
 build cancel <id>    Cancel a build job
@@ -129,8 +153,8 @@ submit               Submit the latest successful artifact
 update               Publish a signed OTA update
 update rollback      Roll back an OTA channel to a previous release
 rollback             Compatibility alias for update rollback
-run                  Install an artifact on a target
-logs                 Stream native logs
+run                  Install an Android, iOS or HarmonyOS artifact
+logs                 Stream Android, iOS or HarmonyOS native logs
 autolink check       Check Lynx native-library wiring
 autolink codegen     Run native-module codegen
 ota doctor           Check native OTA host integration
@@ -161,8 +185,11 @@ Next steps
 ```
 
 `lynxship dev` is for Lynx Explorer and live QR/HMR development. The Android
-host command creates the native Gradle project needed for a real APK/AAB.
-`--local` remains a contract-test mode and never creates a fake artifact.
+host command creates the native Gradle project needed for a real APK/AAB. An
+interactive real build creates a missing host after asking for the application
+ID; CI must pass `--application-id`. Existing native directories are never
+overwritten. `--local` remains a contract-test mode and never creates a fake
+artifact.
 
 To build both native platforms in one local workflow, use the multi-platform
 selector:
@@ -180,10 +207,110 @@ signing setup. Windows and Linux can still run
 `lynxship build --platform android`; use a macOS CI worker for the iOS half.
 `--local` can exercise both contract paths without creating APK or IPA files.
 
-The same guidance covers missing R2 or signing setup, Android SDK tools,
-Autolink/codegen, iOS Xcode/CocoaPods, device tools, store credentials and
-OTA compatibility. In automation, use `--json`; failures include a
-machine-readable `nextSteps` array and optional `note` field.
+The same guidance covers missing R2 or signing setup, native SDK tools,
+Autolink/codegen, target packaging, device tools, store credentials and OTA
+compatibility. In automation, use `--json`; failures include a machine-readable
+`nextSteps` array and optional `note` field.
+
+## Web, HarmonyOS and Desktop targets
+
+These adapters use existing official host contracts; they do not generate a
+fictional native runtime.
+
+### Web
+
+Configure Rspeedy with the official Web environment and build the Web bundle:
+
+```json
+{
+  "build": {
+    "production": {
+      "web": {
+        "environment": "web",
+        "artifact": "dist/main.web.bundle"
+      }
+    }
+  }
+}
+```
+
+```bash
+lynxship doctor --platform web
+lynxship build --platform web --profile production
+```
+
+The adapter invokes the profile's `web.script`, then an existing project
+`build:web` script, and only otherwise uses `rspeedy build --environment web`.
+It then requires exactly one Web bundle output unless the profile declares an
+explicit artifact path.
+
+### HarmonyOS
+
+Use the official Lynx Harmony integration under `harmony/`. The project must
+provide `hvigorw`, `hvigorfile.ts`, `build-profile.json5` and
+`oh-package.json5`. LynxShip runs `ohpm install`, the pinned wrapper in release
+mode, then verifies the signed HAP with the official `hap-sign-tool.jar`.
+
+Optional profile overrides are explicit and remain project-owned:
+
+```json
+{
+  "build": {
+    "production": {
+      "harmony": {
+        "mode": "module",
+        "product": "default",
+        "module": "entry@default",
+        "buildMode": "release",
+        "task": "assembleHap"
+      }
+    }
+  }
+}
+```
+
+```bash
+lynxship doctor --platform harmony
+lynxship build --platform harmony --profile production --no-upload
+lynxship run --platform harmony --artifact .lynxship/artifacts/<uuid>.hap
+lynxship logs --platform harmony --device <device-id>
+```
+
+Set `LYNXSHIP_HAP_SIGN_TOOL` or `build.<profile>.harmony.signTool`; HAP signing
+keys and profiles remain owned by the Harmony project and are never generated
+or printed by LynxShip.
+
+### Desktop
+
+Use the official Lynxtron host and builder, or an Electron Builder host. The
+adapter invokes the configured `desktop.script`, then `pack`, `build:desktop`,
+or `build:app`, and otherwise runs `lynxtron-builder --publish never`. It then
+requires one distributable such as `.dmg`, `.exe`, `.appimage` or `.zip`.
+
+```json
+{
+  "build": {
+    "production": {
+      "desktop": {
+        "script": "pack"
+      }
+    }
+  }
+}
+```
+
+```bash
+lynxship doctor --platform desktop
+lynxship build --platform desktop --profile production --no-upload
+```
+
+Desktop signing is checked before and after packaging. Windows builds require
+a valid Authenticode signature; macOS builds require a valid Apple code
+signature when the artifact exposes an app bundle. Configure the Lynxtron/
+`electron-builder` signing inputs (`WIN_CSC_LINK`/`CSC_LINK`, protected
+passwords, or the platform identity). Production and uploaded artifacts stop
+when verification fails. Use `--allow-unsigned --no-upload` only for local
+packaging tests.
 
 ## OTA rollback
 
@@ -228,9 +355,10 @@ but no `android/` directory.
 
 Production APK/AAB builds require a native Android host. The host is the
 Android application that initializes Lynx, creates `LynxView`, loads the bundle
-and contains the Gradle wrapper. `lynxship build` detects that requirement and
-fails clearly when `android/gradlew` is absent; `--local` only tests LynxShip's
-contract state machine and never fabricates an APK.
+and contains the Gradle wrapper. `lynxship build` creates the host when
+`android/` is absent, or fails with a repair instruction when an existing host
+is incomplete; `--local` only tests LynxShip's contract state machine and never
+fabricates an APK.
 
 To create a minimal host for a pure project:
 
@@ -258,6 +386,34 @@ script. On macOS, `lynxship build --platform ios` installs CocoaPods before
 archiving. Xcode, CocoaPods and real Apple signing credentials are still
 required for a signed IPA; the CLI never fabricates them.
 
+Run the complete first-use diagnosis before building:
+
+```bash
+lynxship doctor --project-dir ./my-lynx-app --platform ios
+```
+
+The iOS doctor checks the active macOS developer directory, Xcode and
+`xcodebuild`, `xcrun`, `codesign`, IPA verification tools, the host and scheme,
+Xcode build settings, Apple team, valid Apple Distribution/Development
+identity, CocoaPods when a `Podfile` exists, export method and provisioning
+profile validity. It does not print certificate or provisioning-profile
+contents. Xcode-managed signing is reported as a warning when profiles are not
+cached locally; manual signing without a valid matching profile fails before
+the archive starts.
+
+### Lynx DevTool, Trace and Recorder
+
+```bash
+lynxship devtool doctor --platform android
+lynxship trace doctor --platform android
+lynxship recorder doctor --platform android
+```
+
+These checks validate the project development script, native DevTool/Trace
+dependencies and USB transport. Trace and Recorder require Lynx's matching
+`-dev` runtime; the official Lynx DevTool Desktop application performs the
+actual recording and analysis.
+
 ## Package layout
 
 The CLI is backed by the public `@lynxship/*` runtime packages in this

package/dist/android-toolchain.d.ts

@@ -0,0 +1,23 @@
+export type ToolchainCheckStatus = "pass" | "warn" | "fail";
+export interface ToolchainCheck {
+    name: string;
+    status: ToolchainCheckStatus;
+    ok: boolean;
+    value: string;
+    fix?: string;
+}
+export interface AndroidToolchainReport {
+    ok: boolean;
+    checks: ToolchainCheck[];
+    sdkPath?: string;
+    compileSdk?: number;
+    buildToolsVersion?: string;
+    agpVersion?: string;
+    gradleVersion?: string;
+    javaVersion?: number;
+    sdkPackages: string[];
+}
+export declare function inspectAndroidToolchain(root: string): Promise<AndroidToolchainReport>;
+export declare function fixAndroidToolchain(root: string, report: AndroidToolchainReport, confirm: (message: string) => Promise<boolean>, onOutput?: (line: string) => void): Promise<void>;
+export declare function formatAndroidToolchainFailure(report: AndroidToolchainReport): string;
+//# sourceMappingURL=android-toolchain.d.ts.map

package/dist/android-toolchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"android-toolchain.d.ts","sourceRoot":"","sources":["../src/android-toolchain.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,oBAAoB,CAAC;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAgQD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sBAAsB,CAAC,CA2LjC;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC9C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAChC,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAQR"}

package/dist/android-toolchain.js

@@ -0,0 +1,319 @@
+import { homedir, platform } from "node:os";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, normalize } from "node:path";
+import { captureProcess, commandExists, executableExists, runProcess, } from "./process-runner.js";
+const agpMinimumGradle = [
+    ["9.2", "9.4.1"],
+    ["9.1", "9.3.1"],
+    ["9.0", "9.1.0"],
+    ["8.13", "8.13"],
+    ["8.12", "8.13"],
+    ["8.11", "8.13"],
+    ["8.10", "8.11.1"],
+    ["8.9", "8.11.1"],
+    ["8.8", "8.10.2"],
+    ["8.7", "8.9"],
+    ["8.6", "8.7"],
+    ["8.5", "8.7"],
+    ["8.4", "8.6"],
+    ["8.3", "8.4"],
+    ["8.2", "8.2"],
+    ["8.1", "8.0"],
+    ["8.0", "8.0"],
+    ["7.4", "7.5"],
+    ["7.3", "7.4"],
+    ["7.2", "7.3.3"],
+    ["7.1", "7.2"],
+    ["7.0", "7.0"],
+];
+function readProjectFiles(root) {
+    const files = [
+        "android/build.gradle",
+        "android/build.gradle.kts",
+        "android/settings.gradle",
+        "android/settings.gradle.kts",
+        "android/app/build.gradle",
+        "android/app/build.gradle.kts",
+        "android/gradle/libs.versions.toml",
+    ];
+    return files
+        .filter((file) => existsSync(join(root, file)))
+        .map((file) => readFileSync(join(root, file), "utf8"))
+        .join("\n");
+}
+function readWrapperVersion(root) {
+    const file = join(root, "android", "gradle", "wrapper", "gradle-wrapper.properties");
+    if (!existsSync(file))
+        return undefined;
+    const content = readFileSync(file, "utf8");
+    return content.match(/gradle-([0-9]+(?:\.[0-9]+){1,2})-(?:bin|all)\.zip/)?.[1];
+}
+function readAndroidInputs(root) {
+    const content = readProjectFiles(root);
+    const agpVersion = content.match(/com\.android\.(?:application|library)["']?\)?\s+version\s+["']([0-9]+(?:\.[0-9]+){1,2})["']/)?.[1] ??
+        content.match(/com\.android\.tools\.build:gradle:([0-9]+(?:\.[0-9]+){1,2})/)?.[1];
+    const compileSdk = content.match(/compileSdk(?:Version)?\s*(?:=|\s)\s*["']?(\d+)/)?.[1];
+    const buildToolsVersion = content.match(/buildToolsVersion\s*(?:=|\s)\s*["']([^"']+)["']/)?.[1];
+    return {
+        agpVersion,
+        compileSdk: compileSdk ? Number(compileSdk) : undefined,
+        buildToolsVersion,
+        gradleVersion: readWrapperVersion(root),
+    };
+}
+function versionParts(version) {
+    return version.split(".").map((part) => Number(part) || 0);
+}
+function compareVersions(left, right) {
+    const a = versionParts(left);
+    const b = versionParts(right);
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference)
+            return difference;
+    }
+    return 0;
+}
+function requiredGradleForAgp(agp) {
+    if (!agp)
+        return undefined;
+    return agpMinimumGradle.find(([minimum]) => compareVersions(agp, minimum) >= 0)?.[1];
+}
+function requiredJavaForAgp(agp) {
+    if (!agp)
+        return 17;
+    if (compareVersions(agp, "8.0") >= 0)
+        return 17;
+    if (compareVersions(agp, "7.0") >= 0)
+        return 11;
+    return 8;
+}
+function sdkCandidates() {
+    const values = [process.env.ANDROID_SDK_ROOT, process.env.ANDROID_HOME];
+    if (platform() === "win32") {
+        values.push(process.env.LOCALAPPDATA
+            ? join(process.env.LOCALAPPDATA, "Android", "Sdk")
+            : undefined);
+    }
+    else if (platform() === "darwin") {
+        values.push(join(homedir(), "Library", "Android", "sdk"));
+    }
+    else {
+        values.push(join(homedir(), "Android", "Sdk"));
+    }
+    return [
+        ...new Set(values.filter((value) => Boolean(value)).map(normalize)),
+    ];
+}
+function sdkExecutable(sdkPath, name) {
+    const extension = platform() === "win32" ? ".exe" : "";
+    const candidates = [
+        join(sdkPath, "platform-tools", `${name}${extension}`),
+        ...readDirectories(join(sdkPath, "build-tools")).map((version) => join(sdkPath, "build-tools", version, `${name}${extension}`)),
+    ];
+    return candidates.find(executableExists);
+}
+function readDirectories(directory) {
+    try {
+        return readdirSync(directory);
+    }
+    catch {
+        return [];
+    }
+}
+function sdkManagerPath(sdkPath) {
+    const extension = platform() === "win32" ? ".bat" : "";
+    const candidates = [
+        join(sdkPath, "cmdline-tools", "latest", "bin", `sdkmanager${extension}`),
+        ...readDirectories(join(sdkPath, "cmdline-tools"))
+            .filter((name) => name !== "latest")
+            .map((name) => join(sdkPath, "cmdline-tools", name, "bin", `sdkmanager${extension}`)),
+        join(sdkPath, "tools", "bin", `sdkmanager${extension}`),
+    ];
+    return (candidates.find(executableExists) ??
+        (commandExists("sdkmanager") ? "sdkmanager" : undefined));
+}
+async function javaVersion(javaPath, cwd) {
+    try {
+        const result = await captureProcess(javaPath, ["-version"], { cwd });
+        const output = `${result.stdout}\n${result.stderr}`;
+        const match = output.match(/version\s+["'](\d+)(?:\.(\d+))?/i);
+        if (!match)
+            return undefined;
+        return Number(match[1]) === 1 ? Number(match[2]) : Number(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+function javaCandidates() {
+    const executable = platform() === "win32" ? "java.exe" : "java";
+    const values = [
+        process.env.JAVA_HOME
+            ? join(process.env.JAVA_HOME, "bin", executable)
+            : undefined,
+        commandExists("java") ? "java" : undefined,
+        platform() === "win32"
+            ? join(process.env.LOCALAPPDATA ?? "", "Programs", "Android", "Android Studio", "jbr", "bin", executable)
+            : undefined,
+        platform() === "win32"
+            ? join(process.env.PROGRAMFILES ?? "", "Android", "Android Studio", "jbr", "bin", executable)
+            : undefined,
+        platform() === "win32"
+            ? join(process.env.PROGRAMFILES ?? "", "Java", "jdk-17", "bin", executable)
+            : undefined,
+        platform() === "win32"
+            ? join(process.env.PROGRAMFILES ?? "", "Eclipse Adoptium", "jdk-17", "bin", executable)
+            : undefined,
+        platform() === "darwin"
+            ? "/Applications/Android Studio.app/Contents/jbr/Contents/Home/bin/java"
+            : undefined,
+        platform() === "darwin"
+            ? "/Applications/Android Studio.app/Contents/jre/Contents/Home/bin/java"
+            : undefined,
+        platform() === "linux" ? "/opt/android-studio/jbr/bin/java" : undefined,
+        platform() === "linux"
+            ? join(homedir(), "android-studio", "jbr", "bin", "java")
+            : undefined,
+    ];
+    return values.filter((value) => Boolean(value));
+}
+function check(name, status, value, fix) {
+    return { name, status, ok: status !== "fail", value, fix };
+}
+export async function inspectAndroidToolchain(root) {
+    const inputs = readAndroidInputs(root);
+    const checks = [];
+    const wrapper = join(root, "android", platform() === "win32" ? "gradlew.bat" : "gradlew");
+    const wrapperExists = existsSync(wrapper) &&
+        (platform() === "win32" || executableExists(wrapper));
+    checks.push(check("gradle-wrapper", wrapperExists ? "pass" : "fail", wrapperExists
+        ? inputs.gradleVersion
+            ? `Gradle ${inputs.gradleVersion}`
+            : "found · version unknown"
+        : "missing", wrapperExists
+        ? undefined
+        : "lynxship android host init --application-id com.example.myapp"));
+    const minimumGradle = requiredGradleForAgp(inputs.agpVersion);
+    const gradleCompatible = Boolean(inputs.gradleVersion &&
+        minimumGradle &&
+        compareVersions(inputs.gradleVersion, minimumGradle) >= 0);
+    const gradleStatus = !inputs.gradleVersion || !inputs.agpVersion
+        ? "warn"
+        : gradleCompatible
+            ? "pass"
+            : "fail";
+    checks.push(check("agp-gradle-compatibility", gradleStatus, inputs.agpVersion && inputs.gradleVersion
+        ? `AGP ${inputs.agpVersion} · Gradle ${inputs.gradleVersion}${minimumGradle ? ` · minimum Gradle ${minimumGradle}` : ""}`
+        : "AGP or wrapper version not detected", gradleStatus === "fail" && minimumGradle
+        ? `Update the project wrapper to Gradle ${minimumGradle}; do not use a global Gradle installation`
+        : undefined));
+    const requiredJava = requiredJavaForAgp(inputs.agpVersion);
+    let detectedJava;
+    let javaPath;
+    for (const candidate of javaCandidates()) {
+        const version = await javaVersion(candidate, root);
+        if (version !== undefined) {
+            detectedJava = version;
+            javaPath = candidate;
+            break;
+        }
+    }
+    const javaStatus = detectedJava === undefined
+        ? "fail"
+        : detectedJava >= requiredJava
+            ? "pass"
+            : "fail";
+    checks.push(check("java", javaStatus, detectedJava === undefined
+        ? "missing"
+        : `JDK ${detectedJava}${javaPath === "java" ? " · PATH" : ""}`, javaStatus === "fail"
+        ? `Install/configure JDK ${requiredJava} and set JAVA_HOME, then run lynxship doctor --platform android`
+        : undefined));
+    const sdkPath = sdkCandidates().find((candidate) => existsSync(candidate));
+    const compileSdk = inputs.compileSdk;
+    const buildTools = inputs.buildToolsVersion;
+    const platformPackage = compileSdk
+        ? `platforms;android-${compileSdk}`
+        : undefined;
+    const buildToolsPackage = buildTools
+        ? `build-tools;${buildTools}`
+        : undefined;
+    const missingPackages = [
+        platformPackage &&
+            sdkPath &&
+            !existsSync(join(sdkPath, "platforms", `android-${compileSdk}`))
+            ? platformPackage
+            : undefined,
+        buildTools &&
+            sdkPath &&
+            !existsSync(join(sdkPath, "build-tools", buildTools))
+            ? buildToolsPackage
+            : undefined,
+    ].filter((value) => Boolean(value));
+    const sdkStatus = !sdkPath
+        ? "fail"
+        : missingPackages.length
+            ? "fail"
+            : "pass";
+    checks.push(check("android-sdk", sdkStatus, !sdkPath
+        ? "missing · set ANDROID_HOME or ANDROID_SDK_ROOT"
+        : missingPackages.length
+            ? `missing: ${missingPackages.join(", ")}`
+            : sdkPath, sdkStatus === "fail"
+        ? "Install Android Studio or the Android command-line tools, then run lynxship doctor --platform android --fix"
+        : undefined));
+    const manager = sdkPath ? sdkManagerPath(sdkPath) : undefined;
+    checks.push(check("sdkmanager", manager ? "pass" : sdkPath ? "warn" : "fail", manager
+        ? "available"
+        : sdkPath
+            ? "missing · use Android Studio SDK Manager"
+            : "unavailable until Android SDK is installed", manager && missingPackages.length
+        ? `sdkmanager ${missingPackages.map((value) => `"${value}"`).join(" ")}`
+        : undefined));
+    const adb = sdkPath ? sdkExecutable(sdkPath, "adb") : undefined;
+    checks.push(check("adb", adb || commandExists("adb") ? "pass" : "warn", adb || commandExists("adb")
+        ? "Android Platform-Tools available"
+        : "missing · required for lynxship run/logs", !adb && !commandExists("adb")
+        ? "Install Android SDK Platform-Tools, then run adb devices"
+        : undefined));
+    const apksigner = sdkPath ? sdkExecutable(sdkPath, "apksigner") : undefined;
+    checks.push(check("apksigner", apksigner || commandExists("apksigner") ? "pass" : "warn", apksigner || commandExists("apksigner")
+        ? "Android Build Tools available"
+        : "missing · required to verify APK signatures", !apksigner && !commandExists("apksigner")
+        ? "Install Android SDK Build Tools, then run lynxship doctor --platform android"
+        : undefined));
+    checks.push(check("android-sdk-licenses", sdkPath && existsSync(join(sdkPath, "licenses")) ? "pass" : "warn", sdkPath && existsSync(join(sdkPath, "licenses"))
+        ? "license directory found"
+        : "not verified", sdkPath ? "sdkmanager --licenses" : undefined));
+    const failures = checks.filter((item) => item.status === "fail");
+    return {
+        ok: failures.length === 0,
+        checks,
+        sdkPath,
+        compileSdk,
+        buildToolsVersion: buildTools,
+        agpVersion: inputs.agpVersion,
+        gradleVersion: inputs.gradleVersion,
+        javaVersion: detectedJava,
+        sdkPackages: missingPackages,
+    };
+}
+export async function fixAndroidToolchain(root, report, confirm, onOutput) {
+    const managerCheck = report.checks.find((item) => item.name === "sdkmanager");
+    const manager = report.sdkPath ? sdkManagerPath(report.sdkPath) : undefined;
+    if (!manager || !report.sdkPackages.length)
+        return;
+    const packages = report.sdkPackages;
+    if (!(await confirm(`Install missing Android SDK packages (${packages.join(", ")}) now?`)))
+        return;
+    await runProcess(manager, packages, { cwd: root, onOutput });
+    if (managerCheck && !(await confirm("Accept Android SDK licenses now?")))
+        return;
+    await runProcess(manager, ["--licenses"], { cwd: root, onOutput });
+}
+export function formatAndroidToolchainFailure(report) {
+    return report.checks
+        .filter((item) => item.status === "fail")
+        .map((item) => `${item.name}: ${item.value}${item.fix ? ` · fix: ${item.fix}` : ""}`)
+        .join("; ");
+}

package/dist/artifact-build.d.ts

@@ -0,0 +1,17 @@
+import { type BuildJob, type Platform } from "@lynxship/contracts";
+import { type NativeArtifactExtension } from "./artifact-name.js";
+export interface ArtifactBuildOptions {
+    root: string;
+    job: BuildJob;
+    platform: Platform;
+    artifactPath: string;
+    extension: NativeArtifactExtension;
+    contentType: string;
+    uploadArtifacts: boolean;
+    verificationMessage: string;
+    quiet?: boolean;
+    onEvent?: (message: string) => void;
+    onProgress?: (value?: number, label?: string) => void;
+}
+export declare function publishBuiltArtifact(options: ArtifactBuildOptions): Promise<BuildJob>;
+//# sourceMappingURL=artifact-build.d.ts.map

package/dist/artifact-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-build.d.ts","sourceRoot":"","sources":["../src/artifact-build.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAG5B,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,QAAQ,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CA0EnB"}

package/dist/artifact-build.js

@@ -0,0 +1,56 @@
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { transitionBuild } from "@lynxship/build-orchestrator";
+import { assert, sha256, } from "@lynxship/contracts";
+import { nativeArtifactName, } from "./artifact-name.js";
+import { loadR2, uploadR2Artifact } from "./r2.js";
+export async function publishBuiltArtifact(options) {
+    const { root, job, platform, artifactPath, extension, contentType, uploadArtifacts, onEvent, onProgress, } = options;
+    const artifactName = nativeArtifactName(extension);
+    const artifactDirectory = join(root, ".lynxship", "artifacts");
+    const artifactPathCopy = join(artifactDirectory, artifactName);
+    await mkdir(artifactDirectory, { recursive: true });
+    await copyFile(artifactPath, artifactPathCopy);
+    const content = await readFile(artifactPathCopy);
+    const hash = sha256(content);
+    job.attempts += 1;
+    transitionBuild(job, "signing", options.verificationMessage);
+    transitionBuild(job, "uploading_artifacts", `${platform} artifact collected`);
+    const step = (message, value) => {
+        onEvent?.(message);
+        onProgress?.(value, message);
+    };
+    if (!uploadArtifacts) {
+        step("Artifact collected locally; R2 upload skipped", 100);
+        job.artifact = {
+            name: artifactName,
+            hash,
+            path: artifactPathCopy,
+            size: content.length,
+            contentType,
+        };
+    }
+    else {
+        await loadR2(root);
+        step("Uploading artifact to Cloudflare R2…", 80);
+        const uploaded = await uploadR2Artifact(root, job.projectId, job.id, artifactPathCopy, contentType, undefined, {
+            onProgress: (uploadedBytes, totalBytes) => {
+                const transfer = totalBytes === 0 ? 1 : uploadedBytes / totalBytes;
+                onProgress?.(80 + transfer * 19, `Uploading artifact to Cloudflare R2… ${Math.round(transfer * 10000) / 100}%`);
+            },
+        });
+        assert(uploaded.hash === hash, "BUILD_ARTIFACT_HASH", "R2 artifact hash mismatch");
+        job.artifact = {
+            name: artifactName,
+            hash,
+            path: artifactPathCopy,
+            key: uploaded.key,
+            size: uploaded.size,
+            contentType: uploaded.contentType,
+            url: uploaded.url,
+            expiresAt: uploaded.expiresAt,
+        };
+    }
+    step(`Artifact ready: ${artifactName}`, 100);
+    return transitionBuild(job, "success", `real ${platform} artifact created`);
+}