@swmansion/argent 0.9.0 → 0.10.0

package/README.md

@@ -37,6 +37,43 @@ npx @swmansion/argent init
 - For iOS: macOS with **Xcode** installed
 - For Android: **Android SDK Platform Tools** (`adb`) on `PATH`, and the **Android Emulator** package if you want to boot AVDs from Argent. Create AVDs via Android Studio or `avdmanager`.
 
+##### Linux host: extra prerequisites for Android emulators
+
+Argent runs Android emulators on Linux but the default install can be slow if a few host-side knobs aren't right. Cover these once and the experience matches macOS:
+
+- **KVM access.** The emulator falls back to slow software emulation (TCG) without `/dev/kvm`. Make sure virtualization is enabled in BIOS/UEFI (`vmx` for Intel, `svm` for AMD in `/proc/cpuinfo`) and that your user can read/write `/dev/kvm` — on most distros that means joining the `kvm` group:
+
+  ```bash
+  sudo usermod -aG kvm "$USER"
+  # log out and back in so the new group takes effect
+  ```
+
+- **GPU mode (`-gpu swiftshader` on Linux, override available).** The Android emulator's Linux GPU story is messy: `-gpu auto` frequently resolves to lavapipe (slow software Vulkan via host libvulkan, ~10× cold-boot regression on flagship hardware), and `-gpu host` silently produces a corrupted or black emulator window on hosts with non-trivial GL stacks — dual-GPU / Optimus laptops, NVIDIA + Mesa coexistence via libglvnd, Wayland sessions on hybrid graphics, headless / containerized hosts. The failure mode is invisible to argent's framebuffer-based screenshot tool, so an agent reports success while the developer sees a black window.
+
+  Argent picks `-gpu swiftshader` on Linux for universal compatibility: it sidesteps the host GL stack entirely and renders via the emulator's bundled SwiftShader. On modern multi-core machines this is indistinguishably smooth from hardware-accelerated `-gpu host` (and far faster than lavapipe).
+
+  Override with the `ARGENT_EMULATOR_GPU_MODE` env var if you've verified `-gpu host` works on your machine (typical single-GPU Mesa box with a healthy X session):
+
+  ```bash
+  ARGENT_EMULATOR_GPU_MODE=host argent ...
+  ```
+
+  Argent's boot-device preflight prints a warning if `/dev/kvm` isn't usable — the condition that causes a 10–50× TCG-vs-KVM slowdown.
+
+- **System image.** Prefer the `default` or `google_apis` variants of `x86_64` system images for headless agent workflows; `google_apis_playstore` adds noticeable boot-time CPU churn from Play services. Always pick `x86_64` on Intel/AMD hosts — ARM images run via QEMU translation and are dramatically slower.
+
+- **AVD config.** AVDs created via `avdmanager create avd` default to `hw.gpu.enabled=no`. Argent overrides this with an explicit `-gpu` arg at launch (so the on-disk config doesn't need editing). For the smoothest experience under heavy native builds (gradle compilations alongside the AVD), bump the AVD's RAM and CPU count — edit `~/.android/avd/<name>.avd/config.ini`:
+
+  ```
+  hw.ramSize = 8192
+  hw.cpu.ncore = 6
+  vm.heapSize = 512
+  ```
+
+  Stock 2 GB / 4 vCPU AVDs can be CPU-starved into wedged-system_server states by a concurrent gradle/Kotlin compile.
+
+- **Headless / CI mode (`ARGENT_EMULATOR_NO_WINDOW=1`).** Argent shows the emulator window by default so a local developer can see the AVD UI. In a headless context — CI runner, container, or a Wayland-only session where the emulator's bundled Qt has no `wayland` platform plugin and SIGABRTs on the crash-consent dialog — opt out by exporting `ARGENT_EMULATOR_NO_WINDOW=1` before starting the tool-server. This appends `-no-window` to the spawn args, selecting `qemu-system-x86_64-headless` which doesn't need a Qt window. Argent's screencap-based screenshot tool reads the in-memory framebuffer correctly without a visible window.
+
 #### Run `init` in your project
 
 From your project root:
@@ -60,14 +97,17 @@ argent init
 
 ## CLI Reference
 
-| Command            | Description                                                 |
-| ------------------ | ----------------------------------------------------------- |
-| `argent init`      | Install globally and configure MCP in the current workspace |
-| `argent install`   | Alias for `init` command                                    |
-| `argent update`    | Pull the latest version and refresh workspace configuration |
-| `argent remove`    | Unregister the MCP server and uninstall the package         |
-| `argent uninstall` | Alias for `remove` command                                  |
-| `argent mcp`       | Start MCP server instance, used internally by agent         |
+| Command            | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| `argent init`      | Install globally and configure MCP in the current workspace            |
+| `argent install`   | Alias for `init` command                                               |
+| `argent update`    | Pull the latest version and refresh workspace configuration            |
+| `argent remove`    | Unregister the MCP server and uninstall the package                    |
+| `argent uninstall` | Alias for `remove` command                                             |
+| `argent mcp`       | Start MCP server instance, used internally by agent                    |
+| `argent enable`    | Enable a predefined feature flag (`--scope project` for project-local) |
+| `argent disable`   | Disable a feature flag (`--scope project` for project-local)           |
+| `argent flags`     | List available feature flags and their state                           |
 
 ## Supported Editors
 
@@ -99,7 +139,7 @@ Argent uses a mixed licensing model.
 
 **Source code** is released under the [Apache License 2.0](LICENSE.txt).
 
-**Proprietary binaries** (the `bin/simulator-server` and `bin/ax-service` executables and the `.dylib` files in `native-devtools-ios`) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited.
+**Proprietary binaries** (the per-platform `bin/<platform>/simulator-server` and `bin/darwin/ax-service` executables and the `.dylib` files in `native-devtools-ios`) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited.
 
 By using Argent, you acknowledge and agree to this structure. See [LICENSE](https://github.com/software-mansion/argent/blob/main/LICENSE.txt) for full details.
 

package/bin/argent-simulator-server.cjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+"use strict";
+
+// Thin dispatcher exposed as the `argent-simulator-server` bin entry in
+// package.json. Picks the platform-specific simulator-server binary at
+// invocation time and execs it with the caller's args. Required because
+// npm's `bin` field resolves to a single file regardless of host platform,
+// but the binary itself is platform-specific (Mach-O for darwin, ELF for
+// linux). The native-devtools-ios resolver uses the same per-platform
+// subdirectory layout, so a stable layout lives in exactly one place.
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const binary = path.join(__dirname, process.platform, "simulator-server");
+if (!fs.existsSync(binary)) {
+  console.error(
+    `argent-simulator-server: no binary for platform "${process.platform}" at ${binary}.\n` +
+      `Supported hosts today: darwin, linux.`
+  );
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
+// Forward termination signals so a supervisor that signals only the dispatcher
+// PID (systemd, `kill -TERM <pid>`, container stop) doesn't orphan the child.
+// Ctrl+C in a TTY already broadcasts to the whole process group so the child
+// receives it too — these handlers cover the non-TTY case where the parent
+// would otherwise exit alone and leave the binary reparented to init.
+/** @type {NodeJS.Signals[]} */
+const FORWARDED_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"];
+for (const sig of FORWARDED_SIGNALS) {
+  process.on(sig, () => {
+    if (!child.killed) {
+      try {
+        child.kill(sig);
+      } catch {
+        // Already exited between the signal arriving and us forwarding it.
+      }
+    }
+  });
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});
+child.on("error", (err) => {
+  console.error(`argent-simulator-server: failed to spawn ${binary}: ${err.message}`);
+  process.exit(1);
+});