@androperator/emulator 0.1.1 → 0.2.0

package/.agents/skills/create-android-emulator/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: create-android-emulator
+description: Create or recreate an Android development emulator with the @androperator/emulator library or CLI, choose an installed phone image and profile, configure practical storage, and verify boot and guest capacity. Use for local AVD provisioning, including insufficient storage during repeated APK installs.
+---
+
+# Create Android Emulator
+
+Use `@androperator/emulator` for AVD lifecycle operations. Prefer its JSON CLI for
+interactive provisioning; use the library exports when integrating into code.
+This skill creates a device, not an Android UI automation workflow.
+
+## Discover and choose
+
+Find an installed `androperator-emulator` and check `--version` and `--help`.
+In this library's source checkout, use `npm ci` if dependencies are missing,
+`npm run build`, then `node dist/cli.js` as the CLI. Outside the checkout, use
+`npm install -g @androperator/emulator` when installation is within the request.
+Requires Node.js 24+, Android SDK tools and their Java runtime. Missing SDK or
+Java prerequisites should be reported before provisioning; the package does not
+install the SDK itself.
+
+CLI tool overrides are `ADB_PATH`, `EMULATOR_PATH`, `SDKMANAGER_PATH` and
+`AVDMANAGER_PATH`. Otherwise discovery checks `ANDROID_HOME`, `ANDROID_SDK_ROOT`,
+standard macOS/Linux SDK roots, then PATH. Use the same resolved tools for the SDK
+and adb commands below. Keep `ANDROID_AVD_HOME` consistent across all commands
+if set; other custom Android home conventions are not supported by the library.
+
+Inspect before mutating:
+
+```sh
+androperator-emulator list
+androperator-emulator status
+"$sdkmanager" --list_installed
+"$avdmanager" list device -c
+```
+
+Here `$sdkmanager`, `$avdmanager` and later `$adb` stand for the resolved executable
+paths. The CLI has no image/profile enumeration command, so use SDK tools for
+those read-only queries.
+
+Respect requested API, image, profile, storage and name. Otherwise prefer:
+
+- Name: `Android_Dev_API_<api>`.
+- Data capacity: `24G`, for repeated development APK installs.
+- Image: highest installed stable API with a Google Play phone image matching
+  the host architecture (`arm64-v8a` on ARM, `x86_64` on x86).
+- Profile: newest installed Pixel phone profile compatible with that image.
+
+Use actual package and profile IDs from discovery, not guessed IDs. If no suitable
+Google Play image is installed, choose an installed compatible Google APIs phone
+image when Play Store access is unnecessary. If an image must be downloaded,
+query `"$sdkmanager" --list` and choose an available compatible package. Creation
+installs a missing selected image. `--accept-licenses` accepts **all outstanding
+SDK licenses**, so use it only with explicit authorization for that acceptance.
+
+## Create and boot
+
+Set `$name`, `$image` and `$profile` to the selected values. For a fresh device:
+
+```sh
+androperator-emulator create "$name" \
+  --image "$image" --profile "$profile" --storage-size 24G
+androperator-emulator inspect "$name"
+androperator-emulator start "$name" --headless
+```
+
+Substitute the requested capacity for `24G`. Omit `--headless` for a visible
+emulator. Every CLI invocation returns one JSON envelope; check exit status and
+`ok` before using `data`. Stop on failure, inspect the error and relevant state,
+and retry only after addressing its cause. A failed start can leave an emulator
+running; check `status` before launching again.
+
+Existing names are refused. Reuse a suitable existing device or choose a fresh
+name. Use `create --replace` only when the user has authorized discarding that
+AVD's data. Before replacement, stop the target if running, then poll `status`
+with a bounded timeout to confirm its serial disappears. `stop` only requests
+shutdown. Replacement/deletion refuse running AVDs and fail closed on uncertain
+ADB state; resolve that state instead of bypassing the checks. Serialize lifecycle
+operations for the same AVD.
+
+`storage` changes configured capacity only; it does not resize existing userdata.
+Prefer a fresh AVD for a capacity change. Creation does not configure an SD card,
+force qcow2 allocation, or disable snapshot saving. Do not promise the reference
+AVD workflow's sparse disk or snapshot-free behavior. CLI launch disables snapshot
+loading. If snapshot saving must be disabled, use library `startAvd` with
+`["-no-snapshot-save"]`, then both readiness waits described below.
+
+## Verify and report
+
+Successful CLI `start` returns `data.serial` and `booted: true` after registration
+and both boot properties pass. Use that returned serial, never assume port 5554.
+If reusing an already-running target, resolve its serial by AVD name in `status`
+and use `wait <serial>` to verify readiness.
+
+```sh
+"$adb" -s "$serial" shell df -h /data
+```
+
+Check actual total and free guest capacity against the requested size; `inspect`
+reports device metadata, not storage capacity. If an APK is supplied for a smoke
+test, install it on this serial with `"$adb" -s "$serial" install -r "$apk"`.
+If host disk usage matters, obtain the actual config path with library
+`getAvdConfigPath(name)` (AVD locator files may redirect it), and measure its
+parent directory with `du -sh`. Inspect existing userdata with SDK `qemu-img info`
+only when that tool and file exist; report measured allocation rather than
+assuming qcow2 or a small physical size.
+
+Leave a requested development device running. Stop a device launched only for
+verification when the requested outcome does not require it running; confirm
+shutdown before reporting it stopped. Do not delete the created AVD as cleanup.
+Report name, API/image/profile, configured capacity, measured `/data` total/free,
+serial and boot state, APK result if tested, and the normal launch command.
+Distinguish unavailable measurements from verified results.
+
+## Library integration
+
+The root export supplies `getDefaultRuntimeConfig`, `createAvd`,
+`inspectConfiguredAvd`, `listRunningEmulators`, `startAvd`,
+`waitForEmulatorRegistration`, `waitForBootCompletion`, `stopAvd`, and
+`getAvdConfigPath`. Use the same selections and replacement/license boundaries.
+
+```js
+import {
+  getDefaultRuntimeConfig, createAvd, startAvd,
+  waitForEmulatorRegistration, waitForBootCompletion,
+} from '@androperator/emulator';
+
+const config = getDefaultRuntimeConfig();
+await createAvd(config, {
+  name, systemImage: image, deviceProfile: profile, dataPartitionSize: '24G',
+});
+await startAvd(config, name, ['-no-window', '-no-audio']);
+const serial = await waitForEmulatorRegistration(config, name);
+await waitForBootCompletion(config, serial);
+```
+
+`startAvd` confirms spawn only; both waits are required to confirm readiness.

