dsh-github-app 0.0.0-stage → 0.0.1

package/index.mjs

@@ -0,0 +1,47 @@
+import "./_virtual/_rollup-plugin-process-env.mjs";
+import { API_PREFIX } from "./constants.mjs";
+import { buildTrustedHosts } from "./fence.mjs";
+import { createApiHandler } from "./api.mjs";
+import { cancelUninstallCleanup, profileDeclaresPackage, watchForUninstallCleanup } from "./uninstall.mjs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// src/index.ts
+/**
+* Resolve the profile directory from the loader context. The loader sets
+* `baseUrl` to the directory of the profile configuration, which is also the
+* directory holding `package.json`.
+*
+* @param baseUrl context base URL, usually a `file:` URL.
+* @returns an absolute directory path, or null when it cannot be resolved.
+*/
+function resolveProfileDir(baseUrl) {
+	if (typeof baseUrl !== "string" || baseUrl.trim() === "") return null;
+	try {
+		const value = baseUrl.startsWith("file:") ? fileURLToPath(new URL(".", baseUrl)) : baseUrl;
+		return resolve(value);
+	} catch {
+		return null;
+	}
+}
+const name = "github";
+const inject = ["webServer", "webStartup"];
+function apply(ctx) {
+	cancelUninstallCleanup();
+	const trustedHosts = buildTrustedHosts(ctx.webStartup?.trustedHosts, (message) => {
+		console.warn("[dsh-github-app] ignoring invalid trusted host:", message);
+	});
+	const handler = createApiHandler(ctx, { trustedHosts });
+	ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: API_PREFIX,
+		handler
+	}), "dsh-github-app: api");
+	const profileDir = resolveProfileDir(ctx.baseUrl);
+	if (profileDir !== null && profileDeclaresPackage(profileDir) === true) {
+		const watchedProfileDir = profileDir;
+		ctx.effect(() => () => {
+			watchForUninstallCleanup({ profileDir: watchedProfileDir });
+		}, "dsh-github-app: uninstall cleanup");
+	}
+}
+export { apply, inject, name };

package/keyCrypto.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Passphrase encryption for the GitHub App private key.
+ *
+ * The key is stored as a self-describing JSON envelope: scrypt turns the
+ * passphrase into an AES-256-GCM key, and the envelope carries only the KDF
+ * parameters, salt, IV and authentication tag — never the passphrase. The
+ * passphrase is not persisted anywhere and is required again after every
+ * server restart.
+ */
+/**
+ * Encrypt a PEM private key under a passphrase.
+ *
+ * @param pem PEM text.
+ * @param passphrase user passphrase; never stored.
+ * @returns the JSON envelope to write to disk.
+ */
+export declare function encryptPrivateKey(pem: string, passphrase: string): Promise<string>;
+/**
+ * Decrypt a key envelope produced by {@link encryptPrivateKey}.
+ *
+ * @param text JSON envelope read from disk.
+ * @param passphrase user passphrase.
+ * @returns the PEM text.
+ */
+export declare function decryptPrivateKey(text: string, passphrase: string): Promise<string>;

package/keyCrypto.mjs

