uncontainerizable 0.0.3 → 0.1.1

package/README.md

@@ -0,0 +1,209 @@
+# 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 singleton.** At most one container per identity is
+  alive at a time; spawning preempts any predecessor using kernel
+  primitives on Linux and Windows.
+- **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   | `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.
+
+## 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. Omit `identity`
+to skip preemption entirely.
+
+## 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 singleton enforcement; prior instance is killed first.   |
+| `adapters`        | `Adapter[]`      | Per-app lifecycle hooks.                                         |
+| `darwinTagArgv0`  | `boolean`        | macOS only; set `false` if the managed program misreads argv[0]. |
+
+### `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/adapters/index.d.mts

@@ -1 +1,2 @@
-export { };
+import { a as appkit, i as chromium, n as firefox, r as crashReporter, t as defaultAdapters } from "../index-B1y4yb1N.mjs";
+export { appkit, chromium, crashReporter, defaultAdapters, firefox };

package/dist/adapters/index.mjs

@@ -1 +1,2 @@
-export {  };
+import { a as appkit, i as chromium, n as firefox, r as crashReporter, t as defaultAdapters } from "../adapters-BYLFpYWC.mjs";
+export { appkit, chromium, crashReporter, defaultAdapters, firefox };

package/dist/adapters-BYLFpYWC.mjs