package/.agents/skills/create-android-emulator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Create Android Emulator"
+  short_description: "Create and verify an Android development emulator"
+  default_prompt: "Use $create-android-emulator to create an Android development emulator with @androperator/emulator."

package/README.md

@@ -12,7 +12,7 @@ npm ci
 npm run build
 npm test
 npm pack
-npm install -g ./androperator-emulator-0.1.1.tgz
+npm install -g ./androperator-emulator-0.2.0.tgz
 androperator-emulator --version
 ```
 
@@ -22,9 +22,27 @@ dependencies.
 The executable remains `androperator-emulator`. See [provenance](docs/provenance.md)
 for source history and [plan](docs/plan.md) for follow-on work.
 
+## Homebrew installation
+
+```sh
+brew install androperator/tap/emulator
+brew upgrade androperator/tap/emulator
+```
+
+The executable remains `androperator-emulator`. Homebrew manages Node and uses
+this package's npm release archive. Android SDK tools and Java are configured
+separately. When moving from a global npm installation, first remove it with
+`npm uninstall -g @androperator/emulator` to avoid executable conflicts.
+New versions become available after automatic tap validation; Homebrew can
+hold newly published dependencies for 24 hours. Do not upgrade a Homebrew
+installation using npm.
+
 ## CLI
 
 ```sh
+androperator-emulator profiles
+androperator-emulator images
+androperator-emulator images --installed
 androperator-emulator list
 androperator-emulator inspect My_AVD
 androperator-emulator status
@@ -52,6 +70,37 @@ The `--version` response identifies the package and machine protocol without SDK
 access. ADBuddy can probe this command after finding the separately installed
 executable; native discovery and installation UI are separate work.
 