@@ -0,0 +1,132 @@
+import { passphraseError } from "./passphrase.mjs";
+import { createCipheriv, createDecipheriv, randomBytes, scrypt } from "node:crypto";
+// src/keyCrypto.ts
+/**
+* Passphrase encryption for the GitHub App private key.
+*
+* The key is stored as a self-describing JSON envelope: scrypt turns the
+* passphrase into an AES-256-GCM key, and the envelope carries only the KDF
+* parameters, salt, IV and authentication tag — never the passphrase. The
+* passphrase is not persisted anywhere and is required again after every
+* server restart.
+*/
+const ENVELOPE_VERSION = 1;
+const KDF = "scrypt";
+const CIPHER = "aes-256-gcm";
+const KEY_BYTES = 32;
+const SALT_BYTES = 16;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const MIN_N = 4096;
+const MAX_N = 1 << 18;
+const MAX_R = 16;
+const MAX_P = 4;
+const AAD = Buffer.from("dsh-github-app:private-key:v1", "utf8");
+function decodeField(value, bytes) {
+	if (typeof value !== "string" || value === "") throw new Error("Malformed key envelope");
+	const buffer = Buffer.from(value, "base64");
+	if (buffer.length !== bytes) throw new Error("Malformed key envelope");
+	return buffer;
+}
+function readEnvelope(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new Error("Malformed key envelope");
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Malformed key envelope");
+	const value = parsed;
+	const N = value.N;
+	const r = value.r;
+	const p = value.p;
+	if (value.version !== ENVELOPE_VERSION || value.kdf !== KDF || value.cipher !== CIPHER) throw new Error("Unsupported key envelope");
+	if (!Number.isInteger(N) || N < MIN_N || N > MAX_N || (N & N - 1) !== 0) throw new Error("Malformed key envelope");
+	if (!Number.isInteger(r) || r < 1 || r > MAX_R) throw new Error("Malformed key envelope");
+	if (!Number.isInteger(p) || p < 1 || p > MAX_P) throw new Error("Malformed key envelope");
+	decodeField(value.salt, SALT_BYTES);
+	decodeField(value.iv, IV_BYTES);
+	decodeField(value.tag, TAG_BYTES);
+	if (typeof value.data !== "string" || value.data === "") throw new Error("Malformed key envelope");
+	return value;
+}
+function deriveKey(passphrase, salt, N, r, p) {
+	return new Promise((resolve, reject) => {
+		scrypt(passphrase, salt, KEY_BYTES, {
+			N,
+			r,
+			p,
+			maxmem: 128 * N * r + 67108864
+		}, (error, key) => {
+			if (error) reject(error);
+			else resolve(key);
+		});
+	});
+}
+/**
+* Encrypt a PEM private key under a passphrase.
+*
+* @param pem PEM text.
+* @param passphrase user passphrase; never stored.
+* @returns the JSON envelope to write to disk.
+*/
+async function encryptPrivateKey(pem, passphrase) {
+	const invalid = passphraseError(passphrase);
+	if (invalid !== null) throw new Error(invalid);
+	if (pem.trim() === "") throw new Error("Private key is empty");
+	const N = 32768;
+	const r = 8;
+	const p = 1;
+	const salt = randomBytes(SALT_BYTES);
+	const iv = randomBytes(IV_BYTES);
+	const key = await deriveKey(passphrase, salt, N, r, p);
+	try {
+		const cipher = createCipheriv(CIPHER, key, iv);
+		cipher.setAAD(AAD);
+		const data = Buffer.concat([cipher.update(pem, "utf8"), cipher.final()]);
+		const tag = cipher.getAuthTag();
+		const envelope = {
+			version: ENVELOPE_VERSION,
+			kdf: KDF,
+			cipher: CIPHER,
+			N,
+			r,
+			p,
+			salt: salt.toString("base64"),
+			iv: iv.toString("base64"),
+			tag: tag.toString("base64"),
+			data: data.toString("base64")
+		};
+		return `${JSON.stringify(envelope, null, 2)}\n`;
+	} finally {
+		key.fill(0);
+	}
+}
+/**
+* Decrypt a key envelope produced by {@link encryptPrivateKey}.
+*
+* @param text JSON envelope read from disk.
+* @param passphrase user passphrase.
+* @returns the PEM text.
+*/
+async function decryptPrivateKey(text, passphrase) {
+	const invalid = passphraseError(passphrase);
+	if (invalid !== null) throw new Error(invalid);
+	const envelope = readEnvelope(text);
+	const salt = decodeField(envelope.salt, SALT_BYTES);
+	const iv = decodeField(envelope.iv, IV_BYTES);
+	const tag = decodeField(envelope.tag, TAG_BYTES);
+	const data = Buffer.from(envelope.data, "base64");
+	const key = await deriveKey(passphrase, salt, envelope.N, envelope.r, envelope.p);
+	try {
+		const decipher = createDecipheriv(CIPHER, key, iv);
+		decipher.setAAD(AAD);
+		decipher.setAuthTag(tag);
+		return Buffer.concat([decipher.update(data), decipher.final()]).toString("utf8");
+	} catch {
+		throw new Error("Cannot decrypt private key");
+	} finally {
+		key.fill(0);
+	}
+}
+export { decryptPrivateKey, encryptPrivateKey };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "dsh-github-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "GitHub CLI (gh) integration for DSH: configure a GitHub App and authenticate gh for git operations.",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": "./index.mjs",
+    "./client": "./client/client.js",
+    "./package.json": "./package.json"
+  },
+  "author": "Mikhail Lysikov <d8corp@mail.ru>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d8corp/dsh-github-app.git"
+  },
+  "keywords": [
+    "DeepSeek",
+    "Harness",
+    "GitHub",
+    "plugin"
+  ],
+  "bugs": {
+    "url": "https://github.com/d8corp/dsh-github-app/issues"
+  },
+  "homepage": "https://github.com/d8corp/dsh-github-app",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "npm run build:theme && npm run build:client && innetjs release -tc -lc -e",
+    "build:client": "innetjs build -i client -tc -lc -e",
+    "build:theme": "innetjs run buildEnv.ts -e",
+    "release": "npm run build:theme && npm run build:client && innetjs release -p -tc -lc -e",
+    "test": "jest",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix"
+  },
+  "dsh": {
+    "manifestVersion": "1",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  }
 }

