@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/hub/cli.js

@@ -0,0 +1,81 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Harness } from "../harness.js";
+export const HUB_USAGE = `Usage: xagent hub <list | show | install> [id@version] [options]
+
+  list [--refresh]             Browse the curated catalog and locally installed versions
+  show <id@version>            Show publisher, license, source, and delivery details
+  install <id@version>         Install the exact reviewed version, disabled and untrusted
+
+  --data <dir>                 Target data library (default: ~/.xingular-harness/data)
+  --state <dir>                Target device state (default: ~/.xingular-harness/state)
+  --refresh                    Refresh the public catalog; cached items remain usable offline
+`;
+export async function runHubCli(argv, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    const args = [];
+    const values = {};
+    let refresh = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--refresh')
+            refresh = true;
+        else if (arg === '--data' || arg === '--state') {
+            const value = argv[++index];
+            if (!value || value.startsWith('--')) {
+                write(`${arg} needs a directory.\n`);
+                return 2;
+            }
+            values[arg.slice(2)] = resolve(value);
+        }
+        else if (arg.startsWith('--')) {
+            write(`Unknown option ${arg}.\n`);
+            return 2;
+        }
+        else
+            args.push(arg);
+    }
+    const [command, target] = args;
+    if (!command || command === 'help') {
+        write(HUB_USAGE);
+        return 0;
+    }
+    if (!['list', 'show', 'install'].includes(command)) {
+        write(HUB_USAGE);
+        return 2;
+    }
+    const root = join(dependencies.home ?? homedir(), '.xingular-harness');
+    const options = { dataRoot: values.data ?? join(root, 'data'), stateDir: values.state ?? join(root, 'state') };
+    const harness = dependencies.createHarness?.(options) ?? new Harness(options);
+    try {
+        const overview = await harness.hub.list(refresh);
+        if (overview.error)
+            write(`Catalog refresh failed: ${overview.error} Using ${overview.origin} content.\n`);
+        if (command === 'list') {
+            write(`Library: ${options.dataRoot}\n${overview.entries.map((entry) => `${entry.id}@${entry.version}  ${entry.category}  ${entry.title}${overview.installed.some((receipt) => receipt.entry.id === entry.id && receipt.entry.version === entry.version) ? ' · installed' : ''}`).join('\n')}\n`);
+            return 0;
+        }
+        const split = target?.lastIndexOf('@') ?? -1;
+        if (!target || split < 1)
+            throw new Error('Name an exact item as publisher/name@version. Run hub list to see versions.');
+        const id = target.slice(0, split);
+        const version = target.slice(split + 1);
+        const entry = await harness.hub.get(id, version);
+        if (command === 'show') {
+            const { bundled: _bundled, ...delivery } = entry.delivery.kind === 'pi-package' ? { ...entry.delivery, bundled: undefined } : entry.delivery;
+            write(`${entry.title} (${target})\n${entry.description}\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\nDelivery: ${JSON.stringify(delivery)}\n`);
+        }
+        else {
+            const receipt = await harness.hub.install(id, version);
+            write(receipt.document ? `Saved ${target} in ${options.dataRoot}/hub/documents/${receipt.document}. Open this library in a compatible application to apply it.\n` : `Installed ${target}, switched off. Attach it separately${entry.delivery.kind === 'pi-package' ? ' and review/trust any code' : ''} before using it.\n`);
+        }
+        return 0;
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        await harness.close();
+    }
+}

package/dist/sdk/hub/hub.d.ts

