@ajnart/self-host-testkit 0.0.0-stage → 1.2.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,287 @@
-# Temporary Holding Version
+# @ajnart/self-host-testkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Real, isolated Docker App fixtures for TypeScript and JavaScript integration
+tests. Start an App through self-host's existing Setup, call its API, and close
+the fixture. ESM only: use `import`, not CommonJS `require`. No runtime npm
+dependencies and no test-runner dependency.
+
+## Before you start
+
+You need **Node.js 22+**, a running local **Docker Engine** and the **Docker
+Compose v2 plugin** (`docker compose version`). Linux and macOS x64/arm64 are
+supported; Docker must use a local Unix socket and enforce memory, CPU and PID
+limits. Allow up to 5 GiB RAM and five CPUs per fixture, plus image/storage space.
+First startup pulls images and can take several minutes.
+
+For a published release, install the SDK as a dev dependency. Version 1.2.1 must
+exist on npm and GitHub before using these commands; for an unpublished source
+checkout, use the source workflow linked below instead:
+
+```bash
+npm install --save-dev @ajnart/self-host-testkit@1.2.1
+```
+
+This guide describes version 1.2.1. The older v1.2.0 tarball does not contain the setup command,
+`TestkitError` export or safe startup reasons. For that release, extract
+`self-host-testkit` from its platform archive, verify `checksums.txt`, and set
+`SELF_HOST_TESTKIT_BINARY` to the helper's absolute path. For the improved source,
+follow the [checkout quickstart](../README.md#typescript-install).
+
+Version 1.2.0 used the unpublished package name `@self-host/testkit`. When
+upgrading, change imports to `@ajnart/self-host-testkit`. The exact npm package
+is also available as `self-host-testkit-1.2.1.tgz` on the matching GitHub release.
+
+## Install the matching helper
+
+After installing the SDK, run:
+
+```bash
+npm exec -- self-host-testkit-setup
+```
+
+This explicit setup downloads only the matching Linux/macOS helper, requires one
+SHA-256 checksum entry and verifies the archive before extraction. It caches the
+helper privately under `$XDG_CACHE_HOME/self-host-testkit/`, or
+`~/.cache/self-host-testkit/`. It does not run Docker, modify PATH, require Go, or
+download anything during package installation or import. Repeating setup reuses
+the cached helper. `createSelfHost()` discovers it automatically.
+
+To use a source-built or offline helper instead:
+
+```bash
+export SELF_HOST_TESTKIT_BINARY=/absolute/path/to/self-host-testkit
+```
+
+Resolution order: `binary` option, `SELF_HOST_TESTKIT_BINARY`, the versioned
+private cache, then `self-host-testkit` on PATH. Keep SDK, helper and Action on
+the same release or immutable source commit. Never substitute the normal
+`self-host` CLI: the helper is a separate executable.
+
+## A small demo
+
+Save this as `demo.mjs` and run `node demo.mjs` after installing the SDK/helper:
+
+```javascript
+import { createSelfHost } from "@ajnart/self-host-testkit";
+
+const selfHost = createSelfHost();
+try {
+  const sonarr = await selfHost.spinup("sonarr");
+  const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
+    headers: { "X-Api-Key": await sonarr.getApiKey() },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) throw new Error("Sonarr rejected the request");
+  const status = await response.json();
+  if (status.appName !== "Sonarr") throw new Error("Unexpected App identity");
+  console.log(`Connected to Sonarr ${status.version}`);
+} finally {
+  await selfHost.close();
+}
+```
+
+The package also includes `examples/sonarr.mjs`. No API key appears in its output.
+Cleanup uses ordinary `try/finally` or test-runner hooks, without requiring
+TypeScript disposable libraries or newer JavaScript syntax.
+
+## Vitest
+
+Use your project's existing Vitest dependency. Set hook timeouts explicitly;
+the default hook timeout is too short for image pulls and Setup.
+
+```typescript
+import { afterAll, beforeAll, expect, test } from "vitest";
+import { createSelfHost, type App } from "@ajnart/self-host-testkit";
+
+const selfHost = createSelfHost();
+let sonarr: App;
+
+beforeAll(async () => {
+  sonarr = await selfHost.spinup("sonarr");
+}, 780_000);
+
+afterAll(async () => {
+  await selfHost.close();
+}, 160_000);
+
+test("Sonarr returns its authenticated identity", async () => {
+  const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
+    headers: { "X-Api-Key": await sonarr.getApiKey() },
+    signal: AbortSignal.timeout(10_000),
+  });
+  expect(response.ok).toBe(true);
+  const status = await response.json();
+  expect(status.appName).toBe("Sonarr");
+  expect(status.version).toMatch(/^\d+\./);
+});
+```
+
+This verifies identity, not complete integration acceptance. Your adapter tests
+should also check meaningful data and invalid-key behavior. Do not print raw
+response bodies, credentials or API keys in failing assertions.
+
+## API
+
+```typescript
+const selfHost = createSelfHost({
+  timeoutMs: 720_000,
+});
+const app = await selfHost.spinup("sonarr", {
+  image: "lscr.io/linuxserver/sonarr:latest",
+});
+const apiKey = await app.getApiKey();
+const credentials = await app.credentials();
+const info = await app.info();
+await app.close();
+await selfHost.close();
+```
+
+- `createSelfHost({ binary?, timeoutMs?, manifest? })`: creates a fixture manager
+  without starting Docker. `timeoutMs` defaults to 720,000 and accepts 1–840,000.
+  It bounds the App lifetime, not just startup; cleanup time is reserved within
+  that budget. Do not share a fixture across a longer-running suite.
+- `spinup(id, { image? })`: awaits Setup and returns an App with its loopback
+  `url`. Each call gets a separate helper and Project; image overrides apply to
+  the selected App, not its dependency images.
+- `getApiKey(name?)`: explicitly reads a private key; the default name is
+  `api_key`. Use the App's declared key name when it differs.
+- `credentials()`: `username`, `password`, `email`, `apiKey`. Fields are
+  non-enumerable and JSON/inspection redact the object, but reading a field
+  returns the actual secret. Never log it or upload it.
+- `info()`: public `id`, `url`, `image`, `imageId`, `repoDigests`. Record image
+  digests when reproducibility matters; `latest` is deliberately mutable.
+- `app.close()` closes one fixture; `selfHost.close()` closes all its fixtures.
+  Both are idempotent. Successful cleanup removes owned containers, networks,
+  anonymous container volumes and private storage. Named volumes are rejected.
+- `manifest`: optional absolute recovery filename in an existing owned mode-0700
+  directory. Otherwise the SDK creates a private temporary parent. The helper
+  records ownership before startup. Keep recovery manifests and Project data
+  private; never upload them as public CI artifacts.
+
+## Errors and recovery
+
+```typescript
+import { TestkitError } from "@ajnart/self-host-testkit";
+
+try {
+  await selfHost.spinup("sonarr");
+} catch (error: unknown) {
+  if (error instanceof TestkitError && error.code === "BINARY") {
+    throw new Error(
+      "Install the matching testkit helper before running this suite",
+    );
+  }
+  throw error;
+}
+```
+
+Errors expose a sanitized `code`: `BINARY`, `PROTOCOL`, `STATE`, `START`,
+`CREDENTIALS`, `INFO`, `CLEANUP`, `TIMEOUT` or `TRANSPORT`. They never include raw
+provider output, helper stderr or executable paths. A `START` error may also
+have an allowlisted `reason` and a corresponding safe hint: `APP`, `OPTIONS`,
+`DOCKER`, `CAPABILITIES`, `PORT`, `OWNERSHIP`, `LIMITS`, `LOCK`, `UNSUPPORTED`,
+`STORAGE`, `CONTAINER` or `SETUP`. These distinguish unsupported fixtures from
+failed Setup without forwarding provider messages.
+
+- **BINARY:** run the explicit setup command or set the helper path.
+- **START:** check local Docker/Compose, supported App prerequisites, resource
+  limits and image availability. Apps needing a Manual step, hardware, external
+  account, host networking, socket mount or named volume fail rather than skip.
+- **TIMEOUT:** allow cold-pull time within the bounded lifetime, lower concurrent
+  fixture count, or use a smaller supported App.
+- **CLEANUP:** retain the private manifest and retry scoped recovery after helper
+  exit. For CI, use the always-run step below. For local recovery, pass the
+  matching helper `--cleanup-manifest /absolute/private/manifest.jsonl`.
+
+If you supply a manifest, retain its path outside the test for recovery. SIGKILL,
+runner loss and daemon outages can prevent cleanup; disposable runners are best.
+Do not run Docker prune or broad container/volume removal to recover fixtures.
+
+## GitHub Actions
+
+```yaml
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npm ci
+      - id: testkit
+        uses: ajnart/self-host/testkit@v1.2.1
+      - run: npx vitest run path/to/live-integration.test.ts
+      - name: Clean up owned fixtures
+        if: always() && steps.testkit.outcome == 'success'
+        run: '"$SELF_HOST_TESTKIT_BINARY" --cleanup-manifest "$SELF_HOST_TESTKIT_MANIFEST"'
+```
+
+Pin the Action to a full commit SHA and install the SDK from the same source or
+release. The Action requires Bash, Python 3 and tar; it verifies and extracts a
+patched Go toolchain privately for its own build without changing the caller's
+PATH or `GOTOOLCHAIN`. It does not require a preinstalled Go launcher and works
+when the caller sets `GOSUMDB=off`. Standard GitHub-hosted Ubuntu runners supply
+these prerequisites.
+The original v1.2.0 Action does not yet preserve the caller's Go environment.
+
+Outputs: `binary-path`, `sdk-path`, `manifest-path`. Job environment:
+`SELF_HOST_TESTKIT_BINARY`, `SELF_HOST_TESTKIT_SDK`, `SELF_HOST_TESTKIT_MANIFEST`.
+The Action does not install the npm dependency or start Apps. Its committed SDK
+exports and source-built helper match its ref. Set bounded matrix concurrency;
+each simultaneous fixture adds its own resource budget. Always-run cleanup is
+mandatory because composite Actions have no finally hook.
+
+## Go
+
+```bash
+go get github.com/ajnart/self-host@v1.2.1
+```
+
+```go
+peer, err := testkit.Start(ctx, testkit.Options{App: "sonarr"})
+if err != nil {
+    return err
+}
+defer func() {
+    cleanup, cancel := context.WithTimeout(context.Background(), time.Minute)
+    defer cancel()
+    if err := peer.Close(cleanup); err != nil {
+        log.Print("fixture cleanup failed; retain its private recovery path")
+    }
+}()
+key, err := peer.GetAPIKey(ctx, "")
+```
+
+Import `github.com/ajnart/self-host/testkit`; it is part of the root module, not a
+separate Go module. `RecoveryPath()` is private operational metadata. Go startup
+errors preserve known safe testkit causes and context cancellation while hiding
+raw provider errors. The current source removes storage on successful `Close`;
+v1.2.0 retains it until a dead-process `Cleanup` pass.
+
+## Developing this package
+
+From the repository root:
+
+```bash
+bun install --frozen-lockfile
+bun run --cwd testkit/node build
+bun run --cwd testkit/node check
+bun run --cwd testkit/node lint
+bun test testkit/node/tests
+npm pack ./testkit/node --ignore-scripts --dry-run
+```
+
+`src/*.mts` is the source of truth. TypeScript generates the committed `.mjs`
+exports and `.d.mts` declarations; CI verifies they remain current. No hand-kept
+parallel declarations. The tarball includes only runtime modules, public types,
+license, README and the demo; it does not ship development dependencies or tests.
+`SELF_HOST_RELEASE_VERSION=X.Y.Z node testkit/node/pack.mjs` validates the package
+allowlist and adds its checksum to release artifacts. Build first. Version bumps
+and npm trusted publishing require a separate release decision; never overwrite
+v1.2.0 assets with a modified package.
+
+Backup/Restore caching and live Docker acceptance are deferred, not implied by
+passing SDK transport tests. The downstream Homarr weekly checklist is tracked
+in [draft PR #7446](https://github.com/homarr-labs/homarr/pull/7446).

package/binary.mjs

@@ -0,0 +1,40 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+const metadata = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+if (typeof metadata !== "object" ||
+    metadata === null ||
+    !("version" in metadata) ||
+    typeof metadata.version !== "string" ||
+    !/^\d+\.\d+\.\d+$/.test(metadata.version)) {
+    throw new Error("Invalid testkit package version.");
+}
+export const version = metadata.version;
+export function binaryDirectory() {
+    let cache = join(homedir(), ".cache");
+    if (process.env.XDG_CACHE_HOME && isAbsolute(process.env.XDG_CACHE_HOME)) {
+        cache = process.env.XDG_CACHE_HOME;
+    }
+    return join(cache, "self-host-testkit", version, `${process.platform}-${process.arch}`);
+}
+export function privateDirectory(path) {
+    const info = lstatSync(path);
+    return (info.isDirectory() &&
+        info.uid === process.getuid?.() &&
+        (info.mode & 0o077) === 0);
+}
+export function installedBinary() {
+    const directory = binaryDirectory();
+    const binary = join(directory, "self-host-testkit");
+    if (!existsSync(binary))
+        return "self-host-testkit";
+    const info = lstatSync(binary);
+    if (!privateDirectory(directory) ||
+        !info.isFile() ||
+        info.uid !== process.getuid?.() ||
+        (info.mode & 0o077) !== 0 ||
+        (info.mode & 0o100) === 0) {
+        throw new Error("Testkit helper cache is not private; set SELF_HOST_TESTKIT_BINARY explicitly.");
+    }
+    return binary;
+}

package/examples/sonarr.mjs

@@ -0,0 +1,20 @@
+import { createSelfHost } from "@ajnart/self-host-testkit";
+
+const selfHost = createSelfHost();
+
+try {
+	const sonarr = await selfHost.spinup("sonarr");
+	const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
+		headers: { "X-Api-Key": await sonarr.getApiKey() },
+		signal: AbortSignal.timeout(10_000),
+	});
+	if (!response.ok)
+		throw new Error("Sonarr rejected the authenticated request.");
+	const status = await response.json();
+	if (status.appName !== "Sonarr" || typeof status.version !== "string") {
+		throw new Error("Sonarr returned an unexpected identity.");
+	}
+	console.log(`Connected to Sonarr ${status.version}.`);
+} finally {
+	await selfHost.close();
+}

