@xingular/harness 0.1.7 → 1.0.0

package/src/hub/hub.test.ts

@@ -1,205 +0,0 @@
-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

@@ -1,256 +0,0 @@
-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 }
-}

package/src/hub/schema.ts

@@ -1,81 +0,0 @@
-import { z } from 'zod'
-
-export const HUB_CATALOG_URL = 'https://raw.githubusercontent.com/tanntnny/xingular-hub/main/catalog.json'
-export const HUB_MAX_BYTES = 16 * 1024 * 1024
-
-const httpsUrl = z.string().max(2000).url().refine((value) => {
-  const url = new URL(value)
-  return url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash && !url.port
-}, 'Use a public HTTPS URL without credentials, queries, or fragments.')
-const payload = {
-  url: httpsUrl,
-  sha256: z.string().regex(/^[a-f0-9]{64}$/),
-  bundled: z.string().max(HUB_MAX_BYTES).optional()
-}
-
-export const hubDeliverySchema = z.discriminatedUnion('kind', [
-  z.object({ kind: z.literal('registry'), registryKind: z.enum(['skills', 'prompts', 'rules']), ...payload }).strict(),
-  z.object({ kind: z.literal('document'), ...payload }).strict(),
-  z.object({ kind: z.literal('pi-package'), source: z.string().max(2000).refine((source) =>
-    /^npm:(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+@\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(source)
-    || /^git:https:\/\/github\.com\/[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(?:\.git)?@[a-f0-9]{40}$/.test(source),
-  'Packages must use an exact npm version or a GitHub commit.') }).strict()
-])
-
-export const hubEntrySchema = z.object({
-  id: z.string().regex(/^[a-z0-9-]{1,64}\/[a-z0-9-]{1,64}$/),
-  title: z.string().min(1).max(100),
-  description: z.string().min(1).max(500),
-  publisher: z.string().min(1).max(100),
-  license: z.string().min(1).max(100),
-  version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/),
-  category: z.string().regex(/^[a-z][a-z-]{0,40}$/),
-  channel: z.enum(['official', 'community']),
-  tags: z.array(z.string().max(60)).max(20),
-  requires: z.record(z.string(), z.string().regex(/^\d+\.\d+\.\d+$/)),
-  sourceUrl: httpsUrl,
-  delivery: hubDeliverySchema
-}).strict()
-
-export const hubCatalogSchema = z.object({
-  schemaVersion: z.literal(1),
-  entries: z.array(hubEntrySchema).max(2000)
-}).strict().superRefine((catalog, ctx) => {
-  const keys = new Set<string>()
-  catalog.entries.forEach((entry, index) => {
-    const key = `${entry.id}@${entry.version}`
-    if (keys.has(key)) ctx.addIssue({ code: 'custom', path: ['entries', index, 'id'], message: 'Duplicate catalog item version.' })
-    keys.add(key)
-  })
-})
-
-export const hubReceiptSchema = z.object({
-  entry: hubEntrySchema,
-  installedAt: z.string(),
-  resourceIds: z.array(z.string()),
-  document: z.string().nullable()
-}).strict()
-
-export const hubOverviewSchema = z.object({
-  entries: z.array(hubEntrySchema),
-  installed: z.array(hubReceiptSchema),
-  origin: z.enum(['bundled', 'cached', 'remote']),
-  refreshedAt: z.string().nullable(),
-  error: z.string().nullable(),
-  dataRoot: z.string().nullable(),
-  stateDir: z.string()
-})
-
-export type HubEntry = z.infer<typeof hubEntrySchema>
-export type HubCatalog = z.infer<typeof hubCatalogSchema>
-export type HubReceipt = z.infer<typeof hubReceiptSchema>
-export type HubOverview = z.infer<typeof hubOverviewSchema>
-
-export function meetsMinimum(actual: string, minimum: string): boolean {
-  const left = actual.split(/[.-]/).slice(0, 3).map(Number)
-  const right = minimum.split('.').map(Number)
-  for (let index = 0; index < 3; index += 1) {
-    if (left[index] !== right[index]) return left[index] > right[index]
-  }
-  return true
-}

package/src/index.ts

@@ -1,75 +0,0 @@
-// @xingular/harness: a Pi agent harness. Multi-account Pi sessions, a compiled system prompt
-// with stable-prefix delivery, a memory lifecycle (Wiki, blocks, facts, recall, sleep-time
-// consolidation), tools with a gate and standing approvals, connected apps over MCP, and
-// skills (a person's own and built-in).
-//
-// An application embeds it with `createHarness` and extends it through prompt sections, tool
-// providers, a tool policy, a secret store, a directory of its own names, and a description of
-// its own parts as plugins. Everything else is reachable by path, e.g. `@xingular/harness/memory/wiki`.
-export { createHarness, Harness, type HarnessOptions, type Recovery } from './harness'
-export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './hub/schema'
-
-export { Bus, log, type Notice } from './core/bus'
-export { EMPTY_DIRECTORY, type Directory, type HarnessEnv } from './core/env'
-export { HarnessError, invalid, notFound, toErrorShape, type ErrorShape } from './core/errors'
-export { findBinary, searchPath } from './core/path'
-
-export { fileSecretStore, memorySecretStore, secretKey, type SecretStore } from './accounts/secrets'
-export type { Account, AccountsOverview, Pool } from './accounts/store'
-export type { AccountLoginSnapshot, ModelOption } from './accounts/accounts'
-export type { Capability, CapabilityCatalogue, CapabilityKind, CapabilityScope, CapabilitySet } from './capabilities/types'
-export type { RunCapabilitySnapshot } from './capabilities/runSnapshot'
-
-export type { CallerContext } from './memory/caller'
-export { dispatch as memoryCall } from './memory/dispatch'
-
-export {
-  compile,
-  render,
-  SECTION_ORDER,
-  CONTEXT_MESSAGE_TYPE,
-  CONTEXT_SNAPSHOT_KEY,
-  type ContextPack,
-  type ContextProfile,
-  type HostSection,
-  type HostToolGroup,
-  type Launch,
-  type Reference,
-  type Section
-} from './prompt/compile'
-
-export { runEventSchema, runRecordSchema, isActiveStatus, type RunEvent, type RunEventType, type RunRecord } from './sessions/contracts'
-export type { ApprovalFacts, ApprovalPolicy, AutomaticReason } from './sessions/approvals'
-export type { ScopeDecision, ToolCall, ToolPolicy } from './sessions/policy'
-export type { ActiveRun, ApprovalDecision, ApprovalInput, QuestionAnswer, QuestionInput } from './sessions/registry'
-export type { RunFields, SessionRunInput } from './sessions/sessions'
-export type { Effort } from './sessions/runner'
-
-export { describeTool, WIKI_TOOLS, WIKI_TOOL_NAMES, type WikiCall, type WikiToolDefinition } from './tools/definitions'
-export type { ToolProvider, ToolResult, ToolSession, ToolSpec } from './tools/types'
-export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, type SubagentOptions } from './tools/spawnSubagent'
-export { maintenanceTools, MAINTENANCE_PLUGIN, MAINTENANCE_TOOL_NAMES } from './tools/maintenance'
-export type { CurationJob } from './memory/curation'
-export { webTools, WEB_PLUGIN, WEB_SEARCH_KEY, type WebToolOptions } from './web/tools'
-export { registryTools, REGISTRY_WRITE, PLUGIN_WRITE, REGISTRY_WRITE_PLUGIN, type RegistryToolOptions } from './tools/registryWrite'
-export { safeRequest, type WebRequest, type WebResponse } from './web/safeRequest'
-
-export type { BrokeredTools, BrokerSession, BrokerTool } from './mcp/service'
-export type { Connection, ConnectionInput } from './mcp/types'
-
-export { configureBuiltins, type RegistryItem, type RegistryState, type SkillBundleInput } from './skills/registry'
-
-export type { TerminalAssets, TerminalLaunch, TerminalPrepareInput } from './terminal/terminals'
-
-export { attach as attachPlugin, inventoryFor as pluginInventory, list as listPlugins, type AttachParams, type InventoryParams, type PluginScope } from './plugins/api'
-export type { Attachment, AttachScope } from './plugins/attachments'
-export { HARNESS_PLUGINS } from './plugins/builtin'
-export { FIRST_PARTY_PLUGINS } from './plugins/firstParty'
-export type { Found, Resolver } from './plugins/discover'
-export type { Loading, Registered } from './plugins/plugins'
-export { CONTRIBUTION_KINDS, PLUGIN_SOURCES, type ConnectorTemplate, type Contribution, type ContributionKind, type ContributionState, type Delivery, type Inventory, type InventoryItem, type Plugin, type PluginDescriptor, type PluginManage, type PluginSetting, type PluginSource } from './plugins/types'
-
-export { methods } from './server/methods'
-export { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './server/remote'
-export { PROTOCOL_VERSION, RpcPeer, stdioTransport, type Handler, type Transport } from './server/rpc'
-export { attach, serve, type Served } from './server/serve'