@@ -0,0 +1,157 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+//#region src/adapters/appkit.ts
+/**
+* Deletes the AppKit "Saved Application State" directory for the managed
+* app after a terminal-stage destroy.
+*
+* macOS's AppKit persists a per-app snapshot of open windows and the
+* "should reopen windows on next launch" hint at
+* `~/Library/Saved Application State/<bundleId>.savedState/`. When an
+* app is force-killed (our SIGTERM/SIGKILL ladder), AppKit interprets
+* the missing clean-shutdown marker as a crash and shows the
+* "Reopen windows?" dialog next launch. Wiping the directory suppresses
+* the dialog.
+*
+* Only matches on darwin probes that carry a resolved `bundleId`.
+* Programs spawned without bundle-ID resolution (anything outside
+* `lsappinfo`'s knowledge of launched apps, for example `sleep` or a
+* manually-compiled binary) silently skip.
+*/
+const appkit = {
+	name: "appkit",
+	matches(probe) {
+		return probe.platform === "darwin" && typeof probe.bundleId === "string";
+	},
+	async clearCrashState(probe) {
+		if (!probe.bundleId) return;
+		await rm(join(homedir(), "Library", "Saved Application State", `${probe.bundleId}.savedState`), {
+			recursive: true,
+			force: true
+		});
+	}
+};
+//#endregion
+//#region src/adapters/chromium.ts
+const CHROMIUM_BASENAMES = [
+	"chrome",
+	"chromium",
+	"Chromium",
+	"Google Chrome",
+	"brave",
+	"Brave Browser",
+	"msedge",
+	"Microsoft Edge"
+];
+/**
+* Stub adapter for Chromium-family browsers.
+*
+* Matches by executable basename (case-sensitive, since bundle exe names
+* are preserved verbatim). The real `clearCrashState` implementation
+* edits the "Last Exit Type" key in the browser's `Preferences` JSON so
+* the next launch does not prompt the user to restore a crashed
+* session. That implementation needs per-OS profile-dir detection and
+* careful JSON editing; it ships in a follow-up.
+*
+* Until then `clearCrashState` emits a warning and returns. The adapter
+* still matches so callers wiring it in can see the "didn't run" signal
+* and swap in a real cleanup when the full version ships.
+*/
+const chromium = {
+	name: "chromium",
+	matches(probe) {
+		const exe = probe.executablePath ? basename(probe.executablePath) : void 0;
+		return exe ? CHROMIUM_BASENAMES.includes(exe) : false;
+	},
+	clearCrashState(_probe) {
+		console.warn("uncontainerizable: chromium.clearCrashState is a stub; the next launch may show a 'didn't shut down correctly' dialog. Track the real implementation in a follow-up release.");
+	}
+};
+//#endregion
+//#region src/adapters/crash-reporter.ts
+/**
+* Deletes per-app crash reports from macOS's user-level CrashReporter
+* archive after a terminal-stage destroy.
+*
+* When our SIGTERM/SIGKILL ladder kills an app, macOS's `ReportCrash`
+* daemon writes an `.ips` entry under
+* `~/Library/Logs/DiagnosticReports/` named like
+* `<AppName>_<timestamp>_<host>.ips`. The next time the user opens the
+* Console app (or the crash-reporter dialog appears) those entries
+* show up as "<App> quit unexpectedly" even though the quit was
+* deliberate.
+*
+* This adapter matches by the basename of `Probe.executablePath` and
+* deletes every report whose filename starts with that basename,
+* followed by an underscore. We only touch files under the user's
+* DiagnosticReports directory; the system-wide `/Library/Logs/...`
+* archive is root-owned and out of scope.
+*
+* Note that this does NOT suppress the modal "quit unexpectedly"
+* dialog that fires immediately when a process crashes: that is
+* displayed before any cleanup hook runs. For that case, let the
+* `apple_event_quit` stage resolve the quit cleanly instead of
+* escalating to SIGTERM/SIGKILL.
+*/
+const crashReporter = {
+	name: "crashReporter",
+	matches(probe) {
+		return probe.platform === "darwin" && typeof probe.executablePath === "string";
+	},
+	async clearCrashState(probe) {
+		if (!probe.executablePath) return;
+		const appName = basename(probe.executablePath);
+		if (!appName) return;
+		const dir = join(homedir(), "Library", "Logs", "DiagnosticReports");
+		if (!(await stat(dir).catch(() => void 0))?.isDirectory()) return;
+		const entries = await readdir(dir);
+		const prefix = `${appName}_`;
+		const removals = entries.filter((name) => name.startsWith(prefix) && (name.endsWith(".ips") || name.endsWith(".crash"))).map((name) => rm(join(dir, name), { force: true }));
+		await Promise.all(removals);
+	}
+};
+//#endregion
+//#region src/adapters/firefox.ts
+const FIREFOX_BASENAMES = [
+	"firefox",
+	"Firefox",
+	"firefox-bin"
+];
+/**
+* Stub adapter for Firefox.
+*
+* Matches by executable basename. The real `clearCrashState` deletes
+* the profile's `sessionstore-backups/recovery.jsonlz4` so the next
+* launch does not offer session restore. Per-OS profile-dir detection
+* and lz4 handling ship in a follow-up.
+*
+* Until then `clearCrashState` emits a warning and returns.
+*/
+const firefox = {
+	name: "firefox",
+	matches(probe) {
+		const exe = probe.executablePath ? basename(probe.executablePath) : void 0;
+		return exe ? FIREFOX_BASENAMES.includes(exe) : false;
+	},
+	clearCrashState(_probe) {
+		console.warn("uncontainerizable: firefox.clearCrashState is a stub; the next launch may prompt to restore the previous session. Track the real implementation in a follow-up release.");
+	}
+};
+//#endregion
+//#region src/adapters/index.ts
+/**
+* The bundle a typical browser-supervising caller wants: every built-in
+* adapter, in an order that doesn't matter (hook invocation is
+* idempotent and non-overlapping across adapters).
+*/
+const defaultAdapters = [
+	chromium,
+	firefox,
+	appkit,
+	crashReporter
+];
+//#endregion
+export { appkit as a, chromium as i, firefox as n, crashReporter as r, defaultAdapters as t };
+
+//# sourceMappingURL=adapters-BYLFpYWC.mjs.map

