skillhub/cli/src/integrations/native-runtime.ts
XiaoSeS 2e82e8ab16 feat(dsh): manage skill activation and simplify installation flows
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-10-28 13:59:58 +08:00

168 lines
9.8 KiB
TypeScript

import { createHash } from 'node:crypto'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import { isDeepStrictEqual } from 'node:util'
import { inspectToggle, executeNativeToggle, recoverToggle } from './native-toggle'
import { readSkillExamples } from '../services/skill-examples'
import { observeInstallationDiscovery } from './install-discovery'
import { readInstalledProjection } from './installed-projection'
import { assessSkillUpdate } from './update-assessment'
import { inspectUpgradeBaseline } from './upgrade-baseline'
import { inspectRemovalBaseline } from './removal-baseline'
import { InventoryStore } from '../stores/inventory-store'
import { recoverInstallation } from './install-recovery'
import { OperationStore, OperationStoreError, operationRequestDigest } from './operation-store'
import { projectOperation } from './operation-projection'
import type { NativeRuntime } from './native-contract'
import { executeNativeInstall } from './native-install'
import { executeNativeUpgrade } from './native-upgrade'
import { executeNativeRemoval } from './native-removal'
import { recoverRemoval } from './removal-recovery'
import { acquireSkillTargetLock } from '../services/skill-target-lock'
/** Private native adapter. Paths must come from the Host, never a Remote request or tool argument. */
export async function openNativeRuntime(options: { stateDirectory: string; inventoryHome: string }): Promise<NativeRuntime> {
const operations = await OperationStore.open(options.stateDirectory)
const inventory = new InventoryStore(options.inventoryHome)
const ensureCompatible = async () => {
if ((await operations.listForRecovery()).some(record => record.schemaVersion < 3)) {
throw new OperationStoreError('TARGET_RECOVERY_REQUIRED')
}
await inventory.ensureWritable()
}
return {
hostInstanceId: operations.hostInstanceId,
readInstallationEntry: async (selected, target) => {
const baseline = await inspectUpgradeBaseline(inventory, { ...selected }, [{ ...target }])
if (baseline.status !== 'ready' || baseline.targets.length !== 1) return undefined
const entry = baseline.inventoryItem.targets[0]!
const content = await readFile(join(entry.installDir, entry.installationState === 'disabled' ? 'SKILL.md.disabled' : 'SKILL.md'))
if (createHash('sha256').update(content).digest('hex') !== baseline.targets[0]!.files['SKILL.md']
|| !isDeepStrictEqual(baseline, await inspectUpgradeBaseline(inventory, { ...selected }, [{ ...target }]))) return undefined
return content.toString('utf8')
},
inspectToggle: (selected, target, desiredState) => inspectToggle(inventory, { ...selected }, { ...target }, desiredState),
acceptToggle: async (request, validateNew) => {
const result = await operations.accept({ hostInstanceId: request.hostInstanceId, ownerId: request.ownerId,
requestKey: request.requestKey, mode: request.mode, requestDigest: operationRequestDigest({ ...request.parameters, kind: 'toggle' }) },
async () => {
const input = await validateNew()
if (!['enable', 'disable'].includes(input.kind)) throw new Error('Expected toggle acceptance')
return input
})
return result ? projectOperation(result) : undefined
},
executeToggle: async request => {
await ensureCompatible()
const snapshot = { ...request, baseline: structuredClone(request.baseline) }
return withOperationLease(operations, snapshot.operationId, snapshot.ownerId,
() => executeNativeToggle(operations, inventory, snapshot))
},
readSkillExamples,
observeInstallation: (operationId, ownerId, trustedRoots, observe) => observeInstallationDiscovery({
operations, inventory, operationId, ownerId, trustedRoots, observe
}),
findPlanOperation: async request => {
let conflict: OperationStoreError | undefined
// Preserve existing per-kind digests, including operations accepted by earlier plugin builds.
for (const kind of ['upgrade', 'removal', 'toggle'] as const) {
try {
const result = await operations.accept({ hostInstanceId: request.hostInstanceId, ownerId: request.ownerId,
requestKey: request.requestKey, mode: 'retry',
requestDigest: operationRequestDigest({ ...request.parameters, kind }) },
async () => { throw new Error('Plan lookup cannot accept new work') })
if (result) {
if (kind === 'upgrade' ? result.operation.kind !== 'upgrade'
: kind === 'toggle' ? !['enable', 'disable'].includes(result.operation.kind) : !['uninstall', 'remove-stale-record'].includes(result.operation.kind)) throw new Error('Plan operation kind mismatch')
return projectOperation(result)
}
} catch (error) {
if (!(error instanceof OperationStoreError) || error.code !== 'REQUEST_KEY_CONFLICT') throw error
conflict = error
}
}
if (conflict) throw conflict
return undefined
},
executeRemoval: async request => {
await ensureCompatible()
const snapshot = { ...request, baseline: structuredClone(request.baseline) }
return withOperationLease(operations, snapshot.operationId, snapshot.ownerId,
() => executeNativeRemoval(operations, inventory, snapshot))
},
acceptRemoval: async (request, validateNew) => {
const result = await operations.accept({ hostInstanceId: request.hostInstanceId, ownerId: request.ownerId,
requestKey: request.requestKey, mode: request.mode, requestDigest: operationRequestDigest({ ...request.parameters, kind: 'removal' }) },
async () => {
const input = await validateNew()
if (!['uninstall', 'remove-stale-record'].includes(input.kind)) throw new Error('Expected removal acceptance')
return input
})
return result ? projectOperation(result) : undefined
},
inspectRemoval: (selected, target) => inspectRemovalBaseline(inventory, { ...selected }, { ...target }),
executeUpgrade: async request => {
await ensureCompatible()
const snapshot = { ...request, baseline: structuredClone(request.baseline) }
return withOperationLease(operations, snapshot.operationId, snapshot.ownerId,
() => executeNativeUpgrade(operations, inventory, snapshot))
},
acceptUpgrade: async (request, validateNew) => {
const result = await operations.accept({ hostInstanceId: request.hostInstanceId, ownerId: request.ownerId,
requestKey: request.requestKey, mode: request.mode, requestDigest: operationRequestDigest({ ...request.parameters, kind: 'upgrade' }) },
async () => ({ ...await validateNew(), kind: 'upgrade' }))
return result ? projectOperation(result) : undefined
},
assessUpdate: assessSkillUpdate,
inspectUpgrade: (selected, targets) => inspectUpgradeBaseline(inventory, { ...selected }, targets.map(target => ({ ...target }))),
listInstalled: (registry, targets) => readInstalledProjection(inventory, registry, targets.map(target => ({ ...target }))),
executeInstall: async request => {
await ensureCompatible()
const snapshot = { ...request }
return withOperationLease(operations, snapshot.operationId, snapshot.ownerId,
() => executeNativeInstall(operations, inventory, snapshot))
},
acceptInstall: async (request, validateNew) => {
const result = await operations.accept({ hostInstanceId: request.hostInstanceId, ownerId: request.ownerId,
requestKey: request.requestKey, mode: request.mode, requestDigest: operationRequestDigest(request.parameters) },
async () => ({ ...await validateNew(), kind: 'install' }))
return result ? projectOperation(result) : undefined
},
getOperation: async (operationId, ownerId) => {
const result = await operations.get(operationId, ownerId)
return result ? projectOperation(result) : undefined
},
listPending: async () => (await operations.listForRecovery()).map(record => ({
operationId: record.operationId, ownerId: record.ownerId, kind: record.operation.kind,
namespace: record.operation.namespace, slug: record.operation.slug, targetPaths: [...record.operation.targetPaths ?? []]
})),
recover: async (operationId, ownerId, trustedTargetPaths, authorize) => {
if (typeof authorize !== 'function') throw new Error('Native recovery requires Host authorization')
const paths = [...trustedTargetPaths]
const result = await withOperationLease(operations, operationId, ownerId, async () => {
const record = await operations.get(operationId, ownerId)
const input = { operations, inventory, operationId, ownerId, trustedTargetPaths: paths, authorizeMutation: authorize }
if (record && ['enable', 'disable'].includes(record.operation.kind)) return recoverToggle(operations, inventory, operationId, ownerId, paths, authorize)
return record && ['uninstall', 'remove-stale-record'].includes(record.operation.kind)
? recoverRemoval(input) : recoverInstallation(input)
})
return { operationId: result.operationId, revision: result.revision, outcome: result.outcome, reason: result.reason }
}
}
}
/** Serialize a whole native execution/recovery, including staging before target locks are acquired. */
async function withOperationLease<T>(operations: OperationStore, operationId: string, ownerId: string, run: () => Promise<T>): Promise<T> {
// Validate the UUID and owner before using the operation identity as a lock key.
if (!await operations.get(operationId, ownerId)) throw new Error('Operation is not owned')
const release = await acquireSkillTargetLock(operations.root, `execution-${operationId}`)
let result: T
try { result = await run() }
catch (failure) {
try { await release() }
catch (error) { throw new AggregateError([failure, error], 'Native operation and lease release failed') }
throw failure
}
await release()
return result
}