+### Creation catalogs
+
+`profiles` returns `{profiles: [{id, name, manufacturer, tag}]}` from the SDK's
+hardware definitions. Pass the stable `id` to `create --profile`; the SDK's
+numeric row index is not returned. Missing manufacturer or tag values are null.
+
+`images` queries installed and available SDK packages and returns
+`{images: [{id, platform, apiLevel, tag, abi, description, installed,
+installedVersion, availableVersion}]}`. `images --installed` queries only local
+packages, so it does not require fetching the remote catalog. Pass `id` directly
+to `create --image`. IDs use semicolons regardless of the SDK output format.
+Versions remain strings; an absent installed or available version is null.
+`platform` preserves the complete platform identifier, including minor versions
+or preview names. `apiLevel` is the numeric major API for numeric platforms and
+null for codenames. Results are sorted by ID, with each image appearing once.
+
+These are catalogs, not compatibility recommendations. Callers must select a
+suitable image/profile/host combination; do not assume every listed image runs
+on this Mac. Remote queries can require network access and may take longer than
+local queries. Tool or unrecognized-format failures return
+`ANDROID_CATALOG_QUERY_FAILED`; empty recognized catalogs return empty arrays.
+The legacy SDK table and the Android CLI shim's slash-separated table are supported.
+
+Library consumers can call `listHardwareProfiles(config)` and
+`listSystemImages(config, {installedOnly: true})`; omitting the latter option
+includes available images. Neither command starts ADB or accepts licenses.
+`--version` now includes `capabilities: ["catalog.profiles", "catalog.images"]`
+in its data object. Consumers should treat missing capabilities as unsupported;
+the JSON envelope remains protocol version 1. Earlier published versions lack
+these catalog commands.
+
 Create requires explicit image, hardware profile and storage capacity. Existing
 AVDs are refused unless `--replace` is supplied, which discards existing data.
 Replacement and deletion refuse running AVDs and fail closed if ADB discovery
@@ -75,6 +124,31 @@ It does not resize existing userdata, guarantee free space, or impose a host dis
 quota. Use a fresh AVD when changing capacity. Dynamic qcow2 allocation and
 snapshot-free storage are follow-on capabilities.
 