package/dist/adapters-BYLFpYWC.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters-BYLFpYWC.mjs","names":[],"sources":["../src/adapters/appkit.ts","../src/adapters/chromium.ts","../src/adapters/crash-reporter.ts","../src/adapters/firefox.ts","../src/adapters/index.ts"],"sourcesContent":["import { rm } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\n\nimport type { Adapter, Probe } from \"#/types.js\";\n\n/**\n * Deletes the AppKit \"Saved Application State\" directory for the managed\n * app after a terminal-stage destroy.\n *\n * macOS's AppKit persists a per-app snapshot of open windows and the\n * \"should reopen windows on next launch\" hint at\n * `~/Library/Saved Application State/<bundleId>.savedState/`. When an\n * app is force-killed (our SIGTERM/SIGKILL ladder), AppKit interprets\n * the missing clean-shutdown marker as a crash and shows the\n * \"Reopen windows?\" dialog next launch. Wiping the directory suppresses\n * the dialog.\n *\n * Only matches on darwin probes that carry a resolved `bundleId`.\n * Programs spawned without bundle-ID resolution (anything outside\n * `lsappinfo`'s knowledge of launched apps, for example `sleep` or a\n * manually-compiled binary) silently skip.\n */\nexport const appkit: Adapter = {\n  name: \"appkit\",\n\n  matches(probe: Probe): boolean {\n    return probe.platform === \"darwin\" && typeof probe.bundleId === \"string\";\n  },\n\n  async clearCrashState(probe: Probe): Promise<void> {\n    if (!probe.bundleId) {\n      return;\n    }\n    const dir = join(\n      homedir(),\n      \"Library\",\n      \"Saved Application State\",\n      `${probe.bundleId}.savedState`\n    );\n    await rm(dir, { recursive: true, force: true });\n  },\n};\n","import { basename } from \"node:path\";\n\nimport type { Adapter, Probe } from \"#/types.js\";\n\nconst CHROMIUM_BASENAMES = [\n  \"chrome\",\n  \"chromium\",\n  \"Chromium\",\n  \"Google Chrome\",\n  \"brave\",\n  \"Brave Browser\",\n  \"msedge\",\n  \"Microsoft Edge\",\n];\n\n/**\n * Stub adapter for Chromium-family browsers.\n *\n * Matches by executable basename (case-sensitive, since bundle exe names\n * are preserved verbatim). The real `clearCrashState` implementation\n * edits the \"Last Exit Type\" key in the browser's `Preferences` JSON so\n * the next launch does not prompt the user to restore a crashed\n * session. That implementation needs per-OS profile-dir detection and\n * careful JSON editing; it ships in a follow-up.\n *\n * Until then `clearCrashState` emits a warning and returns. The adapter\n * still matches so callers wiring it in can see the \"didn't run\" signal\n * and swap in a real cleanup when the full version ships.\n */\nexport const chromium: Adapter = {\n  name: \"chromium\",\n\n  matches(probe: Probe): boolean {\n    const exe = probe.executablePath\n      ? basename(probe.executablePath)\n      : undefined;\n    return exe ? CHROMIUM_BASENAMES.includes(exe) : false;\n  },\n\n  clearCrashState(_probe: Probe): void {\n    console.warn(\n      \"uncontainerizable: chromium.clearCrashState is a stub; the next launch may show a 'didn't shut down correctly' dialog. Track the real implementation in a follow-up release.\"\n    );\n  },\n};\n","import { readdir, rm, stat } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { basename, join } from \"node:path\";\n\nimport type { Adapter, Probe } from \"#/types.js\";\n\n/**\n * Deletes per-app crash reports from macOS's user-level CrashReporter\n * archive after a terminal-stage destroy.\n *\n * When our SIGTERM/SIGKILL ladder kills an app, macOS's `ReportCrash`\n * daemon writes an `.ips` entry under\n * `~/Library/Logs/DiagnosticReports/` named like\n * `<AppName>_<timestamp>_<host>.ips`. The next time the user opens the\n * Console app (or the crash-reporter dialog appears) those entries\n * show up as \"<App> quit unexpectedly\" even though the quit was\n * deliberate.\n *\n * This adapter matches by the basename of `Probe.executablePath` and\n * deletes every report whose filename starts with that basename,\n * followed by an underscore. We only touch files under the user's\n * DiagnosticReports directory; the system-wide `/Library/Logs/...`\n * archive is root-owned and out of scope.\n *\n * Note that this does NOT suppress the modal \"quit unexpectedly\"\n * dialog that fires immediately when a process crashes: that is\n * displayed before any cleanup hook runs. For that case, let the\n * `apple_event_quit` stage resolve the quit cleanly instead of\n * escalating to SIGTERM/SIGKILL.\n */\nexport const crashReporter: Adapter = {\n  name: \"crashReporter\",\n\n  matches(probe: Probe): boolean {\n    return (\n      probe.platform === \"darwin\" && typeof probe.executablePath === \"string\"\n    );\n  },\n\n  async clearCrashState(probe: Probe): Promise<void> {\n    if (!probe.executablePath) {\n      return;\n    }\n    const appName = basename(probe.executablePath);\n    if (!appName) {\n      return;\n    }\n    const dir = join(homedir(), \"Library\", \"Logs\", \"DiagnosticReports\");\n    // `fs.stat` rejects if the path doesn't exist. A fresh user account\n    // may not have a DiagnosticReports directory, so probe first and\n    // short-circuit if it's missing or not a directory. Swallowing the\n    // reject into `undefined` keeps the happy path straight-line.\n    const stats = await stat(dir).catch(() => undefined);\n    if (!stats?.isDirectory()) {\n      return;\n    }\n    const entries = await readdir(dir);\n    const prefix = `${appName}_`;\n    const removals = entries\n      .filter(\n        (name) =>\n          name.startsWith(prefix) &&\n          (name.endsWith(\".ips\") || name.endsWith(\".crash\"))\n      )\n      .map((name) => rm(join(dir, name), { force: true }));\n    await Promise.all(removals);\n  },\n};\n","import { basename } from \"node:path\";\n\nimport type { Adapter, Probe } from \"#/types.js\";\n\nconst FIREFOX_BASENAMES = [\"firefox\", \"Firefox\", \"firefox-bin\"];\n\n/**\n * Stub adapter for Firefox.\n *\n * Matches by executable basename. The real `clearCrashState` deletes\n * the profile's `sessionstore-backups/recovery.jsonlz4` so the next\n * launch does not offer session restore. Per-OS profile-dir detection\n * and lz4 handling ship in a follow-up.\n *\n * Until then `clearCrashState` emits a warning and returns.\n */\nexport const firefox: Adapter = {\n  name: \"firefox\",\n\n  matches(probe: Probe): boolean {\n    const exe = probe.executablePath\n      ? basename(probe.executablePath)\n      : undefined;\n    return exe ? FIREFOX_BASENAMES.includes(exe) : false;\n  },\n\n  clearCrashState(_probe: Probe): void {\n    console.warn(\n      \"uncontainerizable: firefox.clearCrashState is a stub; the next launch may prompt to restore the previous session. Track the real implementation in a follow-up release.\"\n    );\n  },\n};\n","import { appkit } from \"#/adapters/appkit.js\";\nimport { chromium } from \"#/adapters/chromium.js\";\nimport { crashReporter } from \"#/adapters/crash-reporter.js\";\nimport { firefox } from \"#/adapters/firefox.js\";\nimport type { Adapter } from \"#/types.js\";\n\nexport { appkit } from \"#/adapters/appkit.js\";\nexport { chromium } from \"#/adapters/chromium.js\";\nexport { crashReporter } from \"#/adapters/crash-reporter.js\";\nexport { firefox } from \"#/adapters/firefox.js\";\n\n/**\n * The bundle a typical browser-supervising caller wants: every built-in\n * adapter, in an order that doesn't matter (hook invocation is\n * idempotent and non-overlapping across adapters).\n */\nexport const defaultAdapters: readonly Adapter[] = [\n  chromium,\n  firefox,\n  appkit,\n  crashReporter,\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,SAAkB;CAC7B,MAAM;CAEN,QAAQ,OAAuB;AAC7B,SAAO,MAAM,aAAa,YAAY,OAAO,MAAM,aAAa;;CAGlE,MAAM,gBAAgB,OAA6B;AACjD,MAAI,CAAC,MAAM,SACT;AAQF,QAAM,GANM,KACV,SAAS,EACT,WACA,2BACA,GAAG,MAAM,SAAS,aACnB,EACa;GAAE,WAAW;GAAM,OAAO;GAAM,CAAC;;CAElD;;;ACtCD,MAAM,qBAAqB;CACzB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;AAgBD,MAAa,WAAoB;CAC/B,MAAM;CAEN,QAAQ,OAAuB;EAC7B,MAAM,MAAM,MAAM,iBACd,SAAS,MAAM,eAAe,GAC9B,KAAA;AACJ,SAAO,MAAM,mBAAmB,SAAS,IAAI,GAAG;;CAGlD,gBAAgB,QAAqB;AACnC,UAAQ,KACN,+KACD;;CAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;ACdD,MAAa,gBAAyB;CACpC,MAAM;CAEN,QAAQ,OAAuB;AAC7B,SACE,MAAM,aAAa,YAAY,OAAO,MAAM,mBAAmB;;CAInE,MAAM,gBAAgB,OAA6B;AACjD,MAAI,CAAC,MAAM,eACT;EAEF,MAAM,UAAU,SAAS,MAAM,eAAe;AAC9C,MAAI,CAAC,QACH;EAEF,MAAM,MAAM,KAAK,SAAS,EAAE,WAAW,QAAQ,oBAAoB;AAMnE,MAAI,EADU,MAAM,KAAK,IAAI,CAAC,YAAY,KAAA,EAAU,GACxC,aAAa,CACvB;EAEF,MAAM,UAAU,MAAM,QAAQ,IAAI;EAClC,MAAM,SAAS,GAAG,QAAQ;EAC1B,MAAM,WAAW,QACd,QACE,SACC,KAAK,WAAW,OAAO,KACtB,KAAK,SAAS,OAAO,IAAI,KAAK,SAAS,SAAS,EACpD,CACA,KAAK,SAAS,GAAG,KAAK,KAAK,KAAK,EAAE,EAAE,OAAO,MAAM,CAAC,CAAC;AACtD,QAAM,QAAQ,IAAI,SAAS;;CAE9B;;;AC/DD,MAAM,oBAAoB;CAAC;CAAW;CAAW;CAAc;;;;;;;;;;;AAY/D,MAAa,UAAmB;CAC9B,MAAM;CAEN,QAAQ,OAAuB;EAC7B,MAAM,MAAM,MAAM,iBACd,SAAS,MAAM,eAAe,GAC9B,KAAA;AACJ,SAAO,MAAM,kBAAkB,SAAS,IAAI,GAAG;;CAGjD,gBAAgB,QAAqB;AACnC,UAAQ,KACN,0KACD;;CAEJ;;;;;;;;ACfD,MAAa,kBAAsC;CACjD;CACA;CACA;CACA;CACD"}

