@deepseek-insight/dsi 0.6.9 → 0.6.11

package/.agents/skills/dsi-ov-setup/SKILL.md

@@ -131,6 +131,140 @@ This is the only install path that reconciles `dsh.profile.bundles` and survives
 - Two config files, one directory (§1) — check the right one for the symptom.
 - `auth_mode: "dev"` = no auth, localhost only. Never bind `0.0.0.0` without switching to API-key auth (docs: Authentication guide).
 - Piped `init` answers are prompt-order-fragile (Step 3) — count prompts, don't trust defaults.
+---
+name: dsi-ov-setup
+description: Use when OpenViking memory is broken or missing in DeepSeek Harness — server disconnected, server not installed, ov.conf missing, plugin not loaded, or a fresh machine needs the whole OpenViking + DSH memory integration set up (plugin, skill, server). Covers diagnosis, install, config, start, and verification.
+---
+
+# OpenViking + DSH Setup and Recovery
+
+Companion KB: `dev/kb/setup/2026-09-16 - OpenViking Server + DSH Memory Plugin — From Cold Start to Recalled Memory.md` — read it for the why behind every step. This skill is the do-path.
+
+## 0. Diagnose first — which failure is this?
+
+Run in order; stop at the first failing gate:
+
+| Gate | Command | Healthy looks like |
+|---|---|---|
+| Server process | `curl -s --max-time 3 http://127.0.0.1:1933/health` | `{"status":"ok","healthy":true,...}` |
+| Server config | `ls ~/.openviking/ov.conf` | exists |
+| Client config | `cat ~/.openviking/ovcli.conf` | `url` = `http://127.0.0.1:1933` |
+| Package | `openviking-server --version` | prints a version |
+| Plugin installed | `grep @openviking ~/.dsh/profiles/web/package.json` + `ls ~/.dsh/profiles/web/node_modules/@openviking/dsh-memory-plugin` | both the bundle entry and the package exist |
+| MCP connection | harness tool list shows `mcp__openviking__*` | tools present |
+
+- Health fails + `ov.conf` missing → **Recovery path (§2)**, the common case.
+- Health fails + `ov.conf` exists → run `openviking-server doctor`, fix what it names, go to §2 step 4.
+- Plugin missing from manifest or `node_modules` → reinstall via the sanctioned path (§2 step 6): from the running host's checkout, `pnpm dsh plugin --profile web add @openviking/dsh-memory-plugin`. This persists both the dependency and the `dsh.profile.bundles` entry, so profile rebuilds keep it. A bare `pnpm install` in the profile dir is a dead end — bundles are not `dependencies` and pnpm reports "Already up to date" while the plugin stays missing (RCA 2026-09-18 — The Vanished Plugin).
+- Health ok but MCP disconnected → the plugin reconnects on its own within a turn or two; if not after a full turn, restart the harness session. Do not reinstall anything.
+- Package missing → fresh install: do §2 steps 1–6 from scratch.
+
+## 1. Facts to keep straight (most-confused pair)
+
+- `~/.openviking/ovcli.conf` — **client** pointer: `{"url": "http://127.0.0.1:1933", "api_key": ""}`. Missing it breaks CLI commands only.
+- `~/.openviking/ov.conf` — **server** model config (embedding + VLM). Missing it means the server process cannot start at all. This is the usual blocker.
+- The DSH plugin (`@openviking/dsh-memory-plugin`, in the profile bundles at `~/.dsh/profiles/web/package.json`) is a **client only** — it never starts the server, and it reconnects automatically once the server is healthy. Never "fix" a disconnected MCP by touching the plugin.
+- `openviking`/`ov` = CLI/SDK; `openviking-server` = the daemon. Same pip package.
+
+## 2. Recovery / install path
+
+### Step 1 — Install the package (skip if `openviking-server --version` works)
+
+```sh
+pip install openviking --upgrade --force-reinstall
+```
+
+Entry points land in `~/.local/bin`: `ov`, `openviking`, `openviking-server`, `vikingbot`.
+
+### Step 2 — CLI housekeeping
+
+```sh
+ov language en        # v0.3.23+ refuses most commands without this; writes ovcli.settings.conf
+ov config add custom --name local --url http://127.0.0.1:1933 --activate -o json   # only if ovcli.conf missing
+```
+
+Note: both write under `~/.openviking/` — they fail under a workspace-only file sandbox; run with full file access.
+
+### Step 3 — Create the server config: `openviking-server init`
+
+Preferred: run it interactively and let the human answer. If driving it with piped answers, the wizard's prompt order is exact and hidden prompts exist — the tested sequence for the recommended local setup:
+
+```
+1     # mode: step-by-step
+3     # embedding: lightweight CPU (llama.cpp, bge-small-zh-v1.5-f16, no key)
+1     # embedding model: (only option — EASY TO MISS; missing this shifts every later answer)
+6     # VLM: GLM (subscription API key)
+2     # GLM plan: coding
+<key> # API key — pass via stdin from an env var; NEVER in the command line or logs
+N     # query planner via Ollama: no
+1     # bind 127.0.0.1 (dev, no auth)
+1933  # port
+Y     # save
+```
+
+After saving the wizard echoes the resolved API key in its summary — **redact any captured log** before storing it.
+
+Decision guardrails (from the KB §4): embedding `[3]` CPU is the default because it is keyless and tiny; offer `[1]` cloud embedding only when the user cares about retrieval quality and has a key; VLM is the piece worth a strong model — GLM via an existing subscription beats skipping it. `[9]` skip-VLM gives a server that stores but extracts poorly.
+
+### Step 4 — Wait out the build
+
+Choosing CPU embedding triggers `pip install "openviking[local-embed]"`, which **builds `llama-cpp-python` from source** — several minutes of silent wheel-building. It is not hung. Do not kill it; verify with `ps aux | grep "openviking-server init"`.
+
+### Step 5 — Validate and start
+
+```sh
+openviking-server doctor    # expect: all checks PASS (config, auth, disk ≥ several GB)
+openviking-server           # foreground proof; then move to a supervisor
+```
+
+Sandbox warning: server startup acquires a PID lock at
+`~/.openviking/data/.openviking.pid` — under a workspace-only file sandbox it
+dies with `PermissionError` / exit 3 at once. Start the server with full file
+access (same as step 2's CLI housekeeping).
+
+For persistence: launchd/systemd — never rely on an agent shell outliving the
+session. In a harness session, never start the daemon with `nohup … &` inside a
+**foreground** bash call: the harness reaps the call's process group when the
+call returns and the daemon dies seconds later, health-ok inside the call but
+connection-refused on the next one (RCA 2026-09-21 — The Server That Slept).
+Run it as a harness background job instead. Verify:
+
+```sh
+curl -s http://127.0.0.1:1933/health   # {"status":"ok","healthy":true,...}
+ov status                              # "Connected (Healthy)", queue 0 pending / 0 errors
+```
+
+A stale `~/.openviking/pending/` queue (hundreds of files) from the downtime drains on its own — do not delete it.
+
+### Step 6 — Confirm the integration
+
+Within a turn of the server going healthy, the plugin reconnects (MCP tools answer, `<openviking-context>` appears at the next session start). If MCP tools still error after a full turn: restart the harness session once. Only then suspect the bundle (`~/.dsh/profiles/web/package.json` must list `@openviking/dsh-memory-plugin` in `dsh.profile.bundles`).
+
+If the plugin must be (re)installed, run from the **running host's checkout** (find it: `lsof -p <dsh-web-pid> | grep cwd`):
+
+```sh
+pnpm dsh plugin --profile web add @openviking/dsh-memory-plugin
+```
+
+This is the only install path that reconciles `dsh.profile.bundles` and survives profile rebuilds. With `patchReload: "live"` in the manifest the profile recomposes without a host restart and `<openviking-context>` returns mid-session.
+
+## 3. Verification checklist (all seven, in order)
+
+1. `openviking-server --version` → prints version
+2. `ls ~/.openviking/ov.conf ~/.openviking/ovcli.conf` → both exist
+3. `openviking-server doctor` → all PASS
+4. `curl -s http://127.0.0.1:1933/health` → `"healthy":true`
+5. `ov status` → Connected (Healthy), 0 errors
+6. `ov find "smoke test"` after any resource exists → ranked hits, not a connection error
+7. New session → `<openviking-context>` block present
+
+## 4. Known traps
+
+- `ov status` saying "Unreachable" while the server is fine → the language gate; run `ov language en` first.
+- Two config files, one directory (§1) — check the right one for the symptom.
+- `auth_mode: "dev"` = no auth, localhost only. Never bind `0.0.0.0` without switching to API-key auth (docs: Authentication guide).
+- Piped `init` answers are prompt-order-fragile (Step 3) — count prompts, don't trust defaults.
+- When a D4 peer-dependency rejection forces `dsh plugin allow-version`, allow the **exact** plugin version and then install by **exact pin** (`add pkg@0.5.16`, not a `^` range) — a caret range can resolve to a sibling version the exemption does not cover, and the install rolls back (RCA 2026-09-24).
 - Re-examine actual prompt output on every version bump; this sequence was tested against OpenViking 0.4.20 / plugin 0.3.2 (2026-09-16) and the wizard's prompts are not a stable contract.
 
 ## 5. Report the run — always, before finishing

package/.agents/skills/dsi-plugin-rack/rack.d.mts

@@ -0,0 +1,35 @@
+/** Type surface of the rack engine (rack.mjs) for test files. */
+declare const CACHE_VERSION: 2;
+export interface RackRow {
+	n: string;
+	id: string;
+	group?: 'owned' | 'external';
+	repo: string;
+	author?: string | null;
+	authorUrl?: string | null;
+	version?: string | null;
+	description?: string | null;
+	order?: number;
+	installSpec?: string;
+	installed: boolean;
+	pkg: string | null;
+	bundle: string | null;
+}
+export interface GardenRow {
+	id: string;
+	group: 'owned';
+	version: string | null;
+	description: string | null;
+	order: number;
+	installSpec: string;
+	repo: string;
+}
+export function scanGarden(gardenPath: string | undefined | null): GardenRow[];
+export function parseReff(text: string): { plugins: { id: string; repo: string; author: string | null; authorUrl: string | null }[]; warnings: { code: string; detail: string }[] };
+export function findDepKey(manifest: { deps: Record<string, string> }, id: string, repo?: string): string | null;
+export function readManifest(path: string): { deps: Record<string, string>; bundles: string[]; missing: boolean };
+export function isInstalled(manifest: { deps: Record<string, string> }, id: string, repo?: string): boolean;
+export function buildSnapshot(args: { reffPath?: string; manifestPath?: string; gardenPath?: string; profile?: string }): { snapshot: { v: number; generatedAt: string; profile: string; plugins: RackRow[] }; warnings: { code: string; detail: string }[] };
+export function toInstallSpec(repo: string): string;
+export function installOwned(manifestPath: string, row: { id: string; installSpec: string }): string;
+export function restoreClobberedBundles(manifestPath: string, preOwnedRows: { id: string; installSpec?: string; pkg?: string | null }[]): boolean;

package/.agents/skills/dsi-plugin-rack/rack.mjs

@@ -14,12 +14,12 @@
  * dependencies[id] AND dsh.profile.bundles includes id. Gates surface, they
  * never auto-clear (D6).
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-const CACHE_VERSION = 1;
+export const CACHE_VERSION = 2;
 
 function parseArgs(argv) {
 	const out = { command: argv[0], reload: false, reff: null, cache: null, manifest: null, profile: process.env.DSH_PROFILE ?? 'web', dshCmd: null, targets: [] };
@@ -30,6 +30,8 @@ function parseArgs(argv) {
 		else if (a === '--cache') out.cache = argv[++i];
 		else if (a === '--manifest') out.manifest = argv[++i];
 		else if (a === '--profile') out.profile = argv[++i];
+		else if (a === '--garden') out.garden = argv[++i];
+		else if (a === '--garden-repo') out.gardenRepo = argv[++i];
 		else if (a === '--dsh-cmd') out.dshCmd = argv[++i];
 		else out.targets.push(a);
 	}
@@ -54,6 +56,58 @@ export function parseReff(text) {
 	return { plugins, warnings };
 }
 
+
+/** Owned-species enumeration (ADR "The Plugin Garden" 2026-10-07, D1/D2):
+ *  every direct child of the garden dir with a package.json wiring
+ *  dsh.bundle.patch is one owned rack row, identified by its OWN package
+ *  name. Rows carry version/description from the same file and an optional
+ *  dsh.rack.order for display sort. Returns [] for a missing garden. */
+export function scanGarden(gardenPath) {
+	if (!gardenPath || !existsSync(gardenPath)) return [];
+	const rows = [];
+	for (const child of readdirSync(gardenPath, { withFileTypes: true })) {
+		if (!child.isDirectory()) continue;
+		const pkgPath = join(gardenPath, child.name, 'package.json');
+		if (!existsSync(pkgPath)) continue;
+		let pkg;
+		try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')); } catch { continue; }
+		const patch = pkg && pkg.dsh && pkg.dsh.bundle && pkg.dsh.bundle.patch;
+		if (!patch) continue;
+		const order = (pkg.dsh && pkg.dsh.rack && pkg.dsh.rack.order) ?? Number.POSITIVE_INFINITY;
+		rows.push({
+			id: pkg.name,
+			group: 'owned',
+			version: pkg.version ?? null,
+			description: pkg.description ?? null,
+			order,
+			installSpec: 'link:' + join(gardenPath, child.name),
+			repo: 'link:' + join(gardenPath, child.name)
+		});
+	}
+	return rows.sort((a, b) => (a.order - b.order) || a.id.localeCompare(b.id));
+}
+
+/** Repository identity (ADR-0016 D1): a catalog entry identifies a
+ *  REPOSITORY, not a URL string. Strip protocol, .git suffix, trailing
+ *  slashes and any /tree/<ref>(/...)? browse subtree, then keep the
+ *  owner/repo tail. Two URLs with the same identity are one rack group. */
+export function repoIdentity(url) {
+	const s = String(url || '')
+		.replace(/^[a-z+]+:(\/\/)?/i, '') // protocol (https://, git+, github:)
+		.split('/tree/')[0] // a github /tree/<ref>/... browse URL is a view INSIDE a repo
+		.replace(/\/+$/, '')
+		.replace(/\.git$/i, '')
+		.replace(/\/+$/, '');
+	return s.split('/').slice(-2).join('/');
+}
+
+/** Shared tail helper: last two path segments. findDepKey keeps a residual
+ *  subtree (deps may point at subfolders); repoIdentity cuts it entirely. */
+function repoTail(url) {
+	const s = String(url || '').replace(/\.git$/i, '').replace(/\/+$/, '');
+	return s.split('/').slice(-2).join('/');
+}
+
 /** D4 (amended 2026-09-27): the manifest's DEPENDENCIES are the install
  *  authority. pnpm records a git plugin under the package's REAL name from
  *  its own package.json (e.g. '@temoa/dsh-rules-paths'), not the reff id -
@@ -64,8 +118,11 @@ export function parseReff(text) {
  *  install gate. Returns the recorded dep key (the remove target) or null. */
 export function findDepKey(manifest, id, repo) {
 	if (manifest.deps[id] !== undefined) return id;
-	const tail = String(repo || '').replace(/\\.git$/, '').replace(/\/+$/, '').split('/').slice(-2).join('/');
-	if (!tail) return null;
+	// A github /tree/<ref>/ browse URL is the same repo, not a distinct plugin
+	// (identity rule: repoIdentity, ADR-0016 D1); a residual subtree segment is
+	// kept here because deps may legitimately point at subfolders.
+	const tail = repoTail(String(repo || '').replace(/\/tree\/[^/]+(\/|$)/, '/'));
+	if (!tail || tail === '/') return null;
 	for (const [key, value] of Object.entries(manifest.deps)) {
 		if (typeof value === 'string' && value.includes(tail)) return key;
 	}
@@ -89,39 +146,71 @@ export function isInstalled(manifest, id, repo) {
 	return findDepKey(manifest, id, repo) !== null;
 }
 
-export function buildSnapshot({ reffPath, manifestPath, profile }) {
+export function buildSnapshot({ reffPath, manifestPath, gardenPath, gardenRepo, profile }) {
 	const warnings = [];
-	if (!existsSync(reffPath)) warnings.push({ code: 'reff-missing', detail: reffPath });
-	const parsed = existsSync(reffPath) ? parseReff(readFileSync(reffPath, 'utf8')) : { plugins: [], warnings: [] };
-	warnings.push(...parsed.warnings);
 	const manifest = readManifest(manifestPath);
 	if (manifest.missing) warnings.push({ code: 'manifest-missing', detail: manifestPath });
+	const reconcile = (row) => {
+		const depKey = findDepKey(manifest, row.id, row.repo);
+		return { ...row, installed: depKey !== null, pkg: depKey, bundle: (depKey !== null && manifest.bundles.includes(depKey)) || null };
+	};
+	// Owned species first (garden scan), then external (reff) - flat rows,
+	// renumbered once; sources[] groups them by repo (shelf grammar).
+	const owned = scanGarden(gardenPath).map((row) => reconcile({ ...row, repo: gardenRepo ?? row.repo }));
+	const parsed = existsSync(reffPath) ? parseReff(readFileSync(reffPath, 'utf8')) : { plugins: [], warnings: [] };
+	warnings.push(...parsed.warnings);
+	// ADR-0016 D2/D3: an external reff row whose repository the garden already
+	// enumerates is SHADOWED — dropped here with a warning; the reff file itself
+	// is never rewritten and parseReff output is untouched.
+	const ownedIdents = new Set(owned.map((row) => repoIdentity(row.repo)));
+	const external = [];
+	for (const p of parsed.plugins) {
+		if (ownedIdents.has(repoIdentity(p.repo))) {
+			warnings.push({ code: 'reff-shadowed-by-garden', detail: p.id });
+			continue;
+		}
+		external.push(reconcile({
+			n: null,
+			id: p.id,
+			group: 'external',
+			repo: p.repo,
+			version: null,
+			description: null,
+			author: p.author,
+			...(p.authorUrl ? { authorUrl: p.authorUrl } : {})
+		}));
+	}
+	const plugins = [...owned, ...external].map((row, i) => ({ ...row, n: String(i + 1) }));
+	// sources[]: one collapsible group per REPOSITORY (Shelf Chrome grammar),
+	// keyed by repoIdentity (ADR-0016 D2) so /tree browse URLs never split a repo.
+	const sources = [];
+	const byRepo = new Map();
+	for (const row of plugins) {
+		const key = repoIdentity(row.repo);
+		if (!byRepo.has(key)) {
+			sources.push({
+				id: key,
+				name: key.split('/').pop(),
+				author: row.author ?? null,
+				repo: row.repo,
+				plugins: []
+			});
+			byRepo.set(key, sources[sources.length - 1]);
+		}
+		byRepo.get(key).plugins.push(row);
+	}
 	return {
 		snapshot: {
 			v: CACHE_VERSION,
 			generatedAt: new Date().toISOString(),
 			profile,
-			plugins: parsed.plugins.map((p, i) => {
-				const depKey = findDepKey(manifest, p.id, p.repo);
-				return {
-					n: String(i + 1),
-					id: p.id,
-					repo: p.repo,
-					author: p.author,
-					...(p.authorUrl ? { authorUrl: p.authorUrl } : {}),
-					installed: depKey !== null,
-					// The recorded dependency name (pnpm's truth) - the remove target.
-					pkg: depKey,
-					bundle: (depKey !== null && manifest.bundles.includes(depKey)) || null
-				};
-			})
+			sources,
+			plugins
 		},
 		warnings
 	};
 }
 
-/** D3: the reff URL becomes the dsh add spec: git+<url>.git (append .git
- *  only when absent — the operator's line stays the single source). */
 export function toInstallSpec(repo) {
 	return 'git+' + repo + (repo.endsWith('.git') ? '' : '.git');
 }
@@ -132,6 +221,47 @@ function resolveDshCommand(flags) {
 	return 'npx --yes @deepseek-ai/dsh@latest';
 }
 
+
+/** Owned-species install (Plugin Garden ADR, D3): write the link dependency,
+ *  APPEND (never rewrite) the bundle entry, idempotent on re-run. The only
+ *  manifest write the rack performs itself - scoped to @local link species;
+ *  git/npm species keep the dsh add delegation (D3). Returns the dep key. */
+export function installOwned(manifestPath, row) {
+	const doc = JSON.parse(readFileSync(manifestPath, 'utf8'));
+	doc.dependencies = doc.dependencies ?? {};
+	doc.dependencies[row.id] = row.installSpec;
+	const bundles = doc.dsh && doc.dsh.profile && Array.isArray(doc.dsh.profile.bundles) ? doc.dsh.profile.bundles : [];
+	if (!bundles.includes(row.id)) bundles.push(row.id);
+	if (doc.dsh && doc.dsh.profile) doc.dsh.profile.bundles = bundles;
+	writeFileSync(manifestPath, JSON.stringify(doc, null, 2));
+	return row.id;
+}
+
+/** Clobber guard (Plugin Garden ADR, 2026-10-07): a dsh plugin add rewrites
+ *  the bundles array to just the new plugin and may drop earlier deps.
+ *  Re-append every still-installed owned row's bundle entry and dep entry.
+ *  Rows already recorded pass through untouched. */
+export function restoreClobberedBundles(manifestPath, preOwnedRows) {
+	const doc = JSON.parse(readFileSync(manifestPath, 'utf8'));
+	let changed = false;
+	doc.dependencies = doc.dependencies ?? {};
+	const bundles = doc.dsh && doc.dsh.profile && Array.isArray(doc.dsh.profile.bundles) ? doc.dsh.profile.bundles : [];
+	for (const row of preOwnedRows) {
+		if (!row.pkg && !row.installSpec) continue;
+		if (doc.dependencies[row.id] === undefined) {
+			doc.dependencies[row.id] = row.installSpec;
+			changed = true;
+		}
+		if (!bundles.includes(row.id)) {
+			bundles.push(row.id);
+			changed = true;
+		}
+	}
+	if (doc.dsh && doc.dsh.profile) doc.dsh.profile.bundles = bundles;
+	if (changed) writeFileSync(manifestPath, JSON.stringify(doc, null, 2));
+	return changed;
+}
+
 /** D3/D6: run dsh, relay its own diagnostics verbatim on failure. */
 export function runDsh(flags, action, spec) {
 	const cmd = resolveDshCommand(flags) + ' plugin --profile ' + flags.profile + ' ' + action + ' ' + spec;
@@ -166,7 +296,7 @@ function main() {
 			console.log(JSON.stringify({ v: CACHE_VERSION, ok: true, reused: true, snapshot: loadSnapshot(cachePath) }));
 			return;
 		}
-		const { snapshot, warnings } = buildSnapshot({ reffPath, manifestPath, profile: args.profile });
+		const { snapshot, warnings } = buildSnapshot({ reffPath, manifestPath, gardenPath: args.garden, gardenRepo: args.gardenRepo, profile: args.profile });
 		mkdirSync(dirname(cachePath), { recursive: true });
 		writeFileSync(cachePath, JSON.stringify(snapshot, null, 2));
 		console.log(JSON.stringify({ v: CACHE_VERSION, ok: true, snapshot, ...(warnings.length ? { errors: warnings.map((w) => w.code + ': ' + w.detail) } : {}) }));
@@ -186,6 +316,17 @@ function main() {
 			if (!plugin) { results.push({ n: t, ok: false, error: 'not on the rack: ' + t }); continue; }
 			if (action === 'install') {
 				if (plugin.installed) { results.push({ n: plugin.n, id: plugin.id, ok: true, already: true }); continue; }
+				if (plugin.group === 'owned') {
+					// Owned species (Plugin Garden ADR, D3-scoped): link dep + bundles append + pnpm install.
+					const res = installOwned(manifestPath, plugin);
+					const inst = spawnSync('pnpm', ['install'], { cwd: dirname(manifestPath), encoding: 'utf8', timeout: 300000 });
+					if (inst.status !== 0) { results.push({ n: plugin.n, id: plugin.id, ok: false, error: 'pnpm install failed (exit ' + (inst.status ?? 1) + '): ' + String(inst.stderr ?? '').slice(-400) }); continue; }
+					plugin.installed = true;
+					plugin.pkg = res;
+					plugin.bundle = true;
+					results.push({ n: plugin.n, id: plugin.id, pkg: res, ok: true });
+					continue;
+				}
 				const r = runDsh(args, 'add', toInstallSpec(plugin.repo));
 				if (!r.ok) { results.push({ n: plugin.n, id: plugin.id, ok: false, error: r.error }); continue; }
 				const manifest = readManifest(manifestPath);
@@ -234,4 +375,5 @@ function fail(errors) {
 	process.exit(1);
 }
 
-main();
+// Run only when executed directly (not when imported by tests/other tools).
+if (process.argv[1] && import.meta.url === new URL('file://' + process.argv[1].replace(/\\/g, '/')).href) main();