package/index.d.mts

@@ -0,0 +1,40 @@
+export interface Credentials {
+    readonly username: string;
+    readonly password: string;
+    readonly email: string;
+    readonly apiKey: string;
+}
+export interface AppInfo {
+    readonly id: string;
+    readonly url: string;
+    readonly image: string;
+    readonly imageId: string;
+    readonly repoDigests: string[];
+}
+export interface App {
+    readonly url: string;
+    getApiKey(name?: string): Promise<string>;
+    credentials(): Promise<Credentials>;
+    info(): Promise<AppInfo>;
+    close(): Promise<void>;
+}
+export interface SpinupOptions {
+    image?: string;
+}
+export interface SelfHost {
+    spinup(app: string, options?: SpinupOptions): Promise<App>;
+    close(): Promise<void>;
+}
+export interface SelfHostOptions {
+    binary?: string;
+    timeoutMs?: number;
+    manifest?: string;
+}
+export type TestkitErrorCode = "PROTOCOL" | "STATE" | "START" | "CREDENTIALS" | "INFO" | "CLEANUP" | "TIMEOUT" | "TRANSPORT" | "BINARY";
+export type TestkitStartupReason = "APP" | "OPTIONS" | "DOCKER" | "CAPABILITIES" | "PORT" | "OWNERSHIP" | "LIMITS" | "LOCK" | "UNSUPPORTED" | "STORAGE" | "CONTAINER" | "SETUP";
+export declare class TestkitError extends Error {
+    readonly code: TestkitErrorCode;
+    readonly reason: TestkitStartupReason | undefined;
+    constructor(code: TestkitErrorCode, reason?: TestkitStartupReason);
+}
+export declare function createSelfHost(options?: SelfHostOptions): SelfHost;