package/dist/index-B1y4yb1N.d.mts

@@ -0,0 +1,132 @@
+import { JsContainOptions, JsDestroyOptions, JsDestroyResult, JsProbe, JsQuitOptions, JsQuitResult, JsStageResult, NodeContainer } from "@uncontainerizable/native";
+
+//#region src/types.d.ts
+type SupportedPlatform = "linux" | "darwin" | "win32";
+type QuitOptions = JsQuitOptions;
+type DestroyOptions = JsDestroyOptions;
+type QuitResult = JsQuitResult;
+type DestroyResult = JsDestroyResult;
+type StageResult = JsStageResult;
+type Probe = JsProbe;
+/**
+ * Platform-agnostic handle for a spawned contained process. Returned by
+ * `App.contain`; backed by the napi-generated `NodeContainer` class.
+ */
+type Container = NodeContainer;
+/**
+ * Per-app lifecycle hook. Each method except `name` and `matches` is
+ * optional; unimplemented hooks are skipped by the Rust orchestrator.
+ *
+ * Every hook may return a value or a Promise; the TypeScript wrapper
+ * normalizes both forms to `Promise<_>` before handing the adapter to
+ * the napi bridge. Hooks must not throw synchronously: a thrown value
+ * is trapped by the bridge and recorded in
+ * `QuitResult.adapterErrors`, but ergonomic code should prefer
+ * returning a rejected Promise.
+ */
+type Adapter = {
+  readonly name: string;
+  matches(probe: Probe): boolean | Promise<boolean>;
+  beforeQuit?(probe: Probe): void | Promise<void>;
+  beforeStage?(probe: Probe, stageName: string): void | Promise<void>;
+  afterStage?(probe: Probe, result: StageResult): void | Promise<void>;
+  afterQuit?(probe: Probe, result: QuitResult): void | Promise<void>;
+  clearCrashState?(probe: Probe): void | Promise<void>;
+};
+/**
+ * Extends the napi-generated options with a TypeScript-only `adapters`
+ * field. The wrapper normalizes each adapter's hook methods to the
+ * async signatures the napi bridge expects before crossing the
+ * boundary.
+ */
+type ContainOptions = Omit<JsContainOptions, "adapters"> & {
+  adapters?: Adapter[];
+};
+//#endregion
+//#region src/adapters/appkit.d.ts
+/**
+ * Deletes the AppKit "Saved Application State" directory for the managed
+ * app after a terminal-stage destroy.
+ *
+ * macOS's AppKit persists a per-app snapshot of open windows and the
+ * "should reopen windows on next launch" hint at
+ * `~/Library/Saved Application State/<bundleId>.savedState/`. When an
+ * app is force-killed (our SIGTERM/SIGKILL ladder), AppKit interprets
+ * the missing clean-shutdown marker as a crash and shows the
+ * "Reopen windows?" dialog next launch. Wiping the directory suppresses
+ * the dialog.
+ *
+ * Only matches on darwin probes that carry a resolved `bundleId`.
+ * Programs spawned without bundle-ID resolution (anything outside
+ * `lsappinfo`'s knowledge of launched apps, for example `sleep` or a
+ * manually-compiled binary) silently skip.
+ */
+declare const appkit: Adapter;
+//#endregion
+//#region src/adapters/chromium.d.ts
+/**
+ * Stub adapter for Chromium-family browsers.
+ *
+ * Matches by executable basename (case-sensitive, since bundle exe names
+ * are preserved verbatim). The real `clearCrashState` implementation
+ * edits the "Last Exit Type" key in the browser's `Preferences` JSON so
+ * the next launch does not prompt the user to restore a crashed
+ * session. That implementation needs per-OS profile-dir detection and
+ * careful JSON editing; it ships in a follow-up.
+ *
+ * Until then `clearCrashState` emits a warning and returns. The adapter
+ * still matches so callers wiring it in can see the "didn't run" signal
+ * and swap in a real cleanup when the full version ships.
+ */
+declare const chromium: Adapter;
+//#endregion
+//#region src/adapters/crash-reporter.d.ts
+/**
+ * Deletes per-app crash reports from macOS's user-level CrashReporter
+ * archive after a terminal-stage destroy.
+ *
+ * When our SIGTERM/SIGKILL ladder kills an app, macOS's `ReportCrash`
+ * daemon writes an `.ips` entry under
+ * `~/Library/Logs/DiagnosticReports/` named like
+ * `<AppName>_<timestamp>_<host>.ips`. The next time the user opens the
+ * Console app (or the crash-reporter dialog appears) those entries
+ * show up as "<App> quit unexpectedly" even though the quit was
+ * deliberate.
+ *
+ * This adapter matches by the basename of `Probe.executablePath` and
+ * deletes every report whose filename starts with that basename,
+ * followed by an underscore. We only touch files under the user's
+ * DiagnosticReports directory; the system-wide `/Library/Logs/...`
+ * archive is root-owned and out of scope.
+ *
+ * Note that this does NOT suppress the modal "quit unexpectedly"
+ * dialog that fires immediately when a process crashes: that is
+ * displayed before any cleanup hook runs. For that case, let the
+ * `apple_event_quit` stage resolve the quit cleanly instead of
+ * escalating to SIGTERM/SIGKILL.
+ */
+declare const crashReporter: Adapter;
+//#endregion
+//#region src/adapters/firefox.d.ts
+/**
+ * Stub adapter for Firefox.
+ *
+ * Matches by executable basename. The real `clearCrashState` deletes
+ * the profile's `sessionstore-backups/recovery.jsonlz4` so the next
+ * launch does not offer session restore. Per-OS profile-dir detection
+ * and lz4 handling ship in a follow-up.
+ *
+ * Until then `clearCrashState` emits a warning and returns.
+ */
+declare const firefox: Adapter;
+//#endregion
+//#region src/adapters/index.d.ts
+/**
+ * The bundle a typical browser-supervising caller wants: every built-in
+ * adapter, in an order that doesn't matter (hook invocation is
+ * idempotent and non-overlapping across adapters).
+ */
+declare const defaultAdapters: readonly Adapter[];
+//#endregion
+export { appkit as a, Container as c, Probe as d, QuitOptions as f, SupportedPlatform as h, chromium as i, DestroyOptions as l, StageResult as m, firefox as n, Adapter as o, QuitResult as p, crashReporter as r, ContainOptions as s, defaultAdapters as t, DestroyResult as u };
+//# sourceMappingURL=index-B1y4yb1N.d.mts.map

