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
1 change: 1 addition & 0 deletions Sources/CLI/cmd/agent/skills/AgentSkillsCommand.swift
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ struct AgentSkillsCommand: ParsableCommand, GlobalOptionsProviding {
AgentSkillsListCommand.self,
AgentSkillsGetCommand.self,
AgentSkillsInstallCommand.self,
AgentSkillsUpdateCommand.self,
AgentSkillsUninstallCommand.self,
]
)
Expand Down
3 changes: 2 additions & 1 deletion Sources/CLI/cmd/agent/skills/AgentSkillsInstallCommand.swift
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,8 @@ struct AgentSkillsInstallCommand: ParsableCommand, GlobalOptionsProviding {
func run(deps: Deps) throws {
do {
let outcomes = try deps.agentSkillInstallationService().install(
selection.selectedSkills(), root: selection.installationRoot(fileManager: deps.agentSkillFileManager()),
selection.selectedSkills(),
root: selection.root.installationRoot(fileManager: deps.agentSkillFileManager()),
dryRun: selection.dryRun, force: force
)
deps.commandOutputWriter.write(AgentSkillInstallationRenderer().render(outcomes))
Expand Down
19 changes: 13 additions & 6 deletions Sources/CLI/cmd/agent/skills/AgentSkillsListCommand.swift
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,33 @@ import ArgumentParser

struct AgentSkillsListCommand: ParsableCommand, GlobalOptionsProviding {
#if DEBUG
typealias Deps = any (TelemetryProvider & CommandOutputWriterProvider)
typealias Deps = any (TelemetryProvider & CommandOutputWriterProvider & AgentSkillInstallationServiceProvider)
#else
typealias Deps = Dependencies
#endif

@OptionGroup var global: GlobalOptions
@OptionGroup var root: AgentSkillsRootOptions

static let configuration = CommandConfiguration(
commandName: "list",
abstract: "List Agent Skills bundled with apple-docs."
abstract: "List bundled Agent Skills with installation status and paths."
)

mutating func run() throws {
run(deps: AppleDocs.dependencies)
try run(deps: AppleDocs.dependencies)
}

func run(deps: Deps) {
func run(deps: Deps) throws {
deps.telemetry.startCommand(.agentSkillsList)
for skill in BundledAgentSkills.all {
deps.commandOutputWriter.write("\(skill.name)\t\(skill.shortDescription)")
do {
let installations = try deps.agentSkillInstallationService().list(
BundledAgentSkills.all, root: root.installationRoot(fileManager: deps.agentSkillFileManager()))
for line in AgentSkillInstallationRenderer().renderList(installations) {
deps.commandOutputWriter.write(line)
}
} catch let error as AgentSkillInstallationError {
throw ValidationError(error.localizedDescription)
}
}
}
30 changes: 19 additions & 11 deletions Sources/CLI/cmd/agent/skills/AgentSkillsSelectionOptions.swift
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,14 @@ struct AgentSkillsSelectionOptions: ParsableArguments {
@Flag(help: "Select all bundled skills. Cannot be combined with skill names.")
var all = false

@Option(help: "Root of the .agents installation. Skills are stored under DIR/skills.")
var dir: String?

@Flag(
help: "Use the Git root's .agents directory (current directory outside Git). Conflicts with --dir."
)
var project = false
@OptionGroup var root: AgentSkillsRootOptions

@Flag(help: "Preview changes without writing or removing files.")
var dryRun = false

func selectedSkills() throws -> [BundledAgentSkill] {
if project, dir != nil {
throw ValidationError("Use either --project or --dir, not both.")
}
func selectedSkills(defaultToAll: Bool = false) throws -> [BundledAgentSkill] {
try root.validate()
if defaultToAll, !all, skills.isEmpty { return BundledAgentSkills.all }
guard all != !skills.isEmpty else {
throw ValidationError("Specify one or more skill names, or --all, but not both.")
}
Expand All @@ -36,6 +29,21 @@ struct AgentSkillsSelectionOptions: ParsableArguments {
}
}

}

struct AgentSkillsRootOptions: ParsableArguments {
@Option(help: "Root of the .agents installation. Skills are stored under DIR/skills.")
var dir: String?

@Flag(help: "Use the Git root's .agents directory (current directory outside Git). Conflicts with --dir.")
var project = false

func validate() throws {
if project, dir != nil {
throw ValidationError("Use either --project or --dir, not both.")
}
}

func installationRoot(fileManager: AgentSkillFileSystem) -> String {
if project {
let currentDirectory = URL(fileURLWithPath: fileManager.currentDirectoryPath).standardizedFileURL
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@ struct AgentSkillsUninstallCommand: ParsableCommand, GlobalOptionsProviding {
func run(deps: Deps) throws {
do {
let outcomes = try deps.agentSkillInstallationService().uninstall(
selection.selectedSkills(), root: selection.installationRoot(fileManager: deps.agentSkillFileManager()),
selection.selectedSkills(),
root: selection.root.installationRoot(fileManager: deps.agentSkillFileManager()),
dryRun: selection.dryRun
)
deps.commandOutputWriter.write(AgentSkillInstallationRenderer().render(outcomes))
Expand Down
55 changes: 55 additions & 0 deletions Sources/CLI/cmd/agent/skills/AgentSkillsUpdateCommand.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import ArgumentParser

struct AgentSkillsUpdateCommand: ParsableCommand, GlobalOptionsProviding {
#if DEBUG
typealias Deps = any (AgentSkillInstallationServiceProvider & CommandOutputWriterProvider)
#else
typealias Deps = Dependencies
#endif

@OptionGroup var global: GlobalOptions

static let configuration = CommandConfiguration(
commandName: "update",
abstract: "Update installed skills managed by apple-docs.",
discussion: """
With no names, updates all managed bundled skills already installed. Does not install missing
or unmanaged skills. Local edits are preserved and must be resolved before updating.
Use --project for the Git root (current directory outside Git), or --dir for another root.

Examples:
apple-docs agent skills update
apple-docs agent skills update --dry-run
apple-docs agent skills update apple-docs --project
"""
)

@OptionGroup var selection: AgentSkillsSelectionOptions

mutating func validate() throws {
_ = try selection.selectedSkills(defaultToAll: true)
}

mutating func run() throws {
try run(deps: AppleDocs.dependencies)
}

func run(deps: Deps) throws {
do {
let outcomes = try deps.agentSkillInstallationService().update(
selection.selectedSkills(defaultToAll: true),
root: selection.root.installationRoot(fileManager: deps.agentSkillFileManager()),
dryRun: selection.dryRun
)
deps.commandOutputWriter.write(AgentSkillInstallationRenderer().render(outcomes))
} catch let failure as AgentSkillBatchFailure {
deps.commandOutputWriter.write(AgentSkillInstallationRenderer().render(failure.completed))
if let error = failure.underlying as? AgentSkillInstallationError {
throw ValidationError(error.localizedDescription)
}
throw failure.underlying
} catch let error as AgentSkillInstallationError {
throw ValidationError(error.localizedDescription)
}
}
}
2 changes: 1 addition & 1 deletion Sources/CLI/main/AgentSkillErrorPresentation.swift
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ extension AgentSkillInstallationError: LocalizedError {
case .modifiedSkill(let name, let removing):
return removing
? "Skill '\(name)' was edited. Back up and restore it before uninstalling."
: "Skill '\(name)' differs. Use --force to replace the managed file."
: "Skill '\(name)' differs. To replace it, use 'apple-docs agent skills install \(name) --force'."
case .invalidReceipt(let url): return "Invalid apple-docs installation receipt at '\(url.path)'."
case .invalidDirectory(let url):
return "Expected a directory, not a symlink or other file, at '\(url.path)'."
Expand Down
31 changes: 27 additions & 4 deletions Sources/CLI/renderer/AgentSkillInstallationRenderer.swift
Original file line number Diff line number Diff line change
@@ -1,19 +1,42 @@
struct AgentSkillInstallationRenderer {
func render(_ outcomes: [AgentSkillInstallationOutcome]) -> String {
outcomes.map { outcome in
guard !outcomes.isEmpty else { return "No skills to process." }
let lines = outcomes.map { outcome in
let action: String
switch outcome.status {
case .installed, .updated:
case .installed:
action = "Installed: \(outcome.name) at \(outcome.file.path)"
case .wouldInstall, .wouldUpdate:
case .updated:
action = "Updated: \(outcome.name) at \(outcome.file.path)"
case .wouldInstall:
action = "Would install: \(outcome.name) at \(outcome.file.path)"
case .wouldUpdate:
action = "Would update: \(outcome.name) at \(outcome.file.path)"
case .unchanged: action = "Unchanged: \(outcome.name)"
case .uninstalled: action = "Uninstalled: \(outcome.name)"
case .wouldUninstall: action = "Would uninstall: \(outcome.name)"
case .notInstalled: action = "Not installed: \(outcome.name)"
}
let recovery = outcome.requiresRecovery ? "Would recover pending operation: \(outcome.name)\n" : ""
return recovery + action
}.joined(separator: "\n")
}
let labels: [(AgentSkillInstallationOutcome.Status, String)] = [
(.installed, "installed"), (.updated, "updated"), (.unchanged, "unchanged"),
(.uninstalled, "uninstalled"), (.notInstalled, "not installed"),
(.wouldInstall, "would install"), (.wouldUpdate, "would update"), (.wouldUninstall, "would uninstall"),
]
let counts = labels.compactMap { status, label -> String? in
let count = outcomes.filter { $0.status == status }.count
return count == 0 ? nil : "\(count) \(label)"
}
return (lines + ["Summary: " + counts.joined(separator: ", ")]).joined(separator: "\n")
}

func renderList(_ installations: [AgentSkillInstallationStatus]) -> [String] {
installations.map { installation in
let recovery = installation.requiresRecovery ? " (pending recovery)" : ""
return "\(installation.skill.name)\t\(installation.status.rawValue)\(recovery)\t\(installation.file.path)"
+ "\t\(installation.skill.shortDescription)"
}
}
}
16 changes: 16 additions & 0 deletions Sources/CLI/skills/AgentSkillInstallationOutcome.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,22 @@ struct AgentSkillInstallationOutcome: Equatable, Sendable {
var requiresRecovery = false
}

struct AgentSkillInstallationStatus {
enum Status: String {
case installed
case updateAvailable = "update available"
case modified
case unmanaged
case notInstalled = "not installed"
case missing
}

let skill: BundledAgentSkill
let file: URL
let status: Status
let requiresRecovery: Bool
}

enum AgentSkillInstallationError: Error, Equatable {
case emptyRoot
case unmanagedSkill(name: String, removing: Bool)
Expand Down
42 changes: 41 additions & 1 deletion Sources/CLI/skills/AgentSkillInstallationService.swift
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,40 @@ struct DefaultAgentSkillInstallationService {
}
}

func list(_ skills: [BundledAgentSkill], root: String) throws -> [AgentSkillInstallationStatus] {
try inspect(skills, root: root).map { installation in
let status: AgentSkillInstallationStatus.Status
if let content = installation.content {
if let receipt = installation.receipt {
if content != receipt.content {
status = .modified
} else {
status = content == Data(installation.skill.content.utf8) ? .installed : .updateAvailable
}
} else {
status = .unmanaged
}
} else {
status = installation.receipt == nil ? .notInstalled : .missing
}
return AgentSkillInstallationStatus(
skill: installation.skill, file: installation.file, status: status,
requiresRecovery: installation.inspection.pending != nil)
}
}

func update(
_ skills: [BundledAgentSkill], root: String, dryRun: Bool
) throws -> [AgentSkillInstallationOutcome] {
let installations = try inspect(skills, root: root).filter { $0.receipt != nil && $0.content != nil }
for installation in installations {
guard installation.content == installation.receipt?.content else {
throw AgentSkillInstallationError.modifiedSkill(name: installation.skill.name, removing: false)
}
}
return try execute(installations) { try install($0, dryRun: dryRun, force: false) }
}

func uninstall(
_ skills: [BundledAgentSkill], root: String, dryRun: Bool
) throws -> [AgentSkillInstallationOutcome] {
Expand Down Expand Up @@ -135,8 +169,12 @@ struct DefaultAgentSkillInstallationService {
from: installation.inspection.state,
to: .init(content: content, receipt: .init(name: installation.skill.name, content: content)))
}
logger.info(dryRun ? "Would install skill" : "Installed skill", metadata: metadata)
let updating = installation.content != nil
if updating {
logger.info(dryRun ? "Would update skill" : "Updated skill", metadata: metadata)
} else {
logger.info(dryRun ? "Would install skill" : "Installed skill", metadata: metadata)
}
return AgentSkillInstallationOutcome(
name: installation.skill.name, file: installation.file,
status: dryRun ? (updating ? .wouldUpdate : .wouldInstall) : (updating ? .updated : .installed),
Expand Down Expand Up @@ -179,6 +217,8 @@ struct DefaultAgentSkillInstallationService {

#if DEBUG
protocol AgentSkillInstallationService {
func list(_ skills: [BundledAgentSkill], root: String) throws -> [AgentSkillInstallationStatus]
func update(_ skills: [BundledAgentSkill], root: String, dryRun: Bool) throws -> [AgentSkillInstallationOutcome]
func install(_ skills: [BundledAgentSkill], root: String, dryRun: Bool, force: Bool) throws
-> [AgentSkillInstallationOutcome]
func uninstall(_ skills: [BundledAgentSkill], root: String, dryRun: Bool) throws
Expand Down
11 changes: 8 additions & 3 deletions Sources/CLI/skills/BundledAgentSkills.swift
Original file line number Diff line number Diff line change
Expand Up @@ -142,14 +142,19 @@ extension BundledAgentSkills {
apple-docs agent skills get apple-docs-discover-api
apple-docs agent skills install --all --dry-run
apple-docs agent skills install --all
apple-docs agent skills update --dry-run
apple-docs agent skills update
apple-docs agent skills uninstall --all --dry-run
apple-docs agent skills uninstall --all --yes
```

Skills install under `~/.agents/skills`. Use `--dir .agents` for project-local skills, or another .agents root.
Skills install under `~/.agents/skills`. Use `--project` for the Git root (current directory outside Git),
or `--dir` for another .agents root. List reports installation status and paths for the selected root.
Update refreshes only installed managed skills and refuses local edits. Use `--dry-run` to preview changes.
Installation does not configure individual agent tools. The tool must support that skill directory convention.
Obtain user approval before installing or removing skills. `--force` replaces differing managed SKILL.md files
only, never unmanaged files. Uninstall refuses modified managed files and preserves unrelated files.
Obtain user approval before installing, updating, or removing skills. `--force` replaces differing managed
SKILL.md files only, never unmanaged files. Uninstall refuses modified managed files and preserves
unrelated files.
"""

private static let discoverAPIContent = """
Expand Down
Loading
Loading