@@ -0,0 +1,74 @@
+import type { Harness } from "../harness.js";
+import { type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from "./schema.js";
+export interface HubOptions {
+    catalogUrl?: string;
+    catalog?: HubCatalog;
+    fetch?: typeof globalThis.fetch;
+}
+/** Catalog data never loads extensions or changes attachment, trust, or connector scopes. */
+export declare class Hub {
+    private readonly harness;
+    private readonly fallback;
+    private readonly fetcher;
+    private readonly catalogUrl;
+    private watcher;
+    private refresh;
+    private installing;
+    private cachedPayload;
+    get busy(): boolean;
+    constructor(harness: Harness, options?: HubOptions);
+    private receipts;
+    private snapshot;
+    private receiptState;
+    private present;
+    list(refresh?: boolean): Promise<HubOverview>;
+    private bytes;
+    private refreshCatalog;
+    private decode;
+    private find;
+    get(id: string, version: string, preview?: boolean): Promise<HubEntry>;
+    private verifiedPayload;
+    preview(id: string, version: string, offset?: number): Promise<{
+        entry: {
+            id: string;
+            title: string;
+            description: string;
+            publisher: string;
+            license: string;
+            version: string;
+            category: string;
+            channel: "official" | "community";
+            tags: string[];
+            requires: Record<string, string>;
+            sourceUrl: string;
+            delivery: {
+                url: string;
+                sha256: string;
+                kind: "registry";
+                registryKind: "skills" | "prompts" | "rules";
+                bundled?: string | undefined;
+            } | {
+                url: string;
+                sha256: string;
+                kind: "document";
+                bundled?: string | undefined;
+            } | {
+                kind: "pi-package";
+                source: string;
+            };
+        };
+        content: string;
+        offset: number;
+        nextOffset: number;
+        totalBytes: number;
+        done: boolean;
+    }>;
+    install(id: string, version: string): Promise<HubReceipt>;
+    uninstall(id: string, version: string): Promise<HubReceipt>;
+    readDocument(id: string, version: string): {
+        entry: HubEntry;
+        content: string;
+    };
+    watch(root: string): void;
+    close(): void;
+}

package/dist/sdk/hub/hub.js

@@ -0,0 +1,476 @@
+import { createHash } from 'node:crypto';
+import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { watch } from 'node:fs';
+import { HarnessError, invalid } from "../core/errors.js";
+import { atomicWrite, now, readJson, readJsonOr, writeJson } from "../core/fs.js";
+import * as pluginApi from "../plugins/api.js";
+import * as packages from "../plugins/install.js";
+import * as registry from "../variant/components.js";
+import * as attachments from "../plugins/attachments.js";
+import manifest from "../../../package.json" with { type: 'json' };
+import bundled from "./catalog.json" with { type: 'json' };
+import { HUB_CATALOG_URL, HUB_MAX_BYTES, HUB_PREVIEW_PAGE_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum } from "./schema.js";
+const variantVersion = manifest.version;
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const receiptName = (entry) => digest(`${entry.id}@${entry.version}`);
+/** Acquires an exclusive writer lock. A crashed writer's lock is recovered only when its PID is gone. */
+function acquire(path) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    try {
+        const file = openSync(path, 'wx', 0o600);
+        try {
+            writeFileSync(file, `${process.pid}`);
+        }
+        finally {
+            closeSync(file);
+        }
+        return () => rmSync(path, { force: true });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        // Serialize stale-lock recovery too: two reapers must never remove a new writer's lock.
+        let recovery;
+        try {
+            recovery = openSync(`${path}.recovery`, 'wx', 0o600);
+        }
+        catch {
+            throw new HarnessError('hub_busy', 'Another installation is using this library. Wait and retry.');
+        }
+        try {
+            const pid = Number(readFileSync(path, 'utf8'));
+            if (Number.isInteger(pid) && pid > 0) {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (probe) {
+                    if (probe.code === 'ESRCH') {
+                        rmSync(path);
+                        return acquire(path);
+                    }
+                }
+            }
+            throw new HarnessError('hub_busy', 'Another installation is using this library. Wait for it to finish and retry.');
+        }
+        finally {
+            closeSync(recovery);
+            rmSync(`${path}.recovery`, { force: true });
+        }
+    }
+}
+/** Catalog data never loads extensions or changes attachment, trust, or connector scopes. */
+export class Hub {
+    harness;
+    fallback;
+    fetcher;
+    catalogUrl;
+    watcher = null;
+    refresh = null;
+    installing = false;
+    cachedPayload = null;
+    get busy() { return this.installing; }
+    constructor(harness, options = {}) {
+        this.harness = harness;
+        this.fallback = hubCatalogSchema.parse(options.catalog ?? bundled);
+        this.fetcher = options.fetch ?? globalThis.fetch;
+        this.catalogUrl = options.catalogUrl ?? HUB_CATALOG_URL;
+    }
+    receipts() {
+        const root = this.harness.dataRoot;
+        if (!root)
+            return [];
+        const values = readJson(join(root, 'hub', 'installed.json')) ?? [];
+        if (!Array.isArray(values))
+            throw invalid('The hub installation records could not be read.');
+        return values.map((value) => hubReceiptSchema.parse(value));
+    }
+    snapshot() {
+        const cached = readJsonOr(join(this.harness.stateDir, 'hub', 'catalog.json'), null);
+        const parsed = hubCatalogSchema.safeParse(cached?.catalog);
+        const catalog = parsed.success ? parsed.data : this.fallback;
+        const installed = this.receipts().map((receipt) => ({ ...receipt, state: this.receiptState(receipt) }));
+        const entries = new Map(catalog.entries.map((entry) => [`${entry.id}@${entry.version}`, entry]));
+        for (const receipt of installed)
+            if (!entries.has(`${receipt.entry.id}@${receipt.entry.version}`))
+                entries.set(`${receipt.entry.id}@${receipt.entry.version}`, receipt.entry);
+        return { entries: [...entries.values()], installed, origin: parsed.success ? 'cached' : 'bundled', refreshedAt: parsed.success ? cached.at : null, error: null, dataRoot: this.harness.dataRoot, stateDir: this.harness.stateDir };
+    }
+    receiptState(receipt) {
+        if (receipt.document && receipt.entry.delivery.kind === 'document') {
+            if (receipt.document !== `${receiptName(receipt.entry)}.json`)
+                return 'incomplete';
+            try {
+                const path = join(this.harness.dataRoot, 'hub', 'documents', receipt.document);
+                const stat = lstatSync(path);
+                if (!stat.isFile() || stat.size > HUB_MAX_BYTES)
+                    return 'incomplete';
+                return digest(readFileSync(path)) === receipt.entry.delivery.sha256 ? 'installed' : 'changed';
+            }
+            catch {
+                return 'incomplete';
+            }
+        }
+        return this.present(receipt) ? 'installed' : 'incomplete';
+    }
+    present(receipt) {
+        const root = this.harness.dataRoot;
+        if (!root)
+            return false;
+        try {
+            if (receipt.document) {
+                if (receipt.entry.delivery.kind !== 'document' || receipt.document !== `${receiptName(receipt.entry)}.json`)
+                    return false;
+                const path = join(root, 'hub', 'documents', receipt.document);
+                const stat = lstatSync(path);
+                return stat.isFile() && stat.size <= HUB_MAX_BYTES && digest(readFileSync(path)) === receipt.entry.delivery.sha256;
+            }
+            if (receipt.entry.delivery.kind === 'registry')
+                return receipt.resourceIds.length > 0 && receipt.resourceIds.every((id) => {
+                    if (!/^(skills|prompts|rules)\/[a-z0-9-]{1,64}$/.test(id))
+                        return false;
+                    const [kind, name] = id.split('/');
+                    return lstatSync(join(root, 'registry', kind, kind === 'skills' ? `${name}/SKILL.md` : `${name}.md`)).isFile();
+                });
+            if (receipt.entry.delivery.kind === 'pi-package') {
+                const source = receipt.entry.delivery.source;
+                const settings = readJsonOr(join(this.harness.accountsDir, '_shared', 'pi', 'settings.json'), {});
+                return settings.packages?.some((item) => (typeof item === 'string' ? item : item.source) === source) ?? false;
+            }
+        }
+        catch {
+            return false;
+        }
+        return false;
+    }
+    async list(refresh = false) {
+        if (!refresh)
+            return this.snapshot();
+        this.refresh ??= this.refreshCatalog().finally(() => { this.refresh = null; });
+        return this.refresh;
+    }
+    async bytes(url) {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash || parsed.port || parsed.hostname !== 'raw.githubusercontent.com')
+            throw invalid('Hub downloads must use public raw.githubusercontent.com HTTPS URLs.');
+        const response = await this.fetcher(url, { redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(30_000) });
+        if (!response.ok)
+            throw new Error(`The catalog source returned ${response.status}.`);
+        if (Number(response.headers.get('content-length') ?? 0) > HUB_MAX_BYTES)
+            throw invalid('The hub download exceeds 16 MiB.');
+        if (!response.body)
+            throw invalid('The hub download has no body.');
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > HUB_MAX_BYTES)
+                    throw invalid('The hub download exceeds 16 MiB.');
+                chunks.push(value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+        }
+        return Buffer.concat(chunks);
+    }
+    async refreshCatalog() {
+        try {
+            const catalog = hubCatalogSchema.parse(JSON.parse(this.decode(await this.bytes(this.catalogUrl))));
+            writeJson(join(this.harness.stateDir, 'hub', 'catalog.json'), { catalog, at: now() });
+            this.harness.bus.emit({ type: 'hub.changed' });
+            return { ...this.snapshot(), origin: 'remote' };
+        }
+        catch (error) {
+            return { ...this.snapshot(), error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    decode(bytes) {
+        const text = bytes.toString('utf8');
+        if (!Buffer.from(text).equals(bytes))
+            throw invalid('Hub JSON must use valid UTF-8.');
+        return text;
+    }
+    find(id, version) {
+        const entry = this.snapshot().entries.find((item) => item.id === id && item.version === version);
+        if (!entry)
+            throw invalid('That item version is not in this catalog. Refresh the Hub and try again.');
+        return entry;
+    }
+    async get(id, version, preview = false) {
+        const entry = this.find(id, version);
+        if (!preview || entry.delivery.kind === 'pi-package' || entry.delivery.bundled !== undefined)
+            return entry;
+        const bytes = await this.bytes(entry.delivery.url);
+        if (digest(bytes) !== entry.delivery.sha256)
+            throw invalid('The downloaded item differs from the reviewed version.');
+        return { ...entry, delivery: { ...entry.delivery, bundled: this.decode(bytes) } };
+    }
+    async verifiedPayload(entry) {
+        if (entry.delivery.kind === 'pi-package')
+            throw invalid('Packages do not have a JSON payload preview.');
+        const key = `${entry.id}@${entry.version}`;
+        if (this.cachedPayload?.key === key && this.cachedPayload.expiresAt > Date.now())
+            return this.cachedPayload.bytes;
+        const bytes = entry.delivery.bundled === undefined ? await this.bytes(entry.delivery.url) : Buffer.from(entry.delivery.bundled);
+        if (digest(bytes) !== entry.delivery.sha256)
+            throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.');
+        this.decode(bytes);
+        this.cachedPayload = { key, bytes, expiresAt: Date.now() + 5 * 60 * 1000 };
+        return bytes;
+    }
+    async preview(id, version, offset = 0) {
+        if (!Number.isSafeInteger(offset) || offset < 0)
+            throw invalid('Preview offset must be a non-negative byte position.');
+        const entry = this.find(id, version);
+        const bytes = await this.verifiedPayload(entry);
+        if (offset > bytes.length || offset < bytes.length && (bytes[offset] & 0xc0) === 0x80)
+            throw invalid('Preview offset is outside the payload or splits a UTF-8 character.');
+        let end = Math.min(offset + HUB_PREVIEW_PAGE_BYTES, bytes.length);
+        while (end > offset && end < bytes.length && (bytes[end] & 0xc0) === 0x80)
+            end -= 1;
+        const content = this.decode(bytes.subarray(offset, end));
+        return { entry, content, offset, nextOffset: end, totalBytes: bytes.length, done: end >= bytes.length };
+    }
+    async install(id, version) {
+        const root = this.harness.env.root;
+        const entry = hubEntrySchema.parse(this.find(id, version));
+        if (entry.requires.harness && !meetsMinimum(variantVersion, entry.requires.harness))
+            throw invalid(`This item requires Harness ${entry.requires.harness} or newer.`);
+        const releaseState = acquire(join(this.harness.stateDir, 'hub', 'install.lock'));
+        this.installing = true;
+        let releaseData = null;
+        try {
+            releaseData = acquire(join(root, 'hub', 'install.lock'));
+            const records = this.receipts();
+            const existing = records.find((receipt) => receipt.entry.id === id && receipt.entry.version === version);
+            if (existing && this.present(existing))
+                return existing;
+            if (existing)
+                throw invalid('This Hub receipt is changed or incomplete. Uninstall it before installing this version again.');
+            const remaining = records.filter((record) => record !== existing);
+            const receipt = { entry, installedAt: now(), resourceIds: [], document: null };
+            const choicesBefore = attachments.load(root);
+            if (entry.delivery.kind === 'pi-package') {
+                const source = entry.delivery.source;
+                if (remaining.some((record) => record.entry.id === id && this.present(record)))
+                    throw invalid('Another version is already installed. Manage the existing plugin before replacing it.');
+                const before = await pluginApi.list(this.harness, {});
+                const identity = (value) => value.slice(0, value.lastIndexOf('@'));
+                if (before.some((plugin) => plugin.install && identity(plugin.install.source) === identity(source)))
+                    throw invalid('This package is already installed. Manage it in Plugins.');
+                const after = await packages.install(this.harness, { source });
+                receipt.resourceIds = after.filter((plugin) => plugin.install?.source === source && !before.some((old) => old.id === plugin.id)).map((plugin) => plugin.id);
+                if (!receipt.resourceIds.length)
+                    throw invalid('The package did not add an installable plugin. No hub installation was recorded.');
+            }
+            else {
+                const delivery = entry.delivery;
+                const bytes = await this.verifiedPayload(entry);
+                const text = this.decode(bytes);
+                if (delivery.kind === 'document') {
+                    JSON.parse(text);
+                    receipt.document = `${receiptName(entry)}.json`;
+                    const documentPath = join(root, 'hub', 'documents', receipt.document);
+                    try {
+                        lstatSync(documentPath);
+                        throw invalid('A file already exists at the Hub document path. Review or remove it before installing.');
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                    atomicWrite(documentPath, bytes);
+                }
+                else {
+                    const payload = JSON.parse(text);
+                    const previous = new Set(registry.list(root).map((item) => item.id));
+                    const imported = registry.importItems(root, delivery.registryKind, payload.items);
+                    receipt.resourceIds = imported.filter((item) => !previous.has(item.id)).map((item) => item.id);
+                    const choices = structuredClone(choicesBefore);
+                    const ids = new Set(receipt.resourceIds);
+                    for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+                        scope.on = scope.on.filter((id) => !ids.has(id));
+                        scope.off = scope.off.filter((id) => !ids.has(id));
+                    }
+                    attachments.save(root, choices);
+                }
+            }
+            try {
+                writeJson(join(root, 'hub', 'installed.json'), [...remaining, receipt]);
+            }
+            catch (error) {
+                if (receipt.document)
+                    rmSync(join(root, 'hub', 'documents', receipt.document), { force: true });
+                if (entry.delivery.kind === 'registry')
+                    for (const id of receipt.resourceIds) {
+                        const [kind, name] = id.split('/');
+                        rmSync(join(root, 'registry', kind, kind === 'skills' ? name : `${name}.md`), { recursive: true, force: true });
+                    }
+                if (entry.delivery.kind === 'registry')
+                    attachments.save(root, choicesBefore);
+                if (entry.delivery.kind === 'pi-package')
+                    for (const pluginId of receipt.resourceIds)
+                        await packages.removeDirect(this.harness, { pluginId });
+                throw error;
+            }
+            this.harness.bus.emit({ type: 'hub.changed' });
+            this.harness.bus.emit({ type: 'plugins.changed' });
+            return receipt;
+        }
+        finally {
+            this.installing = false;
+            releaseData?.();
+            releaseState();
+        }
+    }
+    async uninstall(id, version) {
+        const root = this.harness.env.root;
+        const releaseState = acquire(join(this.harness.stateDir, 'hub', 'install.lock'));
+        this.installing = true;
+        let releaseData = null;
+        try {
+            releaseData = acquire(join(root, 'hub', 'install.lock'));
+            const records = this.receipts();
+            const receipt = records.find((item) => item.entry.id === id && item.entry.version === version);
+            if (!receipt)
+                throw invalid('This Hub installation receipt no longer exists.');
+            const staged = mkdtempSync(join(root, 'hub', '.uninstall-'));
+            const moves = [];
+            let choicesBefore = null;
+            let committed = false;
+            let rollbackComplete = true;
+            try {
+                const ownedPaths = [];
+                if (receipt.document) {
+                    if (receipt.entry.delivery.kind !== 'document' || receipt.document !== `${receiptName(receipt.entry)}.json`)
+                        throw invalid('The Hub receipt has an invalid document path.');
+                    const path = join(root, 'hub', 'documents', receipt.document);
+                    try {
+                        const stat = lstatSync(path);
+                        if (!stat.isFile())
+                            throw invalid('The receipt-owned document path is not a regular file; it was left untouched.');
+                        ownedPaths.push(path);
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                if (receipt.entry.delivery.kind === 'registry') {
+                    const expectedKind = receipt.entry.delivery.registryKind;
+                    for (const id of receipt.resourceIds) {
+                        if (!/^(skills|prompts|rules)\/[a-z0-9-]{1,64}$/.test(id))
+                            throw invalid('The Hub receipt contains an invalid registry resource path.');
+                        const [kind, name] = id.split('/');
+                        if (kind !== expectedKind)
+                            throw invalid('The Hub receipt contains a resource outside its registry kind.');
+                        const path = join(root, 'registry', kind, kind === 'skills' ? name : `${name}.md`);
+                        try {
+                            lstatSync(path);
+                            ownedPaths.push(path);
+                        }
+                        catch (error) {
+                            if (error.code !== 'ENOENT')
+                                throw error;
+                        }
+                    }
+                    choicesBefore = attachments.load(root);
+                    const choices = structuredClone(choicesBefore);
+                    const owned = new Set(receipt.resourceIds);
+                    for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+                        scope.on = scope.on.filter((value) => !owned.has(value));
+                        scope.off = scope.off.filter((value) => !owned.has(value));
+                    }
+                    for (let index = 0; index < ownedPaths.length; index += 1) {
+                        const source = ownedPaths[index];
+                        const destination = join(staged, String(index));
+                        renameSync(source, destination);
+                        moves.push({ source, staged: destination });
+                    }
+                    attachments.save(root, choices);
+                }
+                else {
+                    for (let index = 0; index < ownedPaths.length; index += 1) {
+                        const source = ownedPaths[index];
+                        const destination = join(staged, String(index));
+                        renameSync(source, destination);
+                        moves.push({ source, staged: destination });
+                    }
+                }
+                if (receipt.entry.delivery.kind === 'pi-package')
+                    for (const pluginId of receipt.resourceIds) {
+                        if ((await pluginApi.list(this.harness, {})).some((plugin) => plugin.id === pluginId && plugin.install))
+                            await packages.removeDirect(this.harness, { pluginId });
+                    }
+                writeJson(join(root, 'hub', 'installed.json'), records.filter((item) => item !== receipt));
+                committed = true;
+                try {
+                    rmSync(staged, { recursive: true, force: true });
+                }
+                catch { /* The receipt is removed; leave the staged copy for disk recovery. */ }
+                this.cachedPayload = this.cachedPayload?.key === `${id}@${version}` ? null : this.cachedPayload;
+                this.harness.bus.emit({ type: 'hub.changed' });
+                this.harness.bus.emit({ type: 'plugins.changed' });
+                return receipt;
+            }
+            catch (error) {
+                if (!committed) {
+                    if (choicesBefore)
+                        try {
+                            attachments.save(root, choicesBefore);
+                        }
+                        catch { /* Preserve the original failure and restore the owned files below. */ }
+                    for (const move of moves.reverse()) {
+                        try {
+                            lstatSync(move.staged);
+                            renameSync(move.staged, move.source);
+                        }
+                        catch {
+                            rollbackComplete = false;
+                        }
+                    }
+                    if (rollbackComplete)
+                        try {
+                            rmSync(staged, { recursive: true, force: true });
+                        }
+                        catch { /* Keep the staging directory for recovery. */ }
+                }
+                throw error;
+            }
+        }
+        finally {
+            this.installing = false;
+            releaseData?.();
+            releaseState();
+        }
+    }
+    readDocument(id, version) {
+        const receipt = this.receipts().find((item) => item.entry.id === id && item.entry.version === version);
+        if (!receipt?.document || receipt.document !== `${receiptName(receipt.entry)}.json`)
+            throw invalid('Install this document before opening it.');
+        const path = join(this.harness.env.root, 'hub', 'documents', receipt.document);
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.size > HUB_MAX_BYTES)
+            throw invalid('The saved document is not a bounded regular file.');
+        const content = readFileSync(path, 'utf8');
+        if (receipt.entry.delivery.kind === 'pi-package' || digest(content) !== receipt.entry.delivery.sha256)
+            throw invalid('The saved document differs from the installed version. Import edited files explicitly instead.');
+        return { entry: receipt.entry, content };
+    }
+    watch(root) {
+        this.watcher?.close();
+        mkdirSync(join(root, 'hub'), { recursive: true });
+        this.watcher = watch(join(root, 'hub'), { persistent: false }, (_event, name) => {
+            if (name === 'installed.json')
+                this.harness.bus.emit({ type: 'hub.changed' });
+        });
+        this.watcher.on('error', () => { this.watcher?.close(); this.watcher = null; });
+    }
+    close() { this.watcher?.close(); this.watcher = null; }
+}