package/dist/index-B1y4yb1N.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-B1y4yb1N.d.mts","names":[],"sources":["../src/types.ts","../src/adapters/appkit.ts","../src/adapters/chromium.ts","../src/adapters/crash-reporter.ts","../src/adapters/firefox.ts","../src/adapters/index.ts"],"mappings":";;;KAWY,iBAAA;AAAA,KAEA,WAAA,GAAc,aAAA;AAAA,KACd,cAAA,GAAiB,gBAAA;AAAA,KACjB,UAAA,GAAa,YAAA;AAAA,KACb,aAAA,GAAgB,eAAA;AAAA,KAChB,WAAA,GAAc,aAAA;AAAA,KACd,KAAA,GAAQ,OAAA;AALpB;;;;AAAA,KAWY,SAAA,GAAY,aAAA;AAVxB;;;;;AACA;;;;;AACA;AAFA,KAuBY,OAAA;EAAA,SACD,IAAA;EACT,OAAA,CAAQ,KAAA,EAAO,KAAA,aAAkB,OAAA;EACjC,UAAA,EAAY,KAAA,EAAO,KAAA,UAAe,OAAA;EAClC,WAAA,EAAa,KAAA,EAAO,KAAA,EAAO,SAAA,kBAA2B,OAAA;EACtD,UAAA,EAAY,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,WAAA,UAAqB,OAAA;EACvD,SAAA,EAAW,KAAA,EAAO,KAAA,EAAO,MAAA,EAAQ,UAAA,UAAoB,OAAA;EACrD,eAAA,EAAiB,KAAA,EAAO,KAAA,UAAe,OAAA;AAAA;AA1BzC;;;;;AAMA;AANA,KAmCY,cAAA,GAAiB,IAAA,CAAK,gBAAA;EAChC,QAAA,GAAW,OAAA;AAAA;;;;;AA3Cb;;;;;AAEA;;;;;AACA;;;;;cCSa,MAAA,EAAQ,OAAA;;;;;ADZrB;;;;;AAEA;;;;;AACA;;cEea,QAAA,EAAU,OAAA;;;;;AFlBvB;;;;;AAEA;;;;;AACA;;;;;AACA;;;;;AACA;;cGca,aAAA,EAAe,OAAA;;;;;AHnB5B;;;;;AAEA;;;cIGa,OAAA,EAAS,OAAA;;;;;;AJHtB;;cKGa,eAAA,WAA0B,OAAA"}