package/passphrase.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Passphrase rules shared by the browser settings UI and the host.
+ */
+/**
+ * Validate a passphrase supplied by the browser.
+ *
+ * @param value raw value from the request.
+ * @returns an error message, or null when the passphrase is usable.
+ */
+export declare function passphraseError(value: unknown): string | null;

package/passphrase.mjs

@@ -0,0 +1,18 @@
+import { MAX_PASSPHRASE_CHARS } from "./constants.mjs";
+// src/passphrase.ts
+/**
+* Passphrase rules shared by the browser settings UI and the host.
+*/
+/**
+* Validate a passphrase supplied by the browser.
+*
+* @param value raw value from the request.
+* @returns an error message, or null when the passphrase is usable.
+*/
+function passphraseError(value) {
+	if (typeof value !== "string" || value.trim() === "") return "Passphrase is required.";
+	if (value.length < 8) return `Passphrase must be at least 8 characters.`;
+	if (value.length > 1024) return `Passphrase must be at most ${MAX_PASSPHRASE_CHARS} characters.`;
+	return null;
+}
+export { passphraseError };

package/secureFile.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Private-file helpers for the GitHub App key.
+ *
+ * Deletions are restricted to the harness home so a tampered settings file
+ * cannot turn `clearConfig` into arbitrary file removal.
+ */
+/**
+ * Whether a path lives inside the harness home, judged by its parent's real
+ * location so a symlinked directory cannot escape the check.
+ *
+ * @param file candidate path.
+ * @returns true when removing the path cannot reach outside `$DSH_HOME`.
+ */
+export declare function isInsideDshHome(file: string | null | undefined): boolean;
+/**
+ * Remove a file only when it is inside the harness home.
+ *
+ * @param file candidate path.
+ * @returns true when the file is gone (or was absent), false otherwise.
+ */
+export declare function removeSecretFile(file: string | null | undefined): boolean;

package/secureFile.mjs

