Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -682,6 +682,22 @@ The CLI resolves all currently accessible, published, download-ready members onc

Each member uses normal Skill installation locks, fingerprint checks, ownership protection and inventory. This creates neither a Suite nor a repository installation ledger. Existing directories are never overwritten by this batch command; no batch `--force` is accepted. Successful members remain installed if another fails. The output lists every attempted member, counts installed/skipped/failed, and returns nonzero on partial failure or no usable plan. In `--json` mode stdout is one result object; a nonzero command additionally writes its standard error object to stderr. Excluded private/unpublished members are not counted as successful or as a disclosed skip count.

A complete historical snapshot ZIP is a separate download: every pinned snapshot member must be available. Batch installation does not promise that all members belong to one commit. Use individual upgrades for existing skills; repository-scoped update checks and upgrades are tracked separately in #1110.
A complete historical snapshot ZIP is a separate download: every pinned snapshot member must be available. Batch installation does not promise that all members belong to one commit. Use the repository-scoped check and upgrade commands below for existing installations.

If an inventory commit is indeterminate or rollback is incomplete, the batch stops further writes and reports a recovery state with retained target/staging/backup paths and a safe next step. It does not serialize arbitrary error details or credentials.

## Check and upgrade installed repository skills

```bash
skillhub repository check 123456 --registry https://skillhub.example.com --json
skillhub repository upgrade 123456 --agent codex --registry https://skillhub.example.com --check
skillhub repository upgrade 123456 --agent codex --registry https://skillhub.example.com
```

`check` and `upgrade --check` are read-only. `--agent` and/or `--dir` filter existing targets; `--scope` applies only to installation. New upstream members are not automatically installed. Local files for removed, hidden or unavailable members are not deleted. A per-Skill provenance hint lets the CLI explain that a previously installed member no longer appears in the accessible published plan without guessing why it is hidden. Older metadata without this hint stays readable and can match verified current members.

Checks compare exact versions and content fingerprints, not commit equality. Each invocation fetches the repository plan once and pins all selected releases. Existing source, ownership, local-change, disabled-state, lock and inventory protections remain in effect. No repository batch `--force` is offered. Protected targets remain unchanged while safe targets may upgrade; the overall result is nonzero if anything is protected or fails. A runtime failure preserves completed work and reports subsequent unattempted targets. The CLI does not claim a single transaction across every skill directory.

The Web page offers these commands but cannot inspect installed local files or display an installed drift count. These operations create no Suite, repository installation ledger, server installation telemetry or lockstep commit policy. Existing registry download quotas still apply.