package/dist/index.d.mts

@@ -1,7 +1,29 @@
+import { a as appkit, c as Container, d as Probe, f as QuitOptions, h as SupportedPlatform, i as chromium, l as DestroyOptions, m as StageResult, n as firefox, o as Adapter, p as QuitResult, r as crashReporter, s as ContainOptions, t as defaultAdapters, u as DestroyResult } from "./index-B1y4yb1N.mjs";
 import { coreVersion } from "@uncontainerizable/native";
 
-//#region src/types.d.ts
-type SupportedPlatform = "linux" | "darwin" | "win32";
+//#region src/index.d.ts
+/**
+ * Namespaced handle for spawning contained processes.
+ *
+ * Construct once per application, typically with a reverse-DNS string like
+ * `"com.example.my-supervisor"`. The prefix namespaces identity strings so
+ * two unrelated libraries using `uncontainerizable` cannot collide.
+ *
+ * Throws `INVALID_IDENTITY` if the prefix contains characters outside
+ * `[A-Za-z0-9._:-]`.
+ */
+declare class App {
+  #private;
+  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.
+   */
+  contain(command: string, options?: ContainOptions): Promise<Container>;
+}
 //#endregion
-export { type SupportedPlatform, coreVersion };
+export { type Adapter, App, type ContainOptions, type Container, type DestroyOptions, type DestroyResult, type Probe, type QuitOptions, type QuitResult, type StageResult, type SupportedPlatform, appkit, chromium, coreVersion, crashReporter, defaultAdapters, firefox };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;;KAAY,iBAAA"}
+{"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"}