+## Agent skill
+
+[Create Android Emulator](.agents/skills/create-android-emulator/SKILL.md) guides an
+agent through image/profile discovery, creation with practical development
+storage (24G by default), boot verification and actual guest storage checks using
+this package. Invoke it as `$create-android-emulator`.
+
+The source lives in `.agents/skills/create-android-emulator/`, the repository
+skill location supported by Codex. The same folder is included in the npm
+archive; the release-only skill is excluded. Installing the npm package does
+not automatically register its skill with an agent.
+
+To use it in another project, copy the entire skill folder from
+`node_modules/@androperator/emulator/.agents/skills/create-android-emulator/`
+into that project's `.agents/skills/`. For a global npm installation, the source
+is under `$(npm root -g)/@androperator/emulator/.agents/skills/`. For personal
+Codex use across projects, copy it into `~/.agents/skills/` instead. Copies should
+be refreshed when upgrading the library.
+
+Each skill needs a `SKILL.md` with name/description frontmatter and instructions;
+`agents/openai.yaml` supplies optional UI metadata. Repository skills work well
+for checked-in workflows. Plugins provide an installation unit for broader skill
+distribution and optional connectors. See the official
+[skill discovery and distribution guidance](https://learn.chatgpt.com/docs/build-skills).
+
 ## Library
 
 ```js

package/dist/catalog.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeConfig } from "./runtimeConfig.js";
+export interface HardwareProfile {
+    /** Stable identifier accepted by create --profile; never the catalog row number. */
+    id: string;
+    name: string;
+    manufacturer: string | null;
+    tag: string | null;
+}
+export interface SystemImage {
+    /** Canonical semicolon-delimited identifier accepted by create --image. */
+    id: string;
+    platform: string;
+    apiLevel: number | null;
+    tag: string;
+    abi: string;
+    description: string;
+    installed: boolean;
+    installedVersion: string | null;
+    availableVersion: string | null;
+}
+export declare function parseHardwareProfiles(output: string): HardwareProfile[];
+export declare function parseSystemImages(output: string): SystemImage[];
+export declare function listHardwareProfiles(config: RuntimeConfig): Promise<HardwareProfile[]>;
+export declare function listSystemImages(config: RuntimeConfig, options?: {
+    installedOnly?: boolean;
+}): Promise<SystemImage[]>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -0,0 +1,98 @@
+import { runAndroidSdkTool } from "./hostToolClient.js";
+function catalogError(message) {
+    throw { code: "ANDROID_CATALOG_QUERY_FAILED", message };
+}
+export function parseHardwareProfiles(output) {
+    const profiles = [];
+    let profile;
+    function finish() {
+        if (!profile)
+            return;
+        if (!profile.name)
+            catalogError(`Missing name for hardware profile ${profile.id}`);
+        profiles.push(profile);
+    }
+    for (const line of output.split(/\r?\n/)) {
+        const id = /^\s*id:\s*\d+\s+or\s+"([^"]+)"\s*$/.exec(line);
+        if (id) {
+            finish();
+            profile = { id: id[1], name: "", manufacturer: null, tag: null };
+        }
+        else if (/^\s*id:/.test(line)) {
+            catalogError(`Unrecognized hardware profile identifier: ${line.trim()}`);
+        }
+        else if (profile) {
+            const field = /^\s*(Name|OEM|Tag)\s*:\s*(.*?)\s*$/.exec(line);
+            if (field?.[1] === "Name")
+                profile.name = field[2];
+            if (field?.[1] === "OEM")
+                profile.manufacturer = field[2] || null;
+            if (field?.[1] === "Tag")
+                profile.tag = field[2] || null;
+        }
+    }
+    finish();
+    if (!profiles.length && !output.includes("Available devices definitions:")) {
+        catalogError("Unrecognized hardware profile catalog; expected avdmanager list device output");
+    }
+    return profiles.sort((a, b) => a.id.localeCompare(b.id));
+}
+export function parseSystemImages(output) {
+    const images = new Map();
+    let section;
+    let recognized = false;
+    for (const line of output.split(/\r?\n/)) {
+        const heading = /^\s*(Installed packages|Available Packages|Available packages|Available Updates|Available updates):\s*$/.exec(line);
+        if (heading) {
+            recognized = true;
+            section = heading[1] === "Installed packages" ? "installed"
+                : heading[1].toLowerCase() === "available packages" ? "available" : undefined;
+            continue;
+        }
+        if (!/^\s*system-images[;/]/.test(line))
+            continue;
+        // Update tables have a different schema; their rows are already represented
+        // by the installed and available package sections.
+        if (!section)
+            continue;
+        const columns = line.includes("|") ? line.split("|").map((column) => column.trim())
+            : line.trim().split(/\s{2,}/);
+        const [rawId, version, description] = columns;
+        const id = rawId.replaceAll("/", ";");
+        const parts = /^system-images;(android-[^;\s]+);([^;\s]+);([^;\s]+)$/.exec(id);
+        if (!parts || !version || !description)
+            catalogError(`Unrecognized system image row: ${line.trim()}`);
+        const [, platform, tag, abi] = parts;
+        const api = /^android-(\d+)(?:\.\d+)*(?:-ext\d+)?$/.exec(platform);
+        const image = images.get(id) ?? {
+            id, platform, apiLevel: api ? Number(api[1]) : null, tag, abi, description,
+            installed: false, installedVersion: null, availableVersion: null,
+        };
+        if (section === "installed") {
+            image.installed = true;
+            image.installedVersion = version;
+        }
+        else {
+            image.availableVersion = version;
+            image.description = description;
+        }
+        images.set(id, image);
+    }
+    if (!recognized)
+        catalogError("Unrecognized system image catalog; expected sdkmanager package sections");
+    return [...images.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function listHardwareProfiles(config) {
+    const result = await runAndroidSdkTool(config, "avdmanager", ["list", "device"], { timeoutMs: 30_000 });
+    if (result.code !== 0 || result.error)
+        catalogError(result.stderr || result.error?.message || "Could not list hardware profiles");
+    return parseHardwareProfiles(result.stdout);
+}
+export async function listSystemImages(config, options = {}) {
+    const result = await runAndroidSdkTool(config, "sdkmanager", [options.installedOnly ? "--list_installed" : "--list"], { timeoutMs: 120_000 });
+    if (result.code !== 0 || result.error)
+        catalogError(result.stderr || result.error?.message || "Could not list system images");
+    const images = parseSystemImages(result.stdout);
+    return options.installedOnly ? images.filter((image) => image.installed) : images;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { getDefaultRuntimeConfig, listRunningEmulators, listConfiguredAvds, inspectConfiguredAvd, createAvd, startAvd, stopAvd, deleteAvd, waitForBootCompletion, waitForEmulatorRegistration, ensureSystemImageInstalled, setAvdDataPartitionSize } from "./index.js";
+import { getDefaultRuntimeConfig, listRunningEmulators, listConfiguredAvds, inspectConfiguredAvd, createAvd, startAvd, stopAvd, deleteAvd, waitForBootCompletion, waitForEmulatorRegistration, ensureSystemImageInstalled, setAvdDataPartitionSize, listHardwareProfiles, listSystemImages } from "./index.js";
 const commands = {
+    profiles: "profiles", images: "images [--installed]",
     list: "list", inspect: "inspect <name>", status: "status",
     download: "download <system-image> [--accept-licenses]",
     create: "create <name> --image <system-image> --profile <hardware-profile> --storage-size <12G> [--replace] [--accept-licenses]",
@@ -14,7 +15,7 @@ function usage(message) {
 }
 async function main() {
     const { values, positionals } = parseArgs({ allowPositionals: true, strict: true, options: {
-            help: { type: "boolean", short: "h" }, version: { type: "boolean" }, json: { type: "boolean" },
+            installed: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" }, json: { type: "boolean" },
             output: { type: "string" }, image: { type: "string" }, profile: { type: "string" },
             "storage-size": { type: "string" }, replace: { type: "boolean" },
             "accept-licenses": { type: "boolean" }, headless: { type: "boolean" }, "timeout-ms": { type: "string" },
@@ -23,17 +24,18 @@ async function main() {
         usage("--output supports json; for example --output json list");
     if (values.version) {
         const { name, version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-        return { name, version, protocolVersion: 1 };
+        return { name, version, protocolVersion: 1, capabilities: ["catalog.profiles", "catalog.images"] };
     }
     if (values.help)
         return { commands, output: "One JSON envelope on stdout; exit 0 success, 1 operation failure, 2 usage error" };
     const [command, target, ...extra] = positionals;
     if (!Object.hasOwn(commands, command ?? ""))
         usage(`Unknown or missing command: ${command ?? ""}; use --help`);
-    const needsTarget = !["list", "status"].includes(command);
+    const needsTarget = !["list", "status", "profiles", "images"].includes(command);
     if (extra.length || (needsTarget ? target === undefined || target.trim() === "" : target !== undefined))
         usage(`Use ${commands[command]}`);
     const allowed = {
+        images: ["installed"],
         create: ["image", "profile", "storage-size", "replace", "accept-licenses"],
         download: ["accept-licenses"], start: ["headless"], wait: ["timeout-ms"], storage: ["storage-size"],
     };
@@ -49,6 +51,8 @@ async function main() {
     }
     const config = getDefaultRuntimeConfig();
     switch (command) {
+        case "profiles": return { profiles: await listHardwareProfiles(config) };
+        case "images": return { images: await listSystemImages(config, { installedOnly: values.installed }) };
         case "status": return { devices: await listRunningEmulators(config) };
         case "list": {
             const running = await listRunningEmulators(config);

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 export declare const ERROR_CODES: {
+    readonly ANDROID_CATALOG_QUERY_FAILED: "ANDROID_CATALOG_QUERY_FAILED";
     readonly ADB_QUERY_FAILED: "ADB_QUERY_FAILED";
     readonly ANDROID_AVD_CREATE_FAILED: "ANDROID_AVD_CREATE_FAILED";
     readonly ANDROID_SDK_TOOL_MISSING: "ANDROID_SDK_TOOL_MISSING";

package/dist/errors.js

@@ -1,4 +1,5 @@
 export const ERROR_CODES = {
+    ANDROID_CATALOG_QUERY_FAILED: "ANDROID_CATALOG_QUERY_FAILED",
     ADB_QUERY_FAILED: "ADB_QUERY_FAILED",
     ANDROID_AVD_CREATE_FAILED: "ANDROID_AVD_CREATE_FAILED",
     ANDROID_SDK_TOOL_MISSING: "ANDROID_SDK_TOOL_MISSING",

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export * from "./configuredAvds.js";
 export * from "./runningEmulators.js";
 export * from "./lifecycle.js";
 export * from "./validation.js";
+export * from "./catalog.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,4 +8,5 @@ export * from "./configuredAvds.js";
 export * from "./runningEmulators.js";
 export * from "./lifecycle.js";
 export * from "./validation.js";
+export * from "./catalog.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@androperator/emulator",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Android emulator lifecycle library and structured CLI extracted from Androperator",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,8 @@
     "README.md",
     "LICENSE",
     "NOTICE",
-    "docs/provenance.md"
+    "docs/provenance.md",
+    ".agents/skills/create-android-emulator/"
   ],
   "engines": {
     "node": ">=24"