GitHub sync release strings contain content hashes and ingestion IDs rather than sortable upstream SemVer. Repository checks use the validated same-source metadata version ID as the creation-order baseline. Exact matching versions/fingerprints are unchanged; older metadata lacking a reliable ordering ID is protected when a different release must be compared. No hash-lexical fallback or forced migration is used. Disabled targets requiring an update are protected during planning; enabled independent targets can proceed.
8 changes: 5 additions & 3 deletions cli/src/commands/help.ts
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,13 @@ export const commands = {
]
},
repository: {
summary: 'Install current published skills from a GitHub repository',
usage: 'skillhub repository install <repository-id> [--scope <user|project>] [--agent <profile>] [--dir <path>] [--registry <url>] [--token <token>] [--json]',
summary: 'Install, check or upgrade skills from a GitHub repository',
usage: 'skillhub repository <install|check|upgrade> <repository-id> [--scope <user|project> (install only)] [--agent <profile>] [--dir <path>] [--registry <url>] [--token <token>] [--check (upgrade only)] [--json]',
examples: [
'skillhub repository install 123456 --scope project --agent codex',
'skillhub repository install 123456 --dir ./skills --json'
'skillhub repository install 123456 --dir ./skills --json',
'skillhub repository check 123456 --json',
'skillhub repository upgrade 123456 --agent codex --check'
]
},
suite: {
Expand Down
24 changes: 21 additions & 3 deletions cli/src/commands/repository.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,39 @@ import { EXIT } from '../shared/constants'
import { CliError } from '../shared/errors'
import { computeStrictIsTTY } from '../shared/tty'
import { resolveEffectiveScope, defaultPromptScope, type InstallCommandOptions } from './install'
import { planRepositoryUpgrades, executeRepositoryUpgrades } from '../services/repository-upgrade-service'
import { renderUpgradePlan, renderUpgradeResult } from './upgrade'

export type RepositoryCommandOptions = Omit<InstallCommandOptions, 'force' | 'version' | 'namespace'>
export type RepositoryCommandOptions = Omit<InstallCommandOptions, 'force' | 'version' | 'namespace'> & { check?: boolean }

export async function repositoryCommand(action: string, repositoryId: string, options: RepositoryCommandOptions): Promise<string> {
if (action !== 'install') throw new CliError('repository action must be "install"', EXIT.usage)
if (!['install', 'check', 'upgrade'].includes(action)) throw new CliError('repository action must be "install", "check" or "upgrade"', EXIT.usage)
repositoryId = String(repositoryId)
if (!/^[1-9]\d*$/.test(repositoryId) || BigInt(repositoryId) > 9223372036854775807n) {
throw new CliError('repository ID must be a positive integer from the repository page', EXIT.usage)
}
if (action !== 'install' && options.scope !== undefined) throw new CliError('use --agent or --dir to filter installed targets; --scope is for installation', EXIT.usage)
if (action === 'install' && options.check) throw new CliError('use repository check to inspect installed skills', EXIT.usage)
const isTTY = computeStrictIsTTY({ stdinIsTTY: process.stdin.isTTY === true,
stdoutIsTTY: process.stdout.isTTY === true, json: Boolean(options.json) })
const scope = await resolveEffectiveScope(options, { isTTY, promptScope: defaultPromptScope })
const scope = action === 'install' ? await resolveEffectiveScope(options, { isTTY, promptScope: defaultPromptScope }) : undefined
const registry = resolveRegistry(options, process.env, await new ConfigStore().read())
const token = resolveToken(options, process.env, await new CredentialsStore().getToken(registry))
const plan = await new SkillHubClient(registry, token).repositoryInstallPlan(repositoryId)
if (action !== 'install') {
const tokenForRegistry = async () => token
const upgrades = await planRepositoryUpgrades(plan, { registry, agents: options.agent, dir: options.dir, tokenForRegistry })
const check = action === 'check' || Boolean(options.check)
const result = check ? undefined : await executeRepositoryUpgrades(upgrades, { tokenForRegistry })
const output = check ? renderUpgradePlan(upgrades, { check: true, executed: false }, Boolean(options.json))
: renderUpgradeResult(upgrades, result!, Boolean(options.json), upgrades.blocked)
if (upgrades.blocked > 0 || result && result.failed > 0) {
process.stdout.write(`${output}\n`)
throw new CliError('repository update contains protected or failed skills; inspect per-target results',
result?.items.find(item => item.action === 'failed')?.exitCode ?? EXIT.validation)
}
return output
}
const targets = await resolveInstallTargets({ cwd: process.cwd(), scope, dir: options.dir,
agents: options.agent ?? [], json: Boolean(options.json), interactive: isTTY })
const result = await installRepositoryPlan(plan, { registry, token, targets })
Expand Down
9 changes: 5 additions & 4 deletions cli/src/commands/upgrade.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ export async function upgradeCommand(coordinates: string[], options: UpgradeComm
return output
}

function renderUpgradePlan(
export function renderUpgradePlan(
plan: UpgradePlan,
state: { check: boolean; executed: boolean },
json: boolean
Expand Down Expand Up @@ -96,7 +96,7 @@ function renderUpgradePlan(
].join('\n')
}

export function renderUpgradeResult(plan: UpgradePlan, result: UpgradeExecutionResult, json: boolean): string {
export function renderUpgradeResult(plan: UpgradePlan, result: UpgradeExecutionResult, json: boolean, blocked = 0): string {
// Execution returns one row per plan position, in order. Coordinates can repeat at different versions.
const items = plan.items.map((item, index) => ({
coordinate: item.coordinate,
Expand All @@ -112,13 +112,14 @@ export function renderUpgradeResult(plan: UpgradePlan, result: UpgradeExecutionR

if (json) {
return JSON.stringify({
ok: result.failed === 0,
ok: result.failed === 0 && blocked === 0,
check: false,
summary: {
upgraded: result.upgraded,
unchanged: result.unchanged,
failed: result.failed,
notAttempted: result.notAttempted
notAttempted: result.notAttempted,
...(blocked ? { blocked } : {})
},
items
})
Expand Down
3 changes: 2 additions & 1 deletion cli/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -292,12 +292,13 @@ cli
})

cli
.command('repository <action> <repository-id>', 'Install published skills from a GitHub repository')
.command('repository <action> <repository-id>', 'Install, check or upgrade skills from a GitHub repository')
.option('--scope <scope>', 'Install scope: user or project')
.option('--agent <profile>', 'Agent profile (repeatable)')
.option('--dir <path>', 'Install directory')
.option('--registry <url>', 'Registry URL')
.option('--token <token>', 'API token')
.option('--check', 'Show the repository upgrade plan without writing')
.option('--json', 'Output JSON')
.action((action: string, repositoryId: string, options: RepositoryCommandOptions & { agent?: string | string[] }) =>
runCommand(() => repositoryCommand(action, repositoryId, { ...options, agent: toArray(options.agent) }), Boolean(options.json)))
Expand Down
69 changes: 69 additions & 0 deletions cli/src/services/repository-upgrade-service.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
import type { RepositoryInstallPlan } from '../clients/skillhub-client'
import { InventoryStore } from '../stores/inventory-store'
import { EXIT } from '../shared/constants'
import { CliError } from '../shared/errors'
import { readInstalledSkillMetadata, sameInstalledSkillSource } from './installed-skill-metadata'
import { MAX_UPGRADE_SELECTION, matchesTargetFilters, planSkillUpgrades, executeSkillUpgradePlan,
type UpgradeSelectionOptions, type UpgradePlan, type UpgradeExecutionResult } from './upgrade-service'

type RepositoryUpgradeOptions = Omit<UpgradeSelectionOptions, 'coordinates' | 'namespace' | 'force' | 'resolveVersion' | 'compareVersions'> & { registry: string }

export async function planRepositoryUpgrades(remote: RepositoryInstallPlan, options: RepositoryUpgradeOptions): Promise<UpgradePlan> {
const inventory = await new InventoryStore(options.home).read()
const members = new Map(remote.members.map(member => [member.slug, member]))
const items: UpgradePlan['items'] = []
const coordinates: string[] = []
for (const item of inventory.items) {
if (item.namespace !== 'github' || item.registry.replace(/\/+$/, '') !== options.registry.replace(/\/+$/, '')) continue
const targets = item.targets.filter(target => matchesTargetFilters(target, options.agents, options.dir))
if (!targets.length) continue
if (members.has(item.slug)) {
coordinates.push(`@github/${item.slug}`)
continue
}
// Local provenance is only a discovery hint for unavailable members, never upgrade authority.
for (const target of targets) {
const metadata = await readInstalledSkillMetadata(target.installDir)
if (metadata.status !== 'valid' || !sameInstalledSkillSource(metadata.metadata, item)
|| metadata.metadata.sourceRepositoryId !== remote.repositoryId) continue
items.push({ coordinate: `@github/${item.slug}`, registry: item.registry, currentVersion: target.version,
action: 'blocked', reason: 'no longer in the accessible published repository plan; local files are preserved',
changedFiles: [], targets: [{ agent: target.agent, dir: target.installDir }],
inventoryItem: { ...item, targets: [target] }, selectedTargets: [target], expectedTargetFiles: {}, allowTargetDrift: false })
}
}
if (!coordinates.length && !items.length) throw new CliError('no installed skills match this repository and target selection; no files changed', EXIT.usage)
for (let offset = 0; offset < coordinates.length; offset += MAX_UPGRADE_SELECTION) {
const plan = await planSkillUpgrades({ ...options, coordinates: coordinates.slice(offset, offset + MAX_UPGRADE_SELECTION),
force: false, resolveVersion: async item => {
const member = members.get(item.slug)
if (!member) throw new CliError('repository member is not in the pinned plan', EXIT.validation)
return member
}, compareVersions: async (item, resolved) => {
const current = await readInstalledSkillMetadata(item.targets[0]!.installDir)
if (current.status !== 'valid' || !sameInstalledSkillSource(current.metadata, item)
|| current.metadata.version !== item.targets[0]!.version
|| current.metadata.fingerprint !== item.targets[0]!.fingerprint) return 'unknown'
if (current.metadata.version === resolved.version && current.metadata.fingerprint === resolved.fingerprint) return 'same'
// GitHub versions embed a content hash, not a sortable SemVer publication sequence.
// Within one verified source Skill, version IDs preserve creation order (including reverts).
const versionId = current.metadata.versionId
if (!Number.isSafeInteger(versionId) || !versionId || versionId <= 0) return 'unknown'
return resolved.versionId === versionId ? 'same' : resolved.versionId > versionId ? 'remote-newer' : 'remote-older'
} })
items.push(...plan.items.map(item => item.action === 'upgrade' && item.selectedTargets.some(target => target.installationState === 'disabled')
? { ...item, action: 'blocked' as const, reason: 'disabled installation is protected; use the native transactional manager' } : item))
}
return { items, blocked: items.filter(item => item.action === 'blocked').length,
upgrades: items.filter(item => item.action === 'upgrade').length, unchanged: items.filter(item => item.action === 'unchanged').length }
}

export async function executeRepositoryUpgrades(plan: UpgradePlan, options: Pick<RepositoryUpgradeOptions, 'home' | 'tokenForRegistry'>): Promise<UpgradeExecutionResult> {
const safeItems = plan.items.filter(item => item.action !== 'blocked')
const executed = await executeSkillUpgradePlan({ ...plan, items: safeItems, blocked: 0 }, options)
let position = 0
return { ...executed, notAttempted: executed.notAttempted + plan.blocked,
items: plan.items.map(item => item.action === 'blocked'
? { coordinate: item.coordinate, action: 'not-attempted' as const, reason: item.reason ?? 'protected local installation' }
: executed.items[position++]!) }
}
30 changes: 23 additions & 7 deletions cli/src/services/upgrade-service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ import { diffSkillFiles, snapshotSkillDirectory } from './skill-fingerprint'
import { snapshotInstalledSkillDirectory } from './installed-skill-snapshot'
import { installSkill } from './install-service'
import { readInstalledSkillMetadata, sameInstalledSkillSource } from './installed-skill-metadata'
import { compareSkillVersions } from './skill-version-order'
import { compareSkillVersions, type SkillVersionOrder } from './skill-version-order'

const MAX_UPGRADE_SELECTION = 50
export const MAX_UPGRADE_SELECTION = 50

export interface UpgradeSelectionOptions {
coordinates: string[]
Expand All @@ -23,6 +23,10 @@ export interface UpgradeSelectionOptions {
force: boolean
home?: string
tokenForRegistry: (registry: string) => Promise<string | undefined>
/** Internal source adapter; a repository invocation supplies its already pinned releases. */
resolveVersion?: (item: InventoryItem) => Promise<ResolveResponse>
/** Source-specific ordering; ordinary upgrades retain the SemVer comparator. */
compareVersions?: (item: InventoryItem, resolved: ResolveResponse) => Promise<SkillVersionOrder>
}

export type UpgradePlanAction = 'upgrade' | 'unchanged' | 'blocked'
Expand Down Expand Up @@ -102,8 +106,8 @@ export async function planSkillUpgrades(options: UpgradeSelectionOptions): Promi
try {
await assertDirectTargetOwnership(inventory, selection.targets.map(target => target.installDir))
const token = await options.tokenForRegistry(selection.item.registry)
resolved = await new SkillHubClient(selection.item.registry, token)
.resolve(selection.item.namespace, selection.item.slug)
resolved = options.resolveVersion ? await options.resolveVersion(selection.item)
: await new SkillHubClient(selection.item.registry, token).resolve(selection.item.namespace, selection.item.slug)
} catch (error) {
items.push({
...base,
Expand All @@ -123,7 +127,18 @@ export async function planSkillUpgrades(options: UpgradeSelectionOptions): Promi
continue
}

const inspection = await inspectTargets(selection.item, selection.targets)
let inspection: Awaited<ReturnType<typeof inspectTargets>>
try {
inspection = await inspectTargets(selection.item, selection.targets)
} catch {
items.push({
...base,
remoteVersion: resolved.version,
action: 'blocked',
reason: 'installed target could not be safely verified; local files were kept'
})
continue
}
const hardConflict = inspection.hardConflicts[0]
if (hardConflict) {
items.push({
Expand Down Expand Up @@ -161,7 +176,8 @@ export async function planSkillUpgrades(options: UpgradeSelectionOptions): Promi
continue
}

const versionOrder = compareSkillVersions(selection.targets[0]!.version, resolved.version)
const versionOrder = options.compareVersions ? await options.compareVersions(selection.item, resolved)
: compareSkillVersions(selection.targets[0]!.version, resolved.version)
if (versionOrder === 'remote-older') {
items.push({
...base,
Expand Down Expand Up @@ -388,7 +404,7 @@ async function inspectTargets(item: InventoryItem, targets: InventoryTarget[]):
}
}

function matchesTargetFilters(target: InventoryTarget, agents?: string[], dir?: string): boolean {
export function matchesTargetFilters(target: InventoryTarget, agents?: string[], dir?: string): boolean {
if (agents?.length && !agents.includes(target.agent)) return false
if (!dir) return true
const filterPath = resolve(dir)
Expand Down
Loading
Loading