uncontainerizable 0.1.1 → 0.1.2

package/README.md

@@ -18,9 +18,10 @@ If the program can run in a real sandbox — namespaces, seccomp, landlock
   stages.
 - **Tree-aware teardown.** Helper processes get reaped alongside the root;
   the container is "empty" only when no member remains.
-- **Identity-based singleton.** At most one container per identity is
-  alive at a time; spawning preempts any predecessor using kernel
-  primitives on Linux and Windows.
+- **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
@@ -32,13 +33,24 @@ If the program can run in a real sandbox — namespaces, seccomp, landlock
 | Platform          | Preemption primitive | Quit ladder                                |
 | ----------------- | -------------------- | ------------------------------------------ |
 | Linux (x64/arm64) | cgroup v2            | `SIGTERM` → `SIGKILL` (race-free via freeze) |
-| macOS (x64/arm64) | `argv[0]` tag scan   | `aevt/quit` → `SIGTERM` → `SIGKILL`          |
+| 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
@@ -80,8 +92,13 @@ 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. Omit `identity`
-to skip preemption entirely.
+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
 
@@ -103,9 +120,9 @@ Spawns a contained process. Options:
 | `args`            | `string[]`       | Command-line arguments.                                          |
 | `env`             | `Record<…>`      | Environment overrides.                                           |
 | `cwd`             | `string`         | Working directory.                                               |
-| `identity`        | `string`         | Enables singleton enforcement; prior instance is killed first.   |
+| `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 only; set `false` if the managed program misreads argv[0]. |
+| `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>`
 

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.1",
+  "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.1"
+    "@uncontainerizable/native": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^24",