@xingular/harness 0.1.6 → 2.0.0

package/src/hub/catalog.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "entries": [
+    {
+      "id": "xingular/evidence-first",
+      "title": "Evidence first",
+      "description": "Keep observations, inferences, and unknowns distinct.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "rule",
+      "channel": "official",
+      "tags": [
+        "rule"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/evidence-first/1.0.0",
+      "delivery": {
+        "kind": "registry",
+        "registryKind": "rules",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/evidence-first/1.0.0/payload.json",
+        "sha256": "0f77661ea41e27bcb51aad982d15d493b893c5c1ba1eb6046a21315ddac07c5b",
+        "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-evidence-first\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: Evidence first\\ndescription: Distinguish observations, inferences, and unknowns.\\n---\\n\\nSupport factual claims with inspectable evidence. Label inferences and uncertainties. Correct a claim when better evidence changes it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+      }
+    },
+    {
+      "id": "xingular/github-connector",
+      "title": "GitHub connector",
+      "description": "A setup recipe for the GitHub MCP server; provide your own credentials.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "connector",
+      "channel": "official",
+      "tags": [
+        "connector"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/github-connector/1.0.0",
+      "delivery": {
+        "kind": "document",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/github-connector/1.0.0/payload.json",
+        "sha256": "ec5bd9675e2977b9d880cf81732d84ac72b04af271048499415eaa6288896223",
+        "bundled": "{\n  \"id\": \"github-hub\",\n  \"name\": \"GitHub\",\n  \"description\": \"Repositories, issues, and pull requests\",\n  \"kind\": \"remote\",\n  \"docsUrl\": \"https://github.com/github/github-mcp-server\",\n  \"url\": \"https://api.githubcopilot.com/mcp/\",\n  \"auth\": \"headers\",\n  \"oauth\": null,\n  \"fields\": [\n    {\n      \"header\": \"Authorization\",\n      \"label\": \"Personal access token\",\n      \"prefix\": \"Bearer \",\n      \"help\": \"Provide a token for only the repositories and permissions you need.\"\n    }\n  ],\n  \"setup\": [\n    \"Create a personal access token in GitHub with the access you want to grant.\",\n    \"Review the connection before enabling it.\"\n  ],\n  \"notice\": null,\n  \"provenance\": null,\n  \"suggestedReadTools\": []\n}\n"
+      }
+    },
+    {
+      "id": "xingular/research-starter",
+      "title": "Research starter",
+      "description": "A starting agent for comparing sources and writing supported answers.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "agent-template",
+      "channel": "official",
+      "tags": [
+        "agent-template"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/research-starter/1.0.0",
+      "delivery": {
+        "kind": "document",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/research-starter/1.0.0/payload.json",
+        "sha256": "a2f672583df6f4049cc153ba1e173192301220e5f8817f9ad5a4fe87af25f52b",
+        "bundled": "{\n  \"schemaVersion\": 1,\n  \"id\": \"research-starter\",\n  \"title\": \"Research starter\",\n  \"description\": \"Compare sources and explain the evidence behind an answer.\",\n  \"version\": \"1.0.0\",\n  \"author\": \"Xingular\",\n  \"license\": \"MIT\",\n  \"agent\": {\n    \"name\": \"Research starter\",\n    \"icon\": {\n      \"kind\": \"mascot\",\n      \"shape\": \"prism\",\n      \"color\": \"violet\",\n      \"material\": \"glass\"\n    },\n    \"description\": \"Investigates questions with sources.\",\n    \"instructions\": \"Help the user investigate a question. Start with reliable sources, explain what the evidence supports, cite the sources, and state unresolved questions. Ask the user when their goal is unclear.\",\n    \"model\": null,\n    \"effort\": \"high\",\n    \"tools\": [\n      \"read\",\n      \"grep\",\n      \"find\",\n      \"ls\",\n      \"web_search\",\n      \"web_fetch\"\n    ]\n  },\n  \"skills\": [],\n  \"connections\": []\n}\n"
+      }
+    },
+    {
+      "id": "xingular/source-review",
+      "title": "Review a source",
+      "description": "Check who wrote a source, what it supports, and what remains uncertain.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "skill",
+      "channel": "official",
+      "tags": [
+        "skill"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/source-review/1.0.0",
+      "delivery": {
+        "kind": "registry",
+        "registryKind": "skills",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/source-review/1.0.0/payload.json",
+        "sha256": "bb0617889ee1ca39611a10952bec3086fa3986e9ce10a809c473c57acf47bc07",
+        "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-source-review\",\n      \"files\": [\n        {\n          \"path\": \"SKILL.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: hub-source-review\\ndescription: Review the evidence behind a source before using its claims.\\n---\\n\\n# Review a source\\n\\nRecord its author and date. Identify the original evidence. Write what the source supports and which uncertainties remain. Cite the source so the reader can inspect it.\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+      }
+    },
+    {
+      "id": "xingular/summarize-source",
+      "title": "Summarize a source",
+      "description": "Summarize a provided source and explain its limitations.",
+      "publisher": "Xingular",
+      "license": "MIT",
+      "version": "1.0.0",
+      "category": "prompt",
+      "channel": "official",
+      "tags": [
+        "prompt"
+      ],
+      "requires": {
+        "harness": "0.1.6"
+      },
+      "sourceUrl": "https://github.com/tanntnny/xingular-hub/tree/main/entries/xingular/summarize-source/1.0.0",
+      "delivery": {
+        "kind": "registry",
+        "registryKind": "prompts",
+        "url": "https://raw.githubusercontent.com/tanntnny/xingular-hub/main/entries/xingular/summarize-source/1.0.0/payload.json",
+        "sha256": "12a646d474fe3cd822970869c972d1d9400c7f6350388dc735dce5c31a22680a",
+        "bundled": "{\n  \"items\": [\n    {\n      \"name\": \"hub-summarize-source\",\n      \"files\": [\n        {\n          \"path\": \"CONTENT.md\",\n          \"encoding\": \"utf8\",\n          \"content\": \"---\\nname: summarize-source\\ndescription: Summarize the supplied source and its limits.\\n---\\n\\nSummarize the source below. Include its main claims, supporting evidence, limitations, and questions it leaves unanswered.\\n\\n$@\\n\"\n        }\n      ]\n    }\n  ]\n}\n"
+      }
+    }
+  ]
+}

package/src/hub/cli.ts

@@ -0,0 +1,59 @@
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { Harness, type HarnessOptions } from '../harness'
+
+export const HUB_USAGE = `Usage: xingular-harness 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: string[], dependencies: { home?: string; write?: (text: string) => void; createHarness?: (options: HarnessOptions) => Harness } = {}): Promise<number> {
+  const write = dependencies.write ?? ((text: string) => void process.stdout.write(text))
+  const args: string[] = []
+  const values: Record<string, string> = {}
+  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: HarnessOptions = { 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/src/hub/hub.test.ts

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Bus } from '../core/bus'
+import { Harness } from '../harness'
+import { memorySecretStore } from '../accounts/secrets'
+import * as registry from '../skills/registry'
+import { Hub } from './hub'
+import { hubCatalogSchema, hubEntrySchema, type HubEntry } from './schema'
+import { runHubMenu } from '../terminal/hubMenu'
+import { SessionSocket } from '../terminal/socket'
+import { HarnessError } from '../core/errors'
+import { runHubCli } from './cli'
+import * as packageApi from '../plugins/api'
+import * as packageInstall from '../plugins/install'
+import type { Plugin } from '../plugins/types'
+
+const folders: string[] = []
+afterEach(() => { vi.restoreAllMocks(); for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }) })
+function entry(kind: 'document' | 'registry' = 'document', content = '{"message":"data only"}'): HubEntry {
+  return hubEntrySchema.parse({ id: 'example/review', title: 'Review', description: 'A reviewed item.', publisher: 'Example', license: 'MIT', version: '1.0.0', category: kind === 'document' ? 'preset' : 'skill', channel: 'community', tags: [], requires: {}, sourceUrl: 'https://github.com/example/review', delivery: { kind, ...(kind === 'registry' ? { registryKind: 'skills' } : {}), url: 'https://raw.githubusercontent.com/example/review/main/payload.json', sha256: createHash('sha256').update(content).digest('hex'), bundled: content } })
+}
+function fixture(items: HubEntry[], fetcher?: typeof fetch) {
+  const root = mkdtempSync(join(tmpdir(), 'hub-test-')); folders.push(root)
+  const harness = { dataRoot: join(root, 'data'), stateDir: join(root, 'state'), env: { root: join(root, 'data') }, bus: new Bus() } as Harness
+  const hub = new Hub(harness, { catalog: { schemaVersion: 1, entries: items }, fetch: fetcher })
+  return { hub, harness, root: harness.env.root }
+}
+const skill = (name = 'review', path = 'SKILL.md') => JSON.stringify({ items: [{ name, files: [{ path, encoding: 'utf8', content: '---\nname: review\ndescription: Review evidence.\n---\n\nRead sources.' }] }] })
+
+describe('Hub installation', () => {
+  it('stores documents inertly, idempotently, and checks their digest on read', async () => {
+    const { hub, root } = fixture([entry()])
+    const receipt = await hub.install('example/review', '1.0.0')
+    expect(receipt.resourceIds).toEqual([])
+    expect(await hub.install('example/review', '1.0.0')).toEqual(receipt)
+    expect(hub.readDocument('example/review', '1.0.0').content).toContain('data only')
+    expect(existsSync(join(root, 'config', 'plugin-attachments.json'))).toBe(false)
+    writeFileSync(join(root, 'hub', 'documents', receipt.document!), '{"edited":true}')
+    expect(() => hub.readDocument('example/review', '1.0.0')).toThrow('differs')
+  })
+  it('imports complete skills disabled and refuses overwriting local files', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    const receipt = await hub.install('example/review', '1.0.0')
+    expect(receipt.resourceIds).toEqual(['skills/review'])
+    expect(registry.enabledFor(root, null)).toEqual([])
+    const content = readFileSync(join(root, 'registry', 'skills', 'review', 'SKILL.md'), 'utf8')
+    const collision = { ...entry('registry', skill()), id: 'other/review' }
+    const another = new Hub(({ dataRoot: root, env: { root }, stateDir: join(root, 'state'), bus: new Bus() }) as Harness, { catalog: { schemaVersion: 1, entries: [collision] } })
+    await expect(another.install(collision.id, collision.version)).rejects.toThrow('already exists')
+    expect(readFileSync(join(root, 'registry', 'skills', 'review', 'SKILL.md'), 'utf8')).toBe(content)
+  })
+  it.each(['../escape', 'folder/../../escape', 'C:/escape', '.hidden/SKILL.md'])('rejects registry path %s before writing', async (path) => {
+    const { hub, root } = fixture([entry('registry', skill('review', path))])
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow()
+    expect(registry.list(root)).toEqual([])
+    expect(existsSync(join(root, 'hub', 'installed.json'))).toBe(false)
+  })
+  it('imports prompts and rules as single Markdown files, disabled', async () => {
+    for (const kind of ['prompts', 'rules'] as const) {
+      const item = entry('registry', JSON.stringify({ items: [{ name: 'review', files: [{ path: 'CONTENT.md', encoding: 'utf8', content: '# Review\nRead evidence.' }] }] }))
+      if (item.delivery.kind === 'registry') item.delivery.registryKind = kind
+      const { hub, root } = fixture([item])
+      await hub.install(item.id, item.version)
+      expect(readFileSync(join(root, 'registry', kind, 'review.md'), 'utf8')).toContain('Read evidence')
+      expect(registry.enabledFor(root, null)).toEqual([])
+    }
+  })
+  it('does not commit a download with the wrong digest', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const { hub, root } = fixture([item], (async () => new Response('{"different":true}')) as typeof fetch)
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('differs')
+    expect(existsSync(join(root, 'hub', 'installed.json'))).toBe(false)
+    expect(hub.busy).toBe(false)
+  })
+  it('rejects malformed UTF-8 JSON even when its byte digest matches', async () => {
+    const bytes = Buffer.from([0x7b, 0x22, 0x78, 0x22, 0x3a, 0x22, 0xff, 0x22, 0x7d])
+    const item = entry()
+    if (item.delivery.kind !== 'pi-package') { delete item.delivery.bundled; item.delivery.sha256 = createHash('sha256').update(bytes).digest('hex') }
+    const { hub, root } = fixture([item], (async () => new Response(bytes)) as typeof fetch)
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('valid UTF-8')
+    expect(existsSync(join(root, 'hub', 'installed.json'))).toBe(false)
+  })
+  it('previews reviewed bytes without creating files or receipts', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const { hub, root } = fixture([item], (async () => new Response('{"message":"data only"}')) as typeof fetch)
+    const preview = await hub.get(item.id, item.version, true)
+    expect(preview.delivery.kind !== 'pi-package' && preview.delivery.bundled).toContain('data only')
+    expect(existsSync(join(root, 'hub'))).toBe(false)
+  })
+  it('can reinstall deleted resources and clears stale attachment grants', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    await hub.install('example/review', '1.0.0')
+    registry.setEnabled(root, null, ['skills/review'])
+    rmSync(join(root, 'registry', 'skills', 'review'), { recursive: true })
+    expect((await hub.list()).installed).toEqual([])
+    await hub.install('example/review', '1.0.0')
+    expect(registry.enabledFor(root, null)).toEqual([])
+    expect((await hub.list()).installed).toHaveLength(1)
+  })
+  it('preserves corrupt installation records rather than overwriting them', async () => {
+    const { hub, root } = fixture([entry()])
+    mkdirSync(join(root, 'hub'), { recursive: true })
+    writeFileSync(join(root, 'hub', 'installed.json'), 'corrupt')
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('could not be read')
+    expect(readFileSync(join(root, 'hub', 'installed.json'), 'utf8')).toBe('corrupt')
+  })
+  it('requires the terminal extension control key for hub mutations', async () => {
+    const { hub, root } = fixture([entry()])
+    const socket = new SessionSocket(join(root, 'unused.sock'), { memory: () => '', apps: async () => null,
+      plugins: async (_grant, method, params, control) => {
+        if (method === 'hub.list') return hub.list()
+        if (!control) throw new HarnessError('unauthorized', 'Only the terminal controls installations.')
+        return hub.install(String(params.id), String(params.version))
+      } })
+    const token = socket.issue({ sessionId: 'terminal', caller: () => ({}), broker: null })
+    const install = { token, call: 'hub.install', params: { id: 'example/review', version: '1.0.0' } }
+    expect(await socket.handle(JSON.stringify(install))).toHaveProperty('error')
+    const claim = await socket.handle(JSON.stringify({ token, call: 'control.claim' })) as { result: { key: string } }
+    expect(await socket.handle(JSON.stringify({ ...install, control: claim.result.key }))).toHaveProperty('result.document')
+    await socket.close()
+  })
+  it('CLI installs into the explicit library without opening or settling runs', async () => {
+    const { hub, harness, root } = fixture([entry()])
+    const output: string[] = []
+    const code = await runHubCli(['install', 'example/review@1.0.0', '--data', root, '--state', harness.stateDir], { write: (text) => output.push(text), createHarness: (options) => {
+      expect(options.dataRoot).toBe(root)
+      return { ...harness, hub, close: async () => undefined } as unknown as Harness
+    } })
+    expect(code).toBe(0)
+    expect(output.join('')).toContain('Saved example/review@1.0.0')
+    expect(existsSync(join(root, 'runs'))).toBe(false)
+  })
+  it('uses the last valid catalog when refresh fails or has duplicate versions', async () => {
+    let response = JSON.stringify({ schemaVersion: 1, entries: [entry()] })
+    const { hub } = fixture([], (async () => new Response(response)) as typeof fetch)
+    expect((await hub.list(true)).origin).toBe('remote')
+    response = JSON.stringify({ schemaVersion: 1, entries: [entry(), entry()] })
+    const cached = await hub.list(true)
+    expect(cached.origin).toBe('cached')
+    expect(cached.error).toBeTruthy()
+    expect(cached.entries).toHaveLength(1)
+    expect((await hub.list()).entries).toHaveLength(1)
+  })
+  it('rejects simultaneous writers and releases locks after a failed download', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    let resolve!: (response: Response) => void
+    const { hub } = fixture([item], (() => new Promise<Response>((done) => { resolve = done })) as typeof fetch)
+    const first = hub.install(item.id, item.version)
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('Another installation')
+    resolve(new Response('bad digest'))
+    await expect(first).rejects.toThrow('differs')
+    expect(hub.busy).toBe(false)
+  })
+  it('keeps an in-progress installation pinned to its data root', async () => {
+    const item = entry(); if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const root = mkdtempSync(join(tmpdir(), 'hub-root-pin-')); folders.push(root)
+    let resolve!: (response: Response) => void
+    const harness = new Harness({ dataRoot: join(root, 'data'), stateDir: join(root, 'state'), secrets: memorySecretStore(), hub: { catalog: { schemaVersion: 1, entries: [item] }, fetch: (() => new Promise<Response>((done) => { resolve = done })) as typeof fetch } })
+    try {
+      const pending = harness.hub.install(item.id, item.version)
+      expect(() => harness.open(join(root, 'other'))).toThrow('Wait for the hub installation')
+      expect(harness.dataRoot).toBe(join(root, 'data'))
+      resolve(new Response('{"message":"data only"}'))
+      await pending
+      expect((await harness.hub.list()).installed).toHaveLength(1)
+      expect(existsSync(join(root, 'other'))).toBe(false)
+    } finally { await harness.close() }
+  })
+  it('rejects unpinned packages and incompatible runtimes', async () => {
+    expect(() => hubEntrySchema.parse({ ...entry(), delivery: { kind: 'pi-package', source: 'npm:unknown@latest' } })).toThrow()
+    expect(() => hubCatalogSchema.parse({ schemaVersion: 2, entries: [] })).toThrow()
+    const item = { ...entry(), requires: { harness: '99.0.0' } }
+    const { hub } = fixture([item])
+    await expect(hub.install(item.id, item.version)).rejects.toThrow('requires Harness')
+  })
+  it('records only the requested package when another plugin appears during installation', async () => {
+    const source = 'npm:@example/review@1.0.0'
+    const item = hubEntrySchema.parse({ ...entry(), category: 'plugin', delivery: { kind: 'pi-package', source } })
+    const { hub } = fixture([item])
+    vi.spyOn(packageApi, 'list').mockResolvedValue([])
+    vi.spyOn(packageInstall, 'install').mockResolvedValue([
+      { id: 'package:review', install: { kind: 'settings', source } } as Plugin,
+      { id: 'package:another', install: { kind: 'settings', source: 'npm:@someone/other@1.0.0' } } as Plugin
+    ])
+    expect((await hub.install(item.id, item.version)).resourceIds).toEqual(['package:review'])
+    expect(packageInstall.install).toHaveBeenCalledWith(expect.anything(), { source })
+  })
+  it('does not treat cancelling the terminal review as an install', async () => {
+    const { hub } = fixture([entry()])
+    const calls: string[] = []
+    const choices = ['Review · preset · example/review@1.0.0', 'Done']
+    await runHubMenu({ select: async () => choices.shift(), confirm: async () => false, notify: () => undefined }, async <T>(method: string) => { calls.push(method); return await hub.list() as T })
+    expect(calls).toEqual(['hub.list', 'hub.list'])
+  })
+  it('refuses an already-held library lock', async () => {
+    const { hub, root } = fixture([entry()])
+    mkdirSync(join(root, 'hub'), { recursive: true })
+    writeFileSync(join(root, 'hub', 'install.lock'), String(process.pid))
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('Another installation')
+    expect(hub.busy).toBe(false)
+  })
+})

package/src/hub/hub.ts

@@ -0,0 +1,256 @@
+import { createHash } from 'node:crypto'
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { watch } from 'node:fs'
+
+import { HarnessError, invalid } from '../core/errors'
+import { atomicWrite, now, readJson, readJsonOr, writeJson } from '../core/fs'
+import type { Harness } from '../harness'
+import * as pluginApi from '../plugins/api'
+import * as packages from '../plugins/install'
+import * as registry from '../skills/registry'
+import * as attachments from '../plugins/attachments'
+import { version as harnessVersion } from '../../package.json'
+import bundled from './catalog.json'
+import { HUB_CATALOG_URL, HUB_MAX_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
+
+export interface HubOptions {
+  catalogUrl?: string
+  catalog?: HubCatalog
+  fetch?: typeof globalThis.fetch
+}
+
+const digest = (bytes: Uint8Array | string): string => createHash('sha256').update(bytes).digest('hex')
+const receiptName = (entry: Pick<HubEntry, 'id' | 'version'>): string => 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: string): () => void {
+  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 as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    // Serialize stale-lock recovery too: two reapers must never remove a new writer's lock.
+    let recovery: number
+    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 as NodeJS.ErrnoException).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 {
+  private readonly fallback: HubCatalog
+  private readonly fetcher: typeof globalThis.fetch
+  private readonly catalogUrl: string
+  private watcher: ReturnType<typeof watch> | null = null
+  private refresh: Promise<HubOverview> | null = null
+  private installing = false
+  get busy(): boolean { return this.installing }
+
+  constructor(private readonly harness: Harness, options: HubOptions = {}) {
+    this.fallback = hubCatalogSchema.parse(options.catalog ?? bundled)
+    this.fetcher = options.fetch ?? globalThis.fetch
+    this.catalogUrl = options.catalogUrl ?? HUB_CATALOG_URL
+  }
+
+  private receipts(): HubReceipt[] {
+    const root = this.harness.dataRoot
+    if (!root) return []
+    const values = readJson<unknown[]>(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))
+  }
+
+  private snapshot(): HubOverview {
+    const cached = readJsonOr<{ catalog: unknown; at: string } | null>(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().filter((receipt) => this.present(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 }
+  }
+
+  private present(receipt: HubReceipt): boolean {
+    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<{ packages?: Array<string | { source: string }> }>(join(this.harness.stateDir, 'accounts', '_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): Promise<HubOverview> {
+    if (!refresh) return this.snapshot()
+    this.refresh ??= this.refreshCatalog().finally(() => { this.refresh = null })
+    return this.refresh
+  }
+
+  private async bytes(url: string): Promise<Buffer> {
+    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: Uint8Array[] = []
+    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)
+  }
+
+  private async refreshCatalog(): Promise<HubOverview> {
+    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) }
+    }
+  }
+
+  private decode(bytes: Buffer): string {
+    const text = bytes.toString('utf8')
+    if (!Buffer.from(text).equals(bytes)) throw invalid('Hub JSON must use valid UTF-8.')
+    return text
+  }
+
+  private find(id: string, version: string): HubEntry {
+    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: string, version: string, preview = false): Promise<HubEntry> {
+    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 install(id: string, version: string): Promise<HubReceipt> {
+    const root = this.harness.env.root
+    const entry = hubEntrySchema.parse(this.find(id, version))
+    if (entry.requires.harness && !meetsMinimum(harnessVersion, 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: (() => void) | null = 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
+      const remaining = records.filter((record) => record !== existing)
+      const receipt: HubReceipt = { 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: string): string => 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 = delivery.bundled === undefined ? await this.bytes(delivery.url) : Buffer.from(delivery.bundled)
+        if (digest(bytes) !== delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+        const text = this.decode(bytes)
+        if (delivery.kind === 'document') {
+          JSON.parse(text)
+          receipt.document = `${receiptName(entry)}.json`
+          atomicWrite(join(root, 'hub', 'documents', receipt.document), 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.items.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.remove(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() }
+  }
+
+  readDocument(id: string, version: string): { entry: HubEntry; content: string } {
+    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: string): void {
+    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(): void { this.watcher?.close(); this.watcher = null }
+}