@@ -0,0 +1,56 @@
+import { dshHomeDir } from "./settings.mjs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, realpathSync, unlinkSync } from "node:fs";
+// src/secureFile.ts
+/**
+* Private-file helpers for the GitHub App key.
+*
+* Deletions are restricted to the harness home so a tampered settings file
+* cannot turn `clearConfig` into arbitrary file removal.
+*/
+/**
+* Real path when it exists. Missing paths are resolved through their nearest
+* existing ancestor, so symlinked parents (`/var` → `/private/var` on macOS)
+* still compare correctly against a real home directory.
+*/
+function realOrResolved(path) {
+	const resolved = resolve(path);
+	try {
+		return realpathSync.native(resolved);
+	} catch {
+		const parent = dirname(resolved);
+		if (parent === resolved) return resolved;
+		return join(realOrResolved(parent), basename(resolved));
+	}
+}
+/**
+* Whether a path lives inside the harness home, judged by its parent's real
+* location so a symlinked directory cannot escape the check.
+*
+* @param file candidate path.
+* @returns true when removing the path cannot reach outside `$DSH_HOME`.
+*/
+function isInsideDshHome(file) {
+	if (typeof file !== "string" || file.trim() === "") return false;
+	const home = realOrResolved(dshHomeDir());
+	const parent = realOrResolved(dirname(resolve(file)));
+	const relation = relative(home, parent);
+	return !relation.startsWith("..") && !isAbsolute(relation);
+}
+/**
+* Remove a file only when it is inside the harness home.
+*
+* @param file candidate path.
+* @returns true when the file is gone (or was absent), false otherwise.
+*/
+function removeSecretFile(file) {
+	if (!isInsideDshHome(file)) return false;
+	const target = file;
+	try {
+		if (existsSync(target)) unlinkSync(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+export { isInsideDshHome, removeSecretFile };

package/settings.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Host-side settings for dsh-github-app.
+ *
+ * Stored at `$DSH_HOME/dsh-github-app/github.json` (or `~/.dsh/dsh-github-app/github.json`).
+ * The private key is never stored here — only its path on the host. The key
+ * itself lives in a separate 0600 file encrypted with a passphrase that is
+ * never persisted.
+ */
+export interface GithubSettings {
+    appId: string;
+    installationId: string;
+    gitUserName: string;
+    gitUserEmail: string;
+    keyPath: string | null;
+    keyFileName: string | null;
+    tokenIssuedAt: string | null;
+    tokenExpiresAt: string | null;
+}
+/**
+ * Resolve the DeepSeek Harness home: `$DSH_HOME` when set, otherwise `~/.dsh`.
+ *
+ * The configured value is `~`-expanded and resolved to an absolute path, so
+ * `DSH_HOME=~/harness` means `$HOME/harness` — never a literal `./~` directory
+ * relative to the server's working directory.
+ *
+ * Kept local on purpose — the host half must load with no runtime dependency
+ * beyond Node built-ins, so no `@deepseek-ai/*` helper package is imported here.
+ *
+ * @returns the absolute harness home directory.
+ */
+export declare function dshHomeDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Plugin-owned data directory under the DSH home.
+ *
+ * @param env environment to read `DSH_HOME` from.
+ * @returns `$DSH_HOME/dsh-github-app`.
+ */
+export declare function pluginDir(env?: NodeJS.ProcessEnv): string;
+export declare function settingsPath(env?: NodeJS.ProcessEnv): string;
+/** Fixed location of the encrypted private key envelope. */
+export declare function encryptedKeyPath(env?: NodeJS.ProcessEnv): string;
+export declare function normalizeSettings(value: unknown): GithubSettings;
+export declare function readSettings(file?: string): GithubSettings;
+export declare function writeSettings(settings: unknown, file?: string): GithubSettings;
+export declare function keyFileExists(settings: unknown): boolean;

package/settings.mjs

@@ -0,0 +1,127 @@
+import { writeSecretFile } from "./atomicFile.mjs";
+import { KEY_ENCRYPTED_FILENAME, PLUGIN_DIR_NAME, SETTINGS_FILENAME } from "./constants.mjs";
+import { parseTimestamp } from "./time.mjs";
+import { join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+// src/settings.ts
+/**
+* Host-side settings for dsh-github-app.
+*
+* Stored at `$DSH_HOME/dsh-github-app/github.json` (or `~/.dsh/dsh-github-app/github.json`).
+* The private key is never stored here — only its path on the host. The key
+* itself lives in a separate 0600 file encrypted with a passphrase that is
+* never persisted.
+*/
+const MAX_ID_CHARS = 64;
+const MAX_GIT_NAME_CHARS = 128;
+const MAX_GIT_EMAIL_CHARS = 255;
+/**
+* Expand a leading `~` to the current user's home directory. `~user/...` is
+* deliberately left alone, matching the harness home-path helper.
+*
+* @param value configured path.
+* @returns the path with `~` (or `~/`) expanded.
+*/
+function expandHome(value) {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/") || value.startsWith("~\\")) return join(homedir(), value.slice(2));
+	return value;
+}
+/**
+* Resolve the DeepSeek Harness home: `$DSH_HOME` when set, otherwise `~/.dsh`.
+*
+* The configured value is `~`-expanded and resolved to an absolute path, so
+* `DSH_HOME=~/harness` means `$HOME/harness` — never a literal `./~` directory
+* relative to the server's working directory.
+*
+* Kept local on purpose — the host half must load with no runtime dependency
+* beyond Node built-ins, so no `@deepseek-ai/*` helper package is imported here.
+*
+* @returns the absolute harness home directory.
+*/
+function dshHomeDir(env = process.env) {
+	const configured = env && typeof env.DSH_HOME === "string" ? env.DSH_HOME.trim() : "";
+	return resolve(configured === "" ? join(homedir(), ".dsh") : expandHome(configured));
+}
+/**
+* Plugin-owned data directory under the DSH home.
+*
+* @param env environment to read `DSH_HOME` from.
+* @returns `$DSH_HOME/dsh-github-app`.
+*/
+function pluginDir(env = process.env) {
+	return join(dshHomeDir(env), PLUGIN_DIR_NAME);
+}
+function settingsPath(env = process.env) {
+	return join(pluginDir(env), SETTINGS_FILENAME);
+}
+/** Fixed location of the encrypted private key envelope. */
+function encryptedKeyPath(env = process.env) {
+	return join(pluginDir(env), KEY_ENCRYPTED_FILENAME);
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeId(value) {
+	if (typeof value === "number" && Number.isFinite(value)) value = String(Math.trunc(value));
+	if (typeof value !== "string") return "";
+	const trimmed = value.trim();
+	if (trimmed === "") return "";
+	return trimmed.slice(0, MAX_ID_CHARS);
+}
+function normalizePath(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	if (trimmed === "") return null;
+	return trimmed;
+}
+/**
+* Normalize a persisted token timestamp to canonical ISO-8601 UTC.
+*
+* Accepts a parseable date string or a finite, non-negative epoch-millisecond
+* number; anything else — objects, arrays, `"nonsense"`, `NaN`, negative or
+* out-of-range numbers — normalizes to `null` instead of throwing.
+*
+* @param value candidate timestamp read from settings JSON.
+* @returns canonical ISO string, or null when the value is unusable.
+*/
+function normalizeTimestamp(value) {
+	const ms = parseTimestamp(value);
+	if (ms === null) return null;
+	try {
+		return new Date(ms).toISOString();
+	} catch {
+		return null;
+	}
+}
+function normalizeSettings(value) {
+	const source = isPlainObject(value) ? value : {};
+	return {
+		appId: normalizeId(source.appId),
+		installationId: normalizeId(source.installationId),
+		gitUserName: typeof source.gitUserName === "string" ? source.gitUserName.trim().slice(0, MAX_GIT_NAME_CHARS) : "",
+		gitUserEmail: typeof source.gitUserEmail === "string" ? source.gitUserEmail.trim().slice(0, MAX_GIT_EMAIL_CHARS) : "",
+		keyPath: normalizePath(source.keyPath),
+		keyFileName: typeof source.keyFileName === "string" && source.keyFileName.trim() !== "" ? source.keyFileName.trim().slice(0, 255) : null,
+		tokenIssuedAt: normalizeTimestamp(source.tokenIssuedAt),
+		tokenExpiresAt: normalizeTimestamp(source.tokenExpiresAt)
+	};
+}
+function readSettings(file = settingsPath()) {
+	try {
+		return normalizeSettings(JSON.parse(readFileSync(file, "utf8")));
+	} catch {
+		return normalizeSettings({});
+	}
+}
+function writeSettings(settings, file = settingsPath()) {
+	const normalized = normalizeSettings(settings);
+	writeSecretFile(file, `${JSON.stringify(normalized, null, 2)}\n`);
+	return normalized;
+}
+function keyFileExists(settings) {
+	const s = normalizeSettings(settings);
+	return !!s.keyPath && existsSync(s.keyPath);
+}
+export { dshHomeDir, encryptedKeyPath, keyFileExists, normalizeSettings, pluginDir, readSettings, settingsPath, writeSettings };

package/time.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parse an ISO-8601 timestamp (or epoch milliseconds) into epoch milliseconds.
+ *
+ * @param value candidate timestamp.
+ * @returns epoch milliseconds, or null when missing, unparsable or negative.
+ */
+export declare function parseTimestamp(value: unknown): number | null;

package/time.mjs

@@ -0,0 +1,15 @@
+// src/time.ts
+/**
+* Parse an ISO-8601 timestamp (or epoch milliseconds) into epoch milliseconds.
+*
+* @param value candidate timestamp.
+* @returns epoch milliseconds, or null when missing, unparsable or negative.
+*/
+function parseTimestamp(value) {
+	let ms;
+	if (typeof value === "number") ms = value;
+	else if (typeof value === "string" && value.trim() !== "") ms = Date.parse(value);
+	else return null;
+	return Number.isFinite(ms) && ms >= 0 ? ms : null;
+}
+export { parseTimestamp };

package/uninstall.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Removes plugin-owned artifacts after the bundle is uninstalled.
+ *
+ * DSH has no uninstall lifecycle: removing a bundle disposes the plugin fiber
+ * exactly like disabling it, an HMR reload, or a host restart. Disposal alone
+ * therefore proves nothing. The watcher keeps reading the profile manifest
+ * after disposal and deletes plugin data only after the package has stayed
+ * absent from both `dependencies` and `dsh.profile.bundles` for a quiet
+ * period. Until the package is gone, the manifest still declares it, so a
+ * disable, reload, or restart leaves the data alone.
+ *
+ * The watcher lives in the host process, so this covers removals performed
+ * while a DSH host is running. Removing the package with no host running
+ * (`dsh plugin remove`) leaves the data directory for manual cleanup.
+ */
+/**
+ * Whether a profile manifest still claims this package.
+ *
+ * @param profileDir profile root holding `package.json`.
+ * @param packageName bundle package name.
+ * @returns true when declared, false when absent, null when the manifest
+ * cannot be read — callers must treat null as "still installed".
+ */
+export declare function profileDeclaresPackage(profileDir: string, packageName?: string): boolean | null;
+/**
+ * Delete the plugin data directory. Paths are derived from `DSH_HOME`, never
+ * from user input.
+ *
+ * @param env environment to read `DSH_HOME` from.
+ * @returns true when the directory was removed.
+ */
+export declare function removePluginArtifacts(env?: NodeJS.ProcessEnv): boolean;
+export interface UninstallCleanupOptions {
+    /** Profile root captured while the plugin was mounted. */
+    profileDir: string;
+    packageName?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Manifest re-read interval; tests shorten this. */
+    intervalMs?: number;
+    /** Consecutive absent readings required before cleanup. */
+    confirmations?: number;
+    /** Upper bound on the watcher's lifetime. */
+    timeoutMs?: number;
+}
+/**
+ * Watch the profile for this package's removal and delete plugin artifacts.
+ *
+ * @param options profile location and timing knobs.
+ * @returns a function that stops the watcher before it acts.
+ */
+export declare function watchForUninstallCleanup(options: UninstallCleanupOptions): () => void;
+/**
+ * Cancel watchers started by this module instance, for example when the
+ * plugin mounts again after an HMR reload or a reinstall.
+ */
+export declare function cancelUninstallCleanup(): void;