spawndroid 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spawndroid
+
+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,108 @@
-# Temporary Holding Version
+# spawndroid
 
-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.
+Run Android tests on hosted devices from any CI.
+
+Upload a build, boot a real device, run your test command against it, and keep
+the result along with the JUnit report, logcat and screen recording.
+
+## Quick start
+
+```bash
+npx spawndroid init                                  # detect the project, write the spec + workflow
+export SPAWNDROID_API_KEY=spawn_live_…               # API & CI/CD → API keys, upload scope
+npx spawndroid check                                 # name the walls before the first run
+npx spawndroid run                                   # upload → boot → test → report → teardown
+```
+
+`init` reads the project (Gradle, Maven, WebdriverIO, pytest), prints what it
+inferred, and writes `spawndroid.yaml` plus
+`.github/workflows/spawndroid.yml`. It asks only for what it cannot infer.
+Every flag is overridable for non-interactive setups:
+
+```bash
+npx spawndroid init --app app/build/outputs/apk/debug/app-debug.apk \
+  --command "mvn test" --report target/surefire-reports/TEST-com.example.CheckoutTest.xml
+```
+
+## The spec
+
+```yaml
+version: 1
+app: app/build/outputs/apk/debug/app-debug.apk   # APK path, or an uploaded app slug
+command: [mvn, test]                             # string is split; list is exact argv
+profile: android-14-phone                        # optional device profile
+report: target/surefire-reports/TEST-com.example.CheckoutTest.xml
+timeout: 600                                     # seconds to wait for the device
+fixtures:                                        # optional files pushed after readiness
+  - local: test/fixtures/sample.jpg
+    device: /sdcard/Pictures                     # absolute directory under /sdcard
+```
+
+Unknown keys are errors — a misspelled `timeout` must not silently fall back
+to the default.
+
+## Commands
+
+```bash
+spawndroid init     [--app <apk>] [--command <cmd>] [--report <xml>] [--profile <id>] [--force]
+spawndroid check    [--config <path>]
+spawndroid run      [--config <path>] [--profile <id>] [--timeout <s>] [-- <command…>]
+spawndroid upload   <app.apk> [--json]
+spawndroid start    --app <slug> [--profile <id>] [--json]
+spawndroid wait     <sessionId> [--timeout <s>] [--json]
+spawndroid report   <sessionId> --result passed|failed
+```
+
+## What `run` does
+
+1. Uploads the APK (or reuses the slug), creating a session with an
+   `Idempotency-Key`.
+2. Retries a *capacity* `429` up to 3 attempts over ~90 s; plan limits
+   (`PLAN_RUNNER_LIMIT`, `PLAN_DEVICE_MINUTES_EXHAUSTED`) fail immediately.
+3. Waits up to `timeout` for the device, then pushes fixtures.
+4. Runs `command` locally on the runner with the session in its environment.
+5. Posts the JUnit report, tears the device down, and prints the run URL.
+
+Exported to the command:
+
+| Variable                 | Meaning                   |
+| ------------------------ | ------------------------- |
+| `SPAWNDROID_WD_URL`      | W3C WebDriver endpoint    |
+| `SPAWNDROID_UDID`        | device serial             |
+| `SPAWNDROID_APP_PACKAGE` | installed app package     |
+| `SPAWNDROID_APP`         | app slug                  |
+| `SPAWNDROID_SESSION_ID`  | session id                |
+
+The build is installed before your command runs — never set `appium:app`.
+
+Exit codes: `0` tests passed, `1` tests failed, `2` infrastructure or setup
+failed. CI retry logic can key off that instead of re-running real failures.
+
+## GitHub Actions
+
+```yaml
+- uses: spawndroid/cli@v0.1.0
+  with:
+    api-key: ${{ secrets.SPAWNDROID_API_KEY }}
+```
+
+The Action installs the CLI, runs `spawndroid run --config spawndroid.yaml`,
+and exposes `session-id`, `run-url` and `result` as step outputs.
+
+## Limits
+
+- Appium / WebDriver suites only: sessions expose a WebDriver endpoint, not adb.
+- One APK per session; the APK is installed before the command starts.
+- Per-run sessions. The stable hub is documented separately at
+  [docs.spawndroid.io](https://docs.spawndroid.io/docs/ci-tests).
+- Hobby: 15-minute sessions, 7-day build expiry, live logcat only.
+
+## Examples
+
+| Example                                               | Language   | Runner              |
+| ----------------------------------------------------- | ---------- | ------------------- |
+| [webdriverio-android](./examples/webdriverio-android) | JavaScript | WebdriverIO + Mocha |
+| [python-pytest](./examples/python-pytest)             | Python     | pytest              |
+| [java-testng](./examples/java-testng)                 | Java       | TestNG + Maven      |
+
+MIT licensed.

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "spawndroid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Run Android tests on hosted devices from any CI.",
+  "type": "module",
+  "bin": {
+    "spawndroid": "src/spawndroid.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/spawndroid.test.mjs test/config.test.mjs test/run.test.mjs test/check.test.mjs"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spawndroid/cli.git"
+  },
+  "homepage": "https://spawndroid.io",
+  "bugs": {
+    "url": "https://github.com/spawndroid/cli/issues"
+  },
+  "keywords": [
+    "android",
+    "appium",
+    "webdriver",
+    "emulator",
+    "testing",
+    "ci"
+  ],
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,130 @@
+/**
+ * HTTP client for the Spawndroid console API.
+ *
+ * Thin on purpose: every method maps to one documented endpoint, and the only
+ * parsing it does is of problem+json error bodies so callers can branch on the
+ * machine-readable `code` instead of the message.
+ */
+
+import { readFile } from "node:fs/promises"
+import { basename } from "node:path"
+import { randomUUID } from "node:crypto"
+
+export class ApiError extends Error {
+  constructor(status, body, path) {
+    const detail =
+      (body && (body.detail || body.error || body.title)) || `HTTP ${status}`
+    super(`${status} ${detail}`)
+    this.name = "ApiError"
+    this.status = status
+    this.code = body?.code ?? null
+    this.legacyCode = body?.legacyCode ?? null
+    this.body = body ?? null
+    this.path = path
+  }
+}
+
+export function createApi({ baseUrl, apiKey, fetchImpl = globalThis.fetch }) {
+  const root = baseUrl.replace(/\/$/, "")
+
+  async function request(path, init = {}) {
+    const headers = { Accept: "application/json", ...(init.headers ?? {}) }
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+    const response = await fetchImpl(`${root}${path}`, { ...init, headers })
+    if (response.status === 204) return null
+    const body = await response.json().catch(() => null)
+    if (!response.ok) throw new ApiError(response.status, body, path)
+    return body
+  }
+
+  return {
+    baseUrl: root,
+
+    /**
+     * Validate the key without spending anything: an unknown session is a 404
+     * for a valid key and a 401/403 for a bad or under-scoped one.
+     */
+    async probe() {
+      try {
+        await request(`/api/v1/sessions/probe-${randomUUID()}`)
+        return { ok: true }
+      } catch (error) {
+        if (error instanceof ApiError && error.status === 404) return { ok: true }
+        if (
+          error instanceof ApiError &&
+          (error.status === 401 || error.status === 403)
+        ) {
+          return { ok: false, error }
+        }
+        throw error
+      }
+    },
+
+    async uploadApk(file) {
+      const bytes = await readFile(file)
+      const form = new FormData()
+      form.append("file", new Blob([bytes]), basename(file))
+      const body = await request("/api/apps", { method: "POST", body: form })
+      return body?.app
+    },
+
+    async createSession(fields, idempotencyKey) {
+      return request("/api/v1/sessions", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Idempotency-Key": idempotencyKey,
+        },
+        body: JSON.stringify(fields),
+      })
+    },
+
+    async getSession(id) {
+      return request(`/api/v1/sessions/${encodeURIComponent(id)}`)
+    },
+
+    async endSession(id, result) {
+      return request(`/api/v1/sessions/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ result }),
+      })
+    },
+
+    async presignFile(id, { filename, path, size }) {
+      return request(
+        `/api/v1/sessions/${encodeURIComponent(id)}/files/presign`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ filename, path, size }),
+        }
+      )
+    },
+
+    async putFile(url, bytes, contentType) {
+      const response = await fetchImpl(url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType ?? "application/octet-stream" },
+        body: bytes,
+      })
+      if (!response.ok) throw new ApiError(response.status, null, "presigned PUT")
+    },
+
+    async commitFile(id, fields) {
+      return request(`/api/v1/sessions/${encodeURIComponent(id)}/files`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(fields),
+      })
+    },
+
+    async postReport(id, xml) {
+      return request(`/api/v1/sessions/${encodeURIComponent(id)}/report`, {
+        method: "POST",
+        headers: { "Content-Type": "application/xml" },
+        body: xml,
+      })
+    },
+  }
+}

package/src/check.mjs

@@ -0,0 +1,93 @@
+/**
+ * `spawndroid check` — name every wall before the first run instead of
+ * returning a 403 halfway through CI.
+ */
+
+import { accessSync, constants, statSync } from "node:fs"
+import { resolve } from "node:path"
+import { spawnSync } from "node:child_process"
+
+import { DEVICE_FILE_MAX_BYTES } from "./config.mjs"
+
+const HOST_BOOT_AND_INSTALL_SECONDS = 420
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+function isExecutableOnPath(command) {
+  if (command.includes("/")) {
+    try {
+      accessSync(command, constants.X_OK)
+      return true
+    } catch {
+      return false
+    }
+  }
+  const probe = process.platform === "win32" ? "where" : "which"
+  return spawnSync(probe, [command], { stdio: "ignore", encoding: "utf8" }).status === 0
+}
+
+export async function collectChecks({ spec, specDir, api }) {
+  const problems = []
+  const warnings = []
+
+  try {
+    const probe = await api.probe()
+    if (!probe.ok) {
+      problems.push(
+        "the API key was rejected (401/403) — create a key with the upload scope in API & CI/CD → API keys"
+      )
+    }
+  } catch (error) {
+    problems.push(`could not reach ${api.baseUrl}: ${error.message}`)
+  }
+
+  const appPath = resolve(specDir, spec.app)
+  const looksLikePath = /\.apk$/i.test(spec.app) || spec.app.includes("/")
+  if (isFile(appPath)) {
+    if (!/\.apk$/i.test(appPath)) warnings.push(`${spec.app} does not end in .apk — only APKs install`)
+  } else if (looksLikePath) {
+    problems.push(`APK not found: ${appPath} — build the app before running tests`)
+  }
+
+  for (const fixture of spec.fixtures) {
+    const local = resolve(specDir, fixture.local)
+    if (!isFile(local)) {
+      problems.push(`fixture not found: ${fixture.local}`)
+      continue
+    }
+    const size = statSync(local).size
+    if (size > DEVICE_FILE_MAX_BYTES) {
+      problems.push(`fixture ${fixture.local} is larger than the 32 MB limit`)
+    }
+  }
+
+  if (spec.report && spec.report.includes("*")) {
+    problems.push(`"report" must be a single JUnit XML file, not a glob (${spec.report})`)
+  }
+
+  if (spec.timeout < HOST_BOOT_AND_INSTALL_SECONDS) {
+    warnings.push(
+      `timeout ${spec.timeout}s is below the host's ~${HOST_BOOT_AND_INSTALL_SECONDS}s boot + install ceiling`
+    )
+  }
+
+  if (!isExecutableOnPath(spec.command[0])) {
+    warnings.push(`test command "${spec.command[0]}" was not found on PATH`)
+  }
+
+  return { problems, warnings }
+}
+
+export function planNotes() {
+  return [
+    "limits: sessions stop at your plan's cap (Hobby: 15 minutes of device time);",
+    "        Hobby builds expire 7 days after upload; Hobby logcat is live-only.",
+    "        Logcat, video and JUnit history are kept for your plan's retention window.",
+  ]
+}