@ajnart/self-host-testkit 1.2.1 → 1.3.0

package/binary.mjs

@@ -1,21 +1,34 @@
 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 function packageVersion(path) {
+    try {
+        const metadata = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof metadata === "object" &&
+            metadata !== null &&
+            "name" in metadata &&
+            metadata.name === "@ajnart/self-host-testkit" &&
+            "version" in metadata &&
+            typeof metadata.version === "string" &&
+            /^\d+\.\d+\.\d+$/.test(metadata.version)) {
+            return metadata.version;
+        }
+    }
+    catch {
+        throw new Error("Invalid testkit package metadata.");
+    }
+    throw new Error("Invalid testkit package metadata.");
 }
-export const version = metadata.version;
-export function binaryDirectory() {
+export const version = packageVersion(new URL("./package.json", import.meta.url));
+export function binaryDirectory(exactVersion = version) {
+    if (!/^\d+\.\d+\.\d+$/.test(exactVersion)) {
+        throw new Error("Invalid testkit helper version.");
+    }
     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}`);
+    return join(cache, "self-host-testkit", exactVersion, `${process.platform}-${process.arch}`);
 }
 export function privateDirectory(path) {
     const info = lstatSync(path);
@@ -23,8 +36,7 @@ export function privateDirectory(path) {
         info.uid === process.getuid?.() &&
         (info.mode & 0o077) === 0);
 }
-export function installedBinary() {
-    const directory = binaryDirectory();
+export function installedBinary(directory = binaryDirectory()) {
     const binary = join(directory, "self-host-testkit");
     if (!existsSync(binary))
         return "self-host-testkit";

package/examples/homarr-sonarr.mjs

@@ -0,0 +1,66 @@
+import { withPair } from "@ajnart/self-host-testkit";
+
+const order = process.argv[2] ?? "consumer-first";
+if (order !== "consumer-first" && order !== "target-first") {
+	throw new Error("Choose consumer-first or target-first.");
+}
+
+await withPair(
+	"homarr",
+	"sonarr",
+	async (pair) => {
+		if ((await pair.inspect()).outcome !== "complete") {
+			throw new Error(
+				"Production Setup/Link has a failed or Manual prerequisite.",
+			);
+		}
+		const response = await fetch(`${pair.target.url}/api/v3/system/status`, {
+			headers: { "X-Api-Key": await pair.target.getApiKey() },
+			signal: AbortSignal.timeout(10_000),
+		});
+		if (!response.ok || (await response.json()).appName !== "Sonarr") {
+			throw new Error("Sonarr identity did not authenticate.");
+		}
+		const integrationId = await pair.consumer.getApiKey("linked_sonarr");
+		const apiKey = await pair.consumer.getApiKey();
+		const snapshot = async () => {
+			const input = encodeURIComponent(
+				JSON.stringify({ json: { integrationId } }),
+			);
+			const result = await fetch(
+				`${pair.consumer.url}/api/trpc/widget.stats.snapshot?input=${input}`,
+				{
+					headers: { ApiKey: apiKey },
+					signal: AbortSignal.timeout(10_000),
+				},
+			);
+			if (!result.ok) throw new Error("Homarr Stats could not be read.");
+			const envelope = await result.json();
+			const sample = envelope.result?.data?.json;
+			if (
+				envelope.error ||
+				!sample ||
+				sample.error !== false ||
+				sample.stale !== false ||
+				!Number.isFinite(sample.updatedAt) ||
+				sample.updatedAt <= 0 ||
+				!["shows", "downloaded", "missing", "queued"].every(
+					(key) =>
+						Number.isInteger(sample.values?.[key]) && sample.values[key] >= 0,
+				)
+			) {
+				throw new Error("Homarr did not return meaningful Sonarr Stats.");
+			}
+			return sample.updatedAt;
+		};
+		const before = await snapshot();
+		if (
+			(await pair.setup("homarr")).outcome !== "complete" ||
+			(await snapshot()) <= before
+		) {
+			throw new Error("Production Link verification did not advance Stats.");
+		}
+		console.log("Production Homarr/Sonarr Link and advancing Stats verified.");
+	},
+	{ order },
+);

package/examples/sonarr.mjs

@@ -1,9 +1,6 @@
-import { createSelfHost } from "@ajnart/self-host-testkit";
+import { withApp } from "@ajnart/self-host-testkit";
 
-const selfHost = createSelfHost();
-
-try {
-	const sonarr = await selfHost.spinup("sonarr");
+await withApp("sonarr", async (sonarr) => {
 	const response = await fetch(`${sonarr.url}/api/v3/system/status`, {
 		headers: { "X-Api-Key": await sonarr.getApiKey() },
 		signal: AbortSignal.timeout(10_000),
@@ -15,6 +12,4 @@ try {
 		throw new Error("Sonarr returned an unexpected identity.");
 	}
 	console.log(`Connected to Sonarr ${status.version}.`);
-} finally {
-	await selfHost.close();
-}
+});

package/index.d.mts

@@ -1,3 +1,5 @@
+import { type TestkitStartupReason } from "./reasons.mjs";
+export type { TestkitStartupReason } from "./reasons.mjs";
 export interface Credentials {
     readonly username: string;
     readonly password: string;
@@ -13,6 +15,7 @@ export interface AppInfo {
 }
 export interface App {
     readonly url: string;
+    readonly recoveryPath?: string;
     getApiKey(name?: string): Promise<string>;
     credentials(): Promise<Credentials>;
     info(): Promise<AppInfo>;
@@ -22,7 +25,60 @@ export interface SpinupOptions {
     image?: string;
 }
 export interface SelfHost {
+    readonly recoveryPath?: string;
     spinup(app: string, options?: SpinupOptions): Promise<App>;
+    spinupPair(consumer: string, target: string, options: PairOptions): Promise<Pair>;
+    close(): Promise<void>;
+}
+export interface PairOptions {
+    order: "consumer-first" | "target-first";
+    images?: Readonly<Record<string, string>>;
+    sonarrFilterWitness?: true;
+}
+export interface SonarrFilterWitness {
+    readonly kind: "sonarr-custom-filter-v1";
+    readonly objectId: number;
+    readonly contentSha256: string;
+}
+declare const pairStates: readonly ["running", "exited", "created", "restarting", "paused", "missing", "unknown", "dead", "removing", "degraded"];
+export type PairAppState = (typeof pairStates)[number];
+export interface PairAppStatus {
+    readonly id: string;
+    readonly url: string;
+    readonly installed: boolean;
+    readonly state: PairAppState;
+    readonly setup: "ok" | "manual" | "incomplete" | "pending";
+    readonly steps: ReadonlyArray<{
+        readonly id: string;
+        readonly status: "ok" | "manual" | "fail" | "skip";
+        readonly verified: boolean;
+    }>;
+}
+export type PairInspection = {
+    readonly link: string;
+    readonly apps: readonly PairAppStatus[];
+} & ({
+    readonly outcome: "complete";
+    readonly reason: "verified";
+} | {
+    readonly outcome: "manual" | "failed";
+    readonly reason: "setup";
+} | {
+    readonly outcome: "prerequisite";
+    readonly reason: "absent" | "unready" | "not-run";
+});
+export type PairApp = Omit<App, "close">;
+export interface Pair {
+    readonly consumer: PairApp;
+    readonly target: PairApp;
+    readonly initial: PairInspection;
+    readonly recoveryPath?: string;
+    inspect(): Promise<PairInspection>;
+    setup(app?: string): Promise<PairInspection>;
+    remove(app: string): Promise<PairInspection>;
+    install(app: string): Promise<PairInspection>;
+    createSonarrFilterWitness(): Promise<SonarrFilterWitness>;
+    readSonarrFilterWitness(): Promise<SonarrFilterWitness>;
     close(): Promise<void>;
 }
 export interface SelfHostOptions {
@@ -30,11 +86,17 @@ export interface SelfHostOptions {
     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 type TestkitErrorCode = "PROTOCOL" | "STATE" | "START" | "CREDENTIALS" | "INFO" | "CLEANUP" | "TIMEOUT" | "TRANSPORT" | "OPERATION" | "CANCELED" | "BINARY";
 export declare class TestkitError extends Error {
     readonly code: TestkitErrorCode;
     readonly reason: TestkitStartupReason | undefined;
-    constructor(code: TestkitErrorCode, reason?: TestkitStartupReason);
+    readonly cleanupFailed: boolean;
+    readonly recoveryPath?: string;
+    constructor(code: TestkitErrorCode, reason?: TestkitStartupReason, recoveryPath?: string, cleanupFailed?: boolean);
 }
 export declare function createSelfHost(options?: SelfHostOptions): SelfHost;
+export interface ScopedOptions {
+    onCleanupError?: (error: TestkitError) => void | Promise<void>;
+}
+export declare function withApp<T>(app: string, callback: (app: App) => T | Promise<T>, options?: SelfHostOptions & SpinupOptions & ScopedOptions): Promise<T>;
+export declare function withPair<T>(consumer: string, target: string, callback: (pair: Pair) => T | Promise<T>, options: SelfHostOptions & PairOptions & ScopedOptions): Promise<T>;