package/dist/index.mjs

@@ -1,3 +1,66 @@
-import { coreVersion } from "@uncontainerizable/native";
+import { a as appkit, i as chromium, n as firefox, r as crashReporter, t as defaultAdapters } from "./adapters-BYLFpYWC.mjs";
+import { NodeApp, coreVersion } from "@uncontainerizable/native";
+//#region src/index.ts
+/**
+* Namespaced handle for spawning contained processes.
+*
+* Construct once per application, typically with a reverse-DNS string like
+* `"com.example.my-supervisor"`. The prefix namespaces identity strings so
+* two unrelated libraries using `uncontainerizable` cannot collide.
+*
+* Throws `INVALID_IDENTITY` if the prefix contains characters outside
+* `[A-Za-z0-9._:-]`.
+*/
+var App = class {
+	#inner;
+	constructor(prefix) {
+		this.#inner = new NodeApp(prefix);
+	}
+	get prefix() {
+		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.
+	*/
+	contain(command, options = {}) {
+		const { adapters, ...nativeOpts } = options;
+		return this.#inner.contain(command, {
+			...nativeOpts,
+			adapters: adapters?.map(normalizeAdapter)
+		});
+	}
+};
+/**
+* Normalize a user-provided `Adapter` (which may declare sync methods)
+* into the always-async shape the napi bridge expects. Every optional
+* hook is only forwarded if defined, so the Rust side keeps its
+* "undefined means skip" semantics.
+*/
+function normalizeAdapter(adapter) {
+	return {
+		name: adapter.name,
+		matches: async (probe) => Boolean(await adapter.matches(probe)),
+		beforeQuit: adapter.beforeQuit ? async (probe) => {
+			await adapter.beforeQuit?.(probe);
+		} : void 0,
+		beforeStage: adapter.beforeStage ? async (probe, stageName) => {
+			await adapter.beforeStage?.(probe, stageName);
+		} : void 0,
+		afterStage: adapter.afterStage ? async (probe, result) => {
+			await adapter.afterStage?.(probe, result);
+		} : void 0,
+		afterQuit: adapter.afterQuit ? async (probe, result) => {
+			await adapter.afterQuit?.(probe, result);
+		} : void 0,
+		clearCrashState: adapter.clearCrashState ? async (probe) => {
+			await adapter.clearCrashState?.(probe);
+		} : void 0
+	};
+}
+//#endregion
+export { App, appkit, chromium, coreVersion, crashReporter, defaultAdapters, firefox };
 
-export { coreVersion };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uncontainerizable",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "description": "Graceful process lifecycle for programs that can't be containerized",
   "keywords": [
     "lifecycle",
@@ -41,12 +41,12 @@
     "provenance": true
   },
   "dependencies": {
-    "@uncontainerizable/native": "0.0.3"
+    "@uncontainerizable/native": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^24",
     "publint": "^0.3",
-    "tsdown": "^0.20",
+    "tsdown": "^0.21.7",
     "typescript": "^6",
     "vitest": "^4",
     "@uncontainerizable/tsconfig": "0.0.0"