package/index.mjs

@@ -0,0 +1,441 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, rmdirSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { inspect } from "node:util";
+import { installedBinary } from "./binary.mjs";
+const MAX_MESSAGE = 65536;
+const CLEANUP_TIMEOUT = 50000;
+const messages = new Map([
+    ["PROTOCOL", "Invalid testkit protocol."],
+    ["STATE", "Fixture is not available."],
+    ["START", "Fixture startup failed."],
+    ["CREDENTIALS", "Fixture credentials are not available."],
+    ["INFO", "Fixture information is not available."],
+    ["CLEANUP", "Fixture cleanup failed; run manifest cleanup."],
+    ["TIMEOUT", "Fixture operation timed out."],
+    ["TRANSPORT", "Testkit helper transport failed."],
+    [
+        "BINARY",
+        "Testkit helper not found. Run self-host-testkit-setup or set SELF_HOST_TESTKIT_BINARY.",
+    ],
+]);
+const startupReasons = new Map([
+    ["APP", "Choose one supported Catalog App."],
+    ["OPTIONS", "Check the selected image and lifetime options."],
+    ["DOCKER", "Check the local Unix Docker socket, daemon and Compose plugin."],
+    ["CAPABILITIES", "Docker must support memory, CPU quota and PID limits."],
+    ["PORT", "A required local port could not be reserved."],
+    ["OWNERSHIP", "Fixture ownership or isolation could not be verified."],
+    [
+        "LIMITS",
+        "Container resource caps or selected image could not be verified.",
+    ],
+    ["LOCK", "The private startup lock is unavailable."],
+    [
+        "UNSUPPORTED",
+        "This App's Compose configuration or operations are unsupported.",
+    ],
+    [
+        "STORAGE",
+        "Private fixture storage or the recovery manifest is unavailable.",
+    ],
+    ["CONTAINER", "The selected App container is absent."],
+    ["SETUP", "App Setup failed or requires a Manual step."],
+]);
+export class TestkitError extends Error {
+    code;
+    reason;
+    constructor(code, reason) {
+        let message = messages.get(code);
+        if (code === "START" && reason)
+            message = `${message} ${startupReasons.get(reason)}`;
+        super(message);
+        this.name = "TestkitError";
+        this.code = code;
+        this.reason = reason;
+    }
+}
+function fault(code, reason) {
+    return new TestkitError(code, reason);
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function strings(value, fields) {
+    return (record(value) && fields.every((field) => typeof value[field] === "string"));
+}
+function privateCredentials(value) {
+    if (!strings(value, ["username", "password", "email", "apiKey"])) {
+        throw fault("PROTOCOL");
+    }
+    const credentials = Object.create(null);
+    for (const field of ["username", "password", "email", "apiKey"]) {
+        Object.defineProperty(credentials, field, { get: () => value[field] });
+    }
+    Object.defineProperty(credentials, "toJSON", {
+        value: () => "[Credentials]",
+    });
+    Object.defineProperty(credentials, inspect.custom, {
+        value: () => "[Credentials]",
+    });
+    return Object.freeze(credentials);
+}
+function runCleanup(binary, manifest, owner) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(binary, ["--cleanup-manifest", manifest, "--owner", owner], { stdio: "ignore" });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(fault("CLEANUP"));
+        }, CLEANUP_TIMEOUT);
+        child.once("error", () => {
+            clearTimeout(timer);
+            reject(fault("CLEANUP"));
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(undefined);
+            else
+                reject(fault("CLEANUP"));
+        });
+    });
+}
+class Bridge {
+    #child;
+    #binary;
+    #manifest;
+    #owner = randomBytes(16).toString("hex");
+    #pending = new Map();
+    #sequence = 0;
+    #buffer = Buffer.alloc(0);
+    #failed = false;
+    #closing;
+    #exited;
+    #spawned = false;
+    constructor(binary, manifest) {
+        this.#binary = binary;
+        this.#manifest = manifest;
+        this.#child = spawn(binary, ["--manifest", manifest, "--owner", this.#owner], { stdio: ["pipe", "pipe", "ignore"] });
+        this.#child.once("spawn", () => {
+            this.#spawned = true;
+        });
+        this.#exited = new Promise((resolve) => {
+            this.#child.once("exit", () => {
+                this.#fail("TRANSPORT");
+                resolve(undefined);
+            });
+            this.#child.once("error", (error) => {
+                let code = "TRANSPORT";
+                if (error.code === "ENOENT")
+                    code = "BINARY";
+                this.#fail(code);
+                resolve(undefined);
+            });
+        });
+        this.#child.stdin.on("error", () => this.#fail("TRANSPORT"));
+        this.#child.stdout.on("data", (chunk) => this.#receive(chunk));
+    }
+    #fail(code) {
+        this.#failed = true;
+        this.#buffer = Buffer.alloc(0);
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(fault(code));
+        }
+        this.#pending.clear();
+        this.#child.kill("SIGTERM");
+    }
+    #receive(chunk) {
+        if (this.#failed)
+            return;
+        if (this.#buffer.length + chunk.length > MAX_MESSAGE) {
+            this.#fail("PROTOCOL");
+            return;
+        }
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        let newline = this.#buffer.indexOf(10);
+        while (newline !== -1) {
+            const line = this.#buffer.subarray(0, newline).toString("utf8");
+            this.#buffer = this.#buffer.subarray(newline + 1);
+            try {
+                const response = JSON.parse(line);
+                if (!record(response) ||
+                    response.version !== 1 ||
+                    typeof response.id !== "number" ||
+                    !Number.isSafeInteger(response.id) ||
+                    !this.#pending.has(response.id) ||
+                    Object.hasOwn(response, "error") === Object.hasOwn(response, "result")) {
+                    throw fault("PROTOCOL");
+                }
+                const pending = this.#pending.get(response.id);
+                if (!pending)
+                    throw fault("PROTOCOL");
+                this.#pending.delete(response.id);
+                clearTimeout(pending.timer);
+                if (Object.hasOwn(response, "error")) {
+                    if (!record(response.error) ||
+                        typeof response.error.code !== "string" ||
+                        !isErrorCode(response.error.code)) {
+                        pending.reject(fault("PROTOCOL"));
+                        this.#fail("PROTOCOL");
+                        return;
+                    }
+                    let reason;
+                    if (response.error.reason !== undefined) {
+                        if (response.error.code !== "START" ||
+                            typeof response.error.reason !== "string" ||
+                            !isStartupReason(response.error.reason)) {
+                            pending.reject(fault("PROTOCOL"));
+                            this.#fail("PROTOCOL");
+                            return;
+                        }
+                        reason = response.error.reason;
+                    }
+                    pending.reject(fault(response.error.code, reason));
+                }
+                else {
+                    pending.resolve(response.result);
+                }
+            }
+            catch {
+                this.#fail("PROTOCOL");
+                return;
+            }
+            newline = this.#buffer.indexOf(10);
+        }
+    }
+    request(method, params = {}, timeout = 35000) {
+        if (this.#failed)
+            return Promise.reject(fault("TRANSPORT"));
+        const id = ++this.#sequence;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => this.#fail("TIMEOUT"), timeout);
+            this.#pending.set(id, { resolve, reject, timer });
+            const message = JSON.stringify({ version: 1, id, method, params });
+            if (Buffer.byteLength(message) >= MAX_MESSAGE) {
+                this.#fail("PROTOCOL");
+                return;
+            }
+            this.#child.stdin.write(`${message}\n`, (error) => {
+                if (error)
+                    this.#fail("TRANSPORT");
+            });
+        });
+    }
+    close() {
+        if (!this.#closing)
+            this.#closing = this.#close();
+        return this.#closing;
+    }
+    async #close() {
+        let failure;
+        if (!this.#failed) {
+            try {
+                await this.request("close", {}, CLEANUP_TIMEOUT);
+            }
+            catch {
+                failure = fault("CLEANUP");
+            }
+        }
+        this.#child.stdin.end();
+        const kill = setTimeout(() => this.#child.kill("SIGKILL"), CLEANUP_TIMEOUT);
+        await this.#exited;
+        clearTimeout(kill);
+        if (!this.#spawned)
+            return;
+        try {
+            await runCleanup(this.#binary, this.#manifest, this.#owner);
+        }
+        catch {
+            failure = fault("CLEANUP");
+        }
+        if (failure)
+            throw failure;
+    }
+    [inspect.custom]() {
+        return "[TestkitBridge]";
+    }
+}
+class AppHandle {
+    #bridge;
+    #url;
+    #closed = false;
+    constructor(bridge, url) {
+        this.#bridge = bridge;
+        this.#url = url;
+    }
+    get url() {
+        return this.#url;
+    }
+    async getApiKey(name = "") {
+        if (this.#closed || typeof name !== "string")
+            throw fault("STATE");
+        const value = await this.#bridge.request("getApiKey", { name });
+        if (!strings(value, ["apiKey"]))
+            throw fault("PROTOCOL");
+        return value.apiKey;
+    }
+    async credentials() {
+        if (this.#closed)
+            throw fault("STATE");
+        return privateCredentials(await this.#bridge.request("credentials"));
+    }
+    async info() {
+        if (this.#closed)
+            throw fault("STATE");
+        const value = await this.#bridge.request("info");
+        if (!strings(value, ["id", "url", "image", "imageId"]) ||
+            !Array.isArray(value.repoDigests) ||
+            !value.repoDigests.every((digest) => typeof digest === "string")) {
+            throw fault("PROTOCOL");
+        }
+        return {
+            id: value.id,
+            url: value.url,
+            image: value.image,
+            imageId: value.imageId,
+            repoDigests: [...value.repoDigests],
+        };
+    }
+    async close() {
+        this.#closed = true;
+        await this.#bridge.close();
+    }
+    toJSON() {
+        return "[App]";
+    }
+    [inspect.custom]() {
+        return "[App]";
+    }
+}
+class SelfHostHandle {
+    #binary;
+    #timeout;
+    #manifest;
+    #directory;
+    #bridges = new Set();
+    #starts = new Set();
+    #closed = false;
+    #closing;
+    constructor(options) {
+        this.#binary =
+            options.binary ??
+                process.env.SELF_HOST_TESTKIT_BINARY ??
+                installedBinary();
+        this.#timeout = options.timeoutMs ?? 720000;
+        if (typeof this.#binary !== "string" ||
+            this.#binary.length === 0 ||
+            !Number.isSafeInteger(this.#timeout) ||
+            this.#timeout < 1 ||
+            this.#timeout > 840000) {
+            throw fault("PROTOCOL");
+        }
+        const manifest = options.manifest ?? process.env.SELF_HOST_TESTKIT_MANIFEST;
+        if (manifest !== undefined &&
+            (typeof manifest !== "string" || !isAbsolute(manifest))) {
+            throw fault("PROTOCOL");
+        }
+        if (manifest) {
+            this.#manifest = manifest;
+        }
+        else {
+            try {
+                this.#directory = mkdtempSync(join(tmpdir(), "self-host-testkit-"));
+                this.#manifest = join(this.#directory, "manifest.jsonl");
+            }
+            catch {
+                throw fault("START");
+            }
+        }
+    }
+    async spinup(app, options) {
+        const selected = options ?? {};
+        if (this.#closed)
+            throw fault("STATE");
+        if (!record(selected) ||
+            typeof app !== "string" ||
+            !/^[a-z0-9][a-z0-9-]{0,63}$/.test(app) ||
+            (selected.image !== undefined && typeof selected.image !== "string")) {
+            throw fault("PROTOCOL");
+        }
+        const bridge = new Bridge(this.#binary, this.#manifest);
+        this.#bridges.add(bridge);
+        const start = this.#spinup(bridge, app, selected);
+        this.#starts.add(start);
+        try {
+            return await start;
+        }
+        finally {
+            this.#starts.delete(start);
+        }
+    }
+    async #spinup(bridge, app, options) {
+        try {
+            const value = await bridge.request("spinup", {
+                app,
+                image: options.image,
+                timeoutMs: this.#timeout,
+            }, this.#timeout + 1000);
+            if (!strings(value, ["url"]) ||
+                !/^http:\/\/127\.0\.0\.1:\d+\/?$/.test(value.url)) {
+                throw fault("PROTOCOL");
+            }
+            if (this.#closed)
+                throw fault("STATE");
+            return new AppHandle(bridge, value.url);
+        }
+        catch (error) {
+            await bridge.close();
+            throw error;
+        }
+    }
+    close() {
+        if (!this.#closing) {
+            this.#closed = true;
+            this.#closing = this.#close();
+        }
+        return this.#closing;
+    }
+    async #close() {
+        const results = await Promise.allSettled([...this.#bridges].map((bridge) => bridge.close()));
+        await Promise.allSettled([...this.#starts]);
+        if (results.some((result) => result.status === "rejected"))
+            throw fault("CLEANUP");
+        if (this.#directory) {
+            try {
+                try {
+                    unlinkSync(this.#manifest);
+                }
+                catch (error) {
+                    if (!(error instanceof Error) ||
+                        !("code" in error) ||
+                        error.code !== "ENOENT")
+                        throw error;
+                }
+                rmdirSync(this.#directory);
+            }
+            catch {
+                throw fault("CLEANUP");
+            }
+        }
+    }
+    toJSON() {
+        return "[SelfHost]";
+    }
+    [inspect.custom]() {
+        return "[SelfHost]";
+    }
+}
+function isErrorCode(value) {
+    return [...messages.keys()].some((code) => code === value);
+}
+function isStartupReason(value) {
+    return [...startupReasons.keys()].some((reason) => reason === value);
+}
+export function createSelfHost(options = {}) {
+    if (!record(options))
+        throw fault("PROTOCOL");
+    return new SelfHostHandle(options);
+}

package/package.json

@@ -1,6 +1,54 @@
 {
-  "name": "@ajnart/self-host-testkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@ajnart/self-host-testkit",
+	"version": "1.2.1",
+	"description": "Real, isolated Docker App fixtures for Node.js and TypeScript integration tests",
+	"type": "module",
+	"main": "./index.mjs",
+	"types": "./index.d.mts",
+	"exports": {
+		".": {
+			"types": "./index.d.mts",
+			"import": "./index.mjs"
+		}
+	},
+	"bin": { "self-host-testkit-setup": "./setup.mjs" },
+	"files": [
+		"index.mjs",
+		"index.d.mts",
+		"binary.mjs",
+		"setup.mjs",
+		"examples/sonarr.mjs",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json && cp ../../LICENSE LICENSE",
+		"check": "tsc -p tsconfig.json --noEmit",
+		"lint": "biome check .",
+		"test": "bun test ./tests",
+		"prepack": "npm run build"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.4",
+		"@types/node": "^26.6.4",
+		"typescript": "^6.0.3"
+	},
+	"publishConfig": { "access": "public" },
+	"keywords": [
+		"docker",
+		"compose",
+		"integration-testing",
+		"fixtures",
+		"self-hosted",
+		"typescript"
+	],
+	"homepage": "https://github.com/ajnart/self-host/tree/main/testkit",
+	"bugs": "https://github.com/ajnart/self-host/issues",
+	"engines": { "node": ">=22" },
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/ajnart/self-host.git",
+		"directory": "testkit/node"
+	}
+}

package/setup.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { binaryDirectory, installedBinary, privateDirectory, version, } from "./binary.mjs";
+async function download(url, limit) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+    if (!response.ok || !response.body)
+        throw new Error("Release download failed; check connectivity and that the matching release exists.");
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > limit) {
+            throw new Error("Release download exceeds the size limit.");
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+async function setup() {
+    if (process.argv.slice(2).length !== 0) {
+        if (process.argv.length === 3 && process.argv[2] === "--help") {
+            console.log("self-host-testkit-setup: download and verify the matching helper for Linux/macOS x64/arm64. Requires tar. Does not start Docker or modify PATH.");
+            return;
+        }
+        throw new Error("Usage: self-host-testkit-setup [--help]");
+    }
+    if (!(process.platform === "linux" || process.platform === "darwin") ||
+        !(process.arch === "x64" || process.arch === "arm64")) {
+        throw new Error("Testkit supports Linux and macOS on x64 or arm64. On Windows, use WSL2 with a local Unix Docker socket.");
+    }
+    const directory = binaryDirectory();
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (!privateDirectory(directory))
+        throw new Error("Testkit helper cache must be private and owned by the current user.");
+    if (installedBinary() !== "self-host-testkit") {
+        console.log(`Testkit helper ${version} is already installed.`);
+        return;
+    }
+    let arch = process.arch;
+    if (arch === "x64")
+        arch = "amd64";
+    const archive = `self-host_${version}_${process.platform}_${arch}.tar.gz`;
+    const base = `https://github.com/ajnart/self-host/releases/download/v${version}`;
+    console.log(`Downloading and verifying testkit helper ${version} for ${process.platform}/${arch}…`);
+    const checksums = (await download(`${base}/checksums.txt`, 1024 * 1024)).toString("utf8");
+    const matches = checksums
+        .split("\n")
+        .map((line) => line.trim().split(/\s+/))
+        .filter((entry) => entry[1] === archive);
+    if (matches.length !== 1 || !/^[a-f0-9]{64}$/.test(matches[0]?.[0] ?? ""))
+        throw new Error("Release lacks an unambiguous helper checksum.");
+    const data = await download(`${base}/${archive}`, 128 * 1024 * 1024);
+    if (createHash("sha256").update(data).digest("hex") !== matches[0]?.[0])
+        throw new Error("Helper checksum mismatch; nothing installed.");
+    const staging = mkdtempSync(join(directory, ".download-"));
+    try {
+        const path = join(staging, archive);
+        writeFileSync(path, data, { mode: 0o600 });
+        const result = spawnSync("tar", ["-xzf", path, "-C", staging, "self-host-testkit"], { stdio: "ignore", timeout: 30_000 });
+        if (result.status !== 0)
+            throw new Error("Helper extraction failed; make sure tar is installed.");
+        const binary = join(staging, "self-host-testkit");
+        if (!lstatSync(binary).isFile())
+            throw new Error("Release did not contain a regular helper binary.");
+        chmodSync(binary, 0o700);
+        renameSync(binary, join(directory, "self-host-testkit"));
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+    console.log("Helper ready. createSelfHost() will find it automatically; no PATH or environment changes needed.");
+}
+try {
+    await setup();
+}
+catch (error) {
+    let message = "Unknown setup failure.";
+    if (error instanceof Error)
+        message = error.message;
+    console.error("Testkit setup failed.", message);
+    process.exitCode = 1;
+}