uncontainerizable 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,226 @@
+# uncontainerizable
+
+> Graceful process lifecycle for programs that can't be put in real containers.
+
+A supervisor for the apps you can't put in Docker: browsers, GUI apps,
+and anything that needs the user's window server, keychain, or display.
+Built on a pure-Rust core with Node bindings via
+[napi-rs](https://napi.rs); the published binary is prebuilt for every
+supported target.
+
+If the program can run in a real sandbox — namespaces, seccomp, landlock
+— use a real container runtime. `uncontainerizable` is for everything else.
+
+## Features
+
+- **Staged quit ladder.** Each platform escalates from its polite quit
+  channel to a guaranteed kill, with per-stage timeouts and skippable
+  stages.
+- **Tree-aware teardown.** Helper processes get reaped alongside the root;
+  the container is "empty" only when no member remains.
+- **Identity-based preemption.** Spawning with an `identity` preempts
+  earlier matching instances. Linux and Windows are identity-scoped;
+  macOS `.app` launches use bundle-scoped preemption on the Launch
+  Services path.
+- **Adapter hooks.** Per-app lifecycle callbacks suppress "didn't shut
+  down correctly" dialogs after force-kill.
+- **Infallible destroy.** `destroy()` aggregates errors into the result
+  so `finally` blocks never throw.
+- **Async first.** `Promise`-based API, Tokio-backed core.
+
+## Platform support
+
+| Platform          | Preemption primitive | Quit ladder                                |
+| ----------------- | -------------------- | ------------------------------------------ |
+| Linux (x64/arm64) | cgroup v2            | `SIGTERM` → `SIGKILL` (race-free via freeze) |
+| macOS (x64/arm64) | `argv[0]` tag scan / bundle-exec `ps` scan | `aevt/quit` → `SIGTERM` → `SIGKILL` |
+| Windows (x64/arm64) | named Job Object   | `WM_CLOSE` → `TerminateJobObject`            |
+
+Linux musl is shipped via `cargo-zigbuild`. Identity strings are
+namespaced by an app-level prefix (conventionally reverse-DNS) so
+libraries using `uncontainerizable` cannot collide.
+
+On macOS, direct-exec launches use `argv[0]` tag scanning. Launch
+Services `.app` launches instead match by bundle executable path via
+`ps comm=`, so supplying `identity` there kills any running instance of
+that bundle before relaunch, regardless of which identity started it.
+Launch Services therefore does not support keeping two instances of the
+same `.app` alive concurrently through this route. If you need that for
+an app bundle, first make sure the app itself supports concurrent
+instances, then pass the inner executable path
+(`Foo.app/Contents/MacOS/Foo`) so the launch goes through direct-exec
+instead of Launch Services.
+
+## Installation
+
+```sh
+npm install uncontainerizable
+# or
+pnpm add uncontainerizable
+# or
+yarn add uncontainerizable
+```
+
+The package pulls in `@uncontainerizable/native`, which resolves to a
+prebuilt `.node` binary for the current platform. No native toolchain
+is needed at install time.
+
+> [!IMPORTANT]
+> Node.js ≥ 24 is required (current LTS). The package ships ESM only.
+
+## Quick start
+
+```ts
+import { App, defaultAdapters } from "uncontainerizable";
+
+const app = new App("com.example.my-supervisor");
+
+const container = await app.contain("chromium", {
+  args: ["--user-data-dir=/tmp/browser-profile"],
+  identity: "browser-main", // preempts any previous "browser-main"
+  adapters: [...defaultAdapters],
+});
+
+// ... later, when you want to shut it down cleanly:
+const result = await container.destroy();
+
+if (result.errors.length > 0) {
+  console.warn("teardown surfaced recoverable errors:", result.errors);
+}
+
+console.log(`exited at ${result.quit.exitedAtStage}`);
+```
+
+A second call to `app.contain(..., { identity: "browser-main" })` will
+kill the running instance before launching the new one. On macOS `.app`
+launches, the same option acts as a bundle-scoped clean-slate switch and
+clears any running instance of that bundle. Omit `identity` to skip
+preemption entirely. If you need concurrent instances of a bundled app on
+macOS, pass the executable inside the bundle rather than the `.app`
+directory, and only do that if the app itself supports multiple
+instances.
+
+## API
+
+### `new App(prefix)`
+
+Namespaced handle for spawning contained processes. The `prefix`
+(conventionally reverse-DNS, e.g. `"com.example.my-supervisor"`)
+namespaces identity strings so unrelated libraries can't collide.
+
+Throws `INVALID_IDENTITY` if `prefix` contains characters outside
+`[A-Za-z0-9._:-]`.
+
+### `app.contain(command, options?) → Promise<Container>`
+
+Spawns a contained process. Options:
+
+| Field             | Type             | Notes                                                            |
+| ----------------- | ---------------- | ---------------------------------------------------------------- |
+| `args`            | `string[]`       | Command-line arguments.                                          |
+| `env`             | `Record<…>`      | Environment overrides.                                           |
+| `cwd`             | `string`         | Working directory.                                               |
+| `identity`        | `string`         | Enables preemption; macOS `.app` launches match by bundle, other routes by identity. Use the inner executable path, not the `.app` path, if the app supports concurrent instances and you need more than one at once. |
+| `adapters`        | `Adapter[]`      | Per-app lifecycle hooks.                                         |
+| `darwinTagArgv0`  | `boolean`        | macOS direct-exec only; set `false` if the managed program misreads argv[0] (ignored for `.app` bundle launches). |
+
+### `container.quit(options?) → Promise<QuitResult>`
+
+Runs the staged quit ladder without releasing platform resources. Use
+when you want to wait for the process to drain but keep the container
+handle alive.
+
+### `container.destroy(options?) → Promise<DestroyResult>`
+
+Runs the quit ladder and releases platform resources. Always resolves:
+recoverable errors appear in `result.errors`, never as a thrown
+exception.
+
+### `coreVersion() → string`
+
+Returns the Rust core's version string — handy for logging and support.
+
+## Built-in adapters
+
+Adapters match by probe (bundle ID, executable path, platform). Their
+`clearCrashState` hook runs after a terminal-stage teardown to suppress
+restart dialogs.
+
+| Adapter         | Purpose                                                              |
+| --------------- | -------------------------------------------------------------------- |
+| `appkit`        | Deletes AppKit's "Saved Application State" directory on macOS.       |
+| `crashReporter` | Clears per-app entries from macOS's user-level CrashReporter archive.|
+| `chromium`      | Matches Chrome/Chromium/Brave/Edge. Crash-state cleanup is stubbed.  |
+| `firefox`       | Matches Firefox. Crash-state cleanup is stubbed.                     |
+
+Import individually or as a bundle:
+
+```ts
+import {
+  appkit,
+  chromium,
+  crashReporter,
+  defaultAdapters,
+  firefox,
+} from "uncontainerizable";
+```
+
+## Custom adapters
+
+An adapter is any object matching the `Adapter` shape. Every hook except
+`name` and `matches` is optional; unimplemented hooks are skipped. Hooks
+may be sync or async — the wrapper normalizes both forms before crossing
+the napi boundary.
+
+```ts
+import type { Adapter } from "uncontainerizable";
+
+const logger: Adapter = {
+  name: "logger",
+  matches: () => true,
+  beforeStage(probe, stageName) {
+    console.log(`[${probe.pid}] entering stage ${stageName}`);
+  },
+  afterStage(_probe, result) {
+    if (result.exited) {
+      console.log(`drained at ${result.stageName}`);
+    }
+  },
+};
+```
+
+Hook surface:
+
+- `beforeQuit(probe)` — before the ladder starts.
+- `beforeStage(probe, stageName)` / `afterStage(probe, result)` — around
+  each stage.
+- `afterQuit(probe, result)` — after the ladder ends, terminal or not.
+- `clearCrashState(probe)` — only after a terminal-stage teardown.
+
+> [!TIP]
+> Adapter hooks are **advisory**: errors are collected into
+> `QuitResult.adapterErrors` and never abort the quit ladder. A
+> misbehaving adapter cannot prevent teardown.
+
+## TypeScript
+
+All public types are exported from the package root:
+
+```ts
+import type {
+  Adapter,
+  ContainOptions,
+  Container,
+  DestroyOptions,
+  DestroyResult,
+  Probe,
+  QuitOptions,
+  QuitResult,
+  StageResult,
+  SupportedPlatform,
+} from "uncontainerizable";
+```
+
+## License
+
+[MIT](https://github.com/inakineitor/uncontainerizable/blob/main/LICENSE)

package/dist/index.d.mts

@@ -17,10 +17,15 @@ declare class App {
   constructor(prefix: string);
   get prefix(): string;
   /**
-   * Spawn a contained process. If `options.identity` is set, any previous
-   * instance with the same (prefix, identity) pair is killed before this
-   * one launches. If `options.adapters` is non-empty the Rust
-   * orchestrator drives their lifecycle hooks around the quit ladder.
+   * Spawn a contained process. If `options.identity` is set, a prior
+   * matching instance is killed before launch. On macOS Launch Services
+   * `.app` launches, matching is bundle-scoped rather than
+   * `(prefix, identity)`-scoped, so this route cannot keep two instances
+   * of the same app alive concurrently. If the app itself supports
+   * multiple concurrent instances, pass the inner executable path
+   * (`Foo.app/Contents/MacOS/Foo`) to use the direct-exec route instead.
+   * If `options.adapters` is non-empty the Rust orchestrator drives their
+   * lifecycle hooks around the quit ladder.
    */
   contain(command: string, options?: ContainOptions): Promise<Container>;
 }

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;AAwBA;;;;;;;;;cAAa,GAAA;EAAA;cAGC,MAAA;EAAA,IAIR,MAAA,CAAA;EAUI;;;;;;EAAR,OAAA,CAAQ,OAAA,UAAiB,OAAA,GAAS,cAAA,GAAsB,OAAA,CAAQ,SAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;AAwBA;;;;;;;;;cAAa,GAAA;EAAA;cAGC,MAAA;EAAA,IAIR,MAAA,CAAA;EAeI;;;;;;;;;;;EAAR,OAAA,CAAQ,OAAA,UAAiB,OAAA,GAAS,cAAA,GAAsB,OAAA,CAAQ,SAAA;AAAA"}

package/dist/index.mjs

@@ -20,10 +20,15 @@ var App = class {
 		return this.#inner.prefix;
 	}
 	/**
-	* Spawn a contained process. If `options.identity` is set, any previous
-	* instance with the same (prefix, identity) pair is killed before this
-	* one launches. If `options.adapters` is non-empty the Rust
-	* orchestrator drives their lifecycle hooks around the quit ladder.
+	* Spawn a contained process. If `options.identity` is set, a prior
+	* matching instance is killed before launch. On macOS Launch Services
+	* `.app` launches, matching is bundle-scoped rather than
+	* `(prefix, identity)`-scoped, so this route cannot keep two instances
+	* of the same app alive concurrently. If the app itself supports
+	* multiple concurrent instances, pass the inner executable path
+	* (`Foo.app/Contents/MacOS/Foo`) to use the direct-exec route instead.
+	* If `options.adapters` is non-empty the Rust orchestrator drives their
+	* lifecycle hooks around the quit ladder.
 	*/
 	contain(command, options = {}) {
 		const { adapters, ...nativeOpts } = options;

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["#inner"],"sources":["../src/index.ts"],"sourcesContent":["import { type JsAdapter, NodeApp } from \"@uncontainerizable/native\";\n\nimport type { Adapter, ContainOptions, Container } from \"#/types.js\";\n\nexport { coreVersion } from \"@uncontainerizable/native\";\n\nexport {\n  appkit,\n  chromium,\n  crashReporter,\n  defaultAdapters,\n  firefox,\n} from \"#/adapters/index.js\";\n\n/**\n * Namespaced handle for spawning contained processes.\n *\n * Construct once per application, typically with a reverse-DNS string like\n * `\"com.example.my-supervisor\"`. The prefix namespaces identity strings so\n * two unrelated libraries using `uncontainerizable` cannot collide.\n *\n * Throws `INVALID_IDENTITY` if the prefix contains characters outside\n * `[A-Za-z0-9._:-]`.\n */\nexport class App {\n  readonly #inner: NodeApp;\n\n  constructor(prefix: string) {\n    this.#inner = new NodeApp(prefix);\n  }\n\n  get prefix(): string {\n    return this.#inner.prefix;\n  }\n\n  /**\n   * Spawn a contained process. If `options.identity` is set, any previous\n   * instance with the same (prefix, identity) pair is killed before this\n   * one launches. If `options.adapters` is non-empty the Rust\n   * orchestrator drives their lifecycle hooks around the quit ladder.\n   */\n  contain(command: string, options: ContainOptions = {}): Promise<Container> {\n    const { adapters, ...nativeOpts } = options;\n    return this.#inner.contain(command, {\n      ...nativeOpts,\n      adapters: adapters?.map(normalizeAdapter),\n    });\n  }\n}\n\n/**\n * Normalize a user-provided `Adapter` (which may declare sync methods)\n * into the always-async shape the napi bridge expects. Every optional\n * hook is only forwarded if defined, so the Rust side keeps its\n * \"undefined means skip\" semantics.\n */\nfunction normalizeAdapter(adapter: Adapter): JsAdapter {\n  return {\n    name: adapter.name,\n    matches: async (probe) => Boolean(await adapter.matches(probe)),\n    beforeQuit: adapter.beforeQuit\n      ? async (probe) => {\n          await adapter.beforeQuit?.(probe);\n        }\n      : undefined,\n    beforeStage: adapter.beforeStage\n      ? async (probe, stageName) => {\n          await adapter.beforeStage?.(probe, stageName);\n        }\n      : undefined,\n    afterStage: adapter.afterStage\n      ? async (probe, result) => {\n          await adapter.afterStage?.(probe, result);\n        }\n      : undefined,\n    afterQuit: adapter.afterQuit\n      ? async (probe, result) => {\n          await adapter.afterQuit?.(probe, result);\n        }\n      : undefined,\n    clearCrashState: adapter.clearCrashState\n      ? async (probe) => {\n          await adapter.clearCrashState?.(probe);\n        }\n      : undefined,\n  };\n}\n\nexport type {\n  Adapter,\n  ContainOptions,\n  Container,\n  DestroyOptions,\n  DestroyResult,\n  Probe,\n  QuitOptions,\n  QuitResult,\n  StageResult,\n  SupportedPlatform,\n} from \"#/types.js\";\n"],"mappings":";;;;;;;;;;;;;AAwBA,IAAa,MAAb,MAAiB;CACf;CAEA,YAAY,QAAgB;AAC1B,QAAA,QAAc,IAAI,QAAQ,OAAO;;CAGnC,IAAI,SAAiB;AACnB,SAAO,MAAA,MAAY;;;;;;;;CASrB,QAAQ,SAAiB,UAA0B,EAAE,EAAsB;EACzE,MAAM,EAAE,UAAU,GAAG,eAAe;AACpC,SAAO,MAAA,MAAY,QAAQ,SAAS;GAClC,GAAG;GACH,UAAU,UAAU,IAAI,iBAAiB;GAC1C,CAAC;;;;;;;;;AAUN,SAAS,iBAAiB,SAA6B;AACrD,QAAO;EACL,MAAM,QAAQ;EACd,SAAS,OAAO,UAAU,QAAQ,MAAM,QAAQ,QAAQ,MAAM,CAAC;EAC/D,YAAY,QAAQ,aAChB,OAAO,UAAU;AACf,SAAM,QAAQ,aAAa,MAAM;MAEnC,KAAA;EACJ,aAAa,QAAQ,cACjB,OAAO,OAAO,cAAc;AAC1B,SAAM,QAAQ,cAAc,OAAO,UAAU;MAE/C,KAAA;EACJ,YAAY,QAAQ,aAChB,OAAO,OAAO,WAAW;AACvB,SAAM,QAAQ,aAAa,OAAO,OAAO;MAE3C,KAAA;EACJ,WAAW,QAAQ,YACf,OAAO,OAAO,WAAW;AACvB,SAAM,QAAQ,YAAY,OAAO,OAAO;MAE1C,KAAA;EACJ,iBAAiB,QAAQ,kBACrB,OAAO,UAAU;AACf,SAAM,QAAQ,kBAAkB,MAAM;MAExC,KAAA;EACL"}
+{"version":3,"file":"index.mjs","names":["#inner"],"sources":["../src/index.ts"],"sourcesContent":["import { type JsAdapter, NodeApp } from \"@uncontainerizable/native\";\n\nimport type { Adapter, ContainOptions, Container } from \"#/types.js\";\n\nexport { coreVersion } from \"@uncontainerizable/native\";\n\nexport {\n  appkit,\n  chromium,\n  crashReporter,\n  defaultAdapters,\n  firefox,\n} from \"#/adapters/index.js\";\n\n/**\n * Namespaced handle for spawning contained processes.\n *\n * Construct once per application, typically with a reverse-DNS string like\n * `\"com.example.my-supervisor\"`. The prefix namespaces identity strings so\n * two unrelated libraries using `uncontainerizable` cannot collide.\n *\n * Throws `INVALID_IDENTITY` if the prefix contains characters outside\n * `[A-Za-z0-9._:-]`.\n */\nexport class App {\n  readonly #inner: NodeApp;\n\n  constructor(prefix: string) {\n    this.#inner = new NodeApp(prefix);\n  }\n\n  get prefix(): string {\n    return this.#inner.prefix;\n  }\n\n  /**\n   * Spawn a contained process. If `options.identity` is set, a prior\n   * matching instance is killed before launch. On macOS Launch Services\n   * `.app` launches, matching is bundle-scoped rather than\n   * `(prefix, identity)`-scoped, so this route cannot keep two instances\n   * of the same app alive concurrently. If the app itself supports\n   * multiple concurrent instances, pass the inner executable path\n   * (`Foo.app/Contents/MacOS/Foo`) to use the direct-exec route instead.\n   * If `options.adapters` is non-empty the Rust orchestrator drives their\n   * lifecycle hooks around the quit ladder.\n   */\n  contain(command: string, options: ContainOptions = {}): Promise<Container> {\n    const { adapters, ...nativeOpts } = options;\n    return this.#inner.contain(command, {\n      ...nativeOpts,\n      adapters: adapters?.map(normalizeAdapter),\n    });\n  }\n}\n\n/**\n * Normalize a user-provided `Adapter` (which may declare sync methods)\n * into the always-async shape the napi bridge expects. Every optional\n * hook is only forwarded if defined, so the Rust side keeps its\n * \"undefined means skip\" semantics.\n */\nfunction normalizeAdapter(adapter: Adapter): JsAdapter {\n  return {\n    name: adapter.name,\n    matches: async (probe) => Boolean(await adapter.matches(probe)),\n    beforeQuit: adapter.beforeQuit\n      ? async (probe) => {\n          await adapter.beforeQuit?.(probe);\n        }\n      : undefined,\n    beforeStage: adapter.beforeStage\n      ? async (probe, stageName) => {\n          await adapter.beforeStage?.(probe, stageName);\n        }\n      : undefined,\n    afterStage: adapter.afterStage\n      ? async (probe, result) => {\n          await adapter.afterStage?.(probe, result);\n        }\n      : undefined,\n    afterQuit: adapter.afterQuit\n      ? async (probe, result) => {\n          await adapter.afterQuit?.(probe, result);\n        }\n      : undefined,\n    clearCrashState: adapter.clearCrashState\n      ? async (probe) => {\n          await adapter.clearCrashState?.(probe);\n        }\n      : undefined,\n  };\n}\n\nexport type {\n  Adapter,\n  ContainOptions,\n  Container,\n  DestroyOptions,\n  DestroyResult,\n  Probe,\n  QuitOptions,\n  QuitResult,\n  StageResult,\n  SupportedPlatform,\n} from \"#/types.js\";\n"],"mappings":";;;;;;;;;;;;;AAwBA,IAAa,MAAb,MAAiB;CACf;CAEA,YAAY,QAAgB;AAC1B,QAAA,QAAc,IAAI,QAAQ,OAAO;;CAGnC,IAAI,SAAiB;AACnB,SAAO,MAAA,MAAY;;;;;;;;;;;;;CAcrB,QAAQ,SAAiB,UAA0B,EAAE,EAAsB;EACzE,MAAM,EAAE,UAAU,GAAG,eAAe;AACpC,SAAO,MAAA,MAAY,QAAQ,SAAS;GAClC,GAAG;GACH,UAAU,UAAU,IAAI,iBAAiB;GAC1C,CAAC;;;;;;;;;AAUN,SAAS,iBAAiB,SAA6B;AACrD,QAAO;EACL,MAAM,QAAQ;EACd,SAAS,OAAO,UAAU,QAAQ,MAAM,QAAQ,QAAQ,MAAM,CAAC;EAC/D,YAAY,QAAQ,aAChB,OAAO,UAAU;AACf,SAAM,QAAQ,aAAa,MAAM;MAEnC,KAAA;EACJ,aAAa,QAAQ,cACjB,OAAO,OAAO,cAAc;AAC1B,SAAM,QAAQ,cAAc,OAAO,UAAU;MAE/C,KAAA;EACJ,YAAY,QAAQ,aAChB,OAAO,OAAO,WAAW;AACvB,SAAM,QAAQ,aAAa,OAAO,OAAO;MAE3C,KAAA;EACJ,WAAW,QAAQ,YACf,OAAO,OAAO,WAAW;AACvB,SAAM,QAAQ,YAAY,OAAO,OAAO;MAE1C,KAAA;EACJ,iBAAiB,QAAQ,kBACrB,OAAO,UAAU;AACf,SAAM,QAAQ,kBAAkB,MAAM;MAExC,KAAA;EACL"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uncontainerizable",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Graceful process lifecycle for programs that can't be containerized",
   "keywords": [
     "lifecycle",
@@ -41,7 +41,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@uncontainerizable/native": "0.1.0"
+    "@uncontainerizable/native": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^24",