Files
skillshare/cmd/skillshare/install.go
T
Willie 788f9bc6e9 feat(agents): JSON output + audit gate for install/update
Extend install/update with agent-aware --json output and apply the same
audit block-threshold gate skills already use.

Install:
- install --json: imply --force; imply --all only when neither
  --skill nor --agent is set (so explicit selectors still work)
- project-mode install now routes through cmdInstallProjectParsed
  so --json suppresses UI and emits a pure-JSON payload
- agent installs propagate SourceDir so metadata lands in the
  agents root, not the install subdir
- validation error lists --agent / --kind / --branch explicitly

Update agents:
- update agents supports --force, --skip-audit, --audit-threshold
- tracked agent repos + metadata-backed single-file agents now run
  the same audit gate as skills; blocks roll back from a temp stage
- JSON output returns the final per-agent status
  (updated/skipped/failed/up_to_date/...) by merging check results
  with batch update outcomes

Audit:
- auditInstalledAgent shares one helper with auditInstalledSkill
  (scan + cleanup callbacks); single-file agent scans now use
  audit.ScanFile / ScanFileForProject instead of staging the file
  into a temp directory
- UpdateAgentFromDiscovery stages to temp, audits, then renames
  atomically (rename already overwrites on POSIX)

Refactors pulled in while reworking these paths:
- extract jsonUISuppressor helper in json_output.go and use it
  from install/update/update_agents; collapses 4 copies of the
  suppress/restore closure dance and the per-error failJSON block
- drop relPath plumbing from installAgentFromDiscoveryInternal
  now that ScanFile doesn't need a staged relative path
- list.go render functions now use theme.ANSI() so NO_COLOR is
  respected in plain-text output

Tests:
- add TestInstallAgentFromDiscovery_HighFindingBlocked (unit)
- add TestUpdate_Agents_HighFindingBlockedByThreshold (integration)
- add TestInstall_Project_JSON_Agent_PureJSON,
  TestUpdate_Agents_JSON_ReportsFinalStatus
- fix TestList_SKILLSHARE_THEME_Light / TestList_NO_COLOR to
  write a config before invoking list
- fix TestTargetList_NoTUI_FallsBackToPlainText assertion to match
  the new structured Mode: merge output
- fix TestDoctor_AllGood_PassesAll by pinning SKILLSHARE_THEME=dark
  so the no-TTY theme fallback warning doesn't fire
- add list_tui_content_test.go covering light/dark glamour base
- list detail pane now picks LightStyleConfig on light terminals

Docs:
- update install.md, update.md, understand/agents.md for the new
  flags, JSON shapes, and agents update workflow
2026-04-10 23:27:26 +08:00

647 lines
20 KiB
Go

package main
import (
"fmt"
"os"
"path/filepath"
"strings"
"time"
"skillshare/internal/config"
"skillshare/internal/install"
"skillshare/internal/oplog"
"skillshare/internal/ui"
"skillshare/internal/validate"
)
// installArgs holds parsed install command arguments
type installArgs struct {
sourceArg string
opts install.InstallOptions
jsonOutput bool
}
// installJSONOutput is the JSON representation for install --json output.
type installJSONOutput struct {
Source string `json:"source"`
Tracked bool `json:"tracked"`
DryRun bool `json:"dry_run"`
Into string `json:"into,omitempty"`
Skills []string `json:"skills"`
Failed []string `json:"failed"`
Duration string `json:"duration"`
}
type installLogSummary struct {
Source string
Mode string
SkillCount int
InstalledSkills []string
FailedSkills []string
DryRun bool
Tracked bool
Into string
SkipAudit bool
AuditVerbose bool
AuditThreshold string
}
type installBatchSummary struct {
InstalledSkills []string
FailedSkills []string
}
// parseInstallArgs parses install command arguments
func parseInstallArgs(args []string) (*installArgs, bool, error) {
result := &installArgs{}
i := 0
for i < len(args) {
arg := args[i]
switch {
case arg == "--name":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("--name requires a value")
}
i++
result.opts.Name = args[i]
case arg == "--force" || arg == "-f":
result.opts.Force = true
case arg == "--update" || arg == "-u":
result.opts.Update = true
case arg == "--dry-run" || arg == "-n":
result.opts.DryRun = true
case arg == "--skip-audit":
result.opts.SkipAudit = true
case arg == "--audit-verbose":
result.opts.AuditVerbose = true
case arg == "--audit-threshold" || arg == "--threshold" || arg == "-T":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("%s requires a value", arg)
}
i++
threshold, err := normalizeInstallAuditThreshold(args[i])
if err != nil {
return nil, false, err
}
result.opts.AuditThreshold = threshold
case arg == "--branch" || arg == "-b":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("--branch requires a value")
}
i++
branch := strings.TrimSpace(args[i])
if branch == "" {
return nil, false, fmt.Errorf("--branch requires a non-empty value")
}
result.opts.Branch = branch
case arg == "--track" || arg == "-t":
result.opts.Track = true
case arg == "--kind":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("--kind requires a value (skill or agent)")
}
i++
kind := strings.ToLower(args[i])
if kind != "skill" && kind != "agent" {
return nil, false, fmt.Errorf("--kind must be 'skill' or 'agent', got %q", args[i])
}
result.opts.Kind = kind
case arg == "--agent" || arg == "-a":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("-a requires agent name(s)")
}
i++
result.opts.AgentNames = strings.Split(args[i], ",")
result.opts.Kind = "agent"
case arg == "--skill" || arg == "-s":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("--skill requires a value")
}
i++
result.opts.Skills = strings.Split(args[i], ",")
case arg == "--exclude":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("--exclude requires a value")
}
i++
result.opts.Exclude = strings.Split(args[i], ",")
case arg == "--into":
if i+1 >= len(args) {
return nil, false, fmt.Errorf("--into requires a value")
}
i++
result.opts.Into = args[i]
case strings.HasPrefix(arg, "--into="):
result.opts.Into = strings.TrimPrefix(arg, "--into=")
case arg == "--all":
result.opts.All = true
case arg == "--yes" || arg == "-y":
result.opts.Yes = true
case arg == "--json":
result.jsonOutput = true
case arg == "--help" || arg == "-h":
return nil, true, nil // showHelp = true
case strings.HasPrefix(arg, "-"):
return nil, false, fmt.Errorf("unknown option: %s", arg)
default:
if result.sourceArg != "" {
return nil, false, fmt.Errorf("unexpected argument: %s", arg)
}
result.sourceArg = arg
}
i++
}
// Clean --skill input
if len(result.opts.Skills) > 0 {
cleaned := make([]string, 0, len(result.opts.Skills))
for _, s := range result.opts.Skills {
s = strings.TrimSpace(s)
if s != "" {
cleaned = append(cleaned, s)
}
}
if len(cleaned) == 0 {
return nil, false, fmt.Errorf("--skill requires at least one skill name")
}
result.opts.Skills = cleaned
}
// Clean --exclude input
if len(result.opts.Exclude) > 0 {
cleaned := make([]string, 0, len(result.opts.Exclude))
for _, s := range result.opts.Exclude {
s = strings.TrimSpace(s)
if s != "" {
cleaned = append(cleaned, s)
}
}
result.opts.Exclude = cleaned
}
// Validate mutual exclusion
if result.opts.HasSkillFilter() && result.opts.All {
return nil, false, fmt.Errorf("--skill and --all cannot be used together")
}
if result.opts.HasSkillFilter() && result.opts.Yes {
return nil, false, fmt.Errorf("--skill and --yes cannot be used together")
}
if result.opts.HasSkillFilter() && result.opts.Track {
return nil, false, fmt.Errorf("--skill cannot be used with --track")
}
if result.opts.HasAgentFilter() && result.opts.Track {
return nil, false, fmt.Errorf("--agent cannot be used with --track")
}
if result.opts.ShouldInstallAll() && result.opts.Track {
return nil, false, fmt.Errorf("--all/--yes cannot be used with --track")
}
if result.opts.Branch != "" && result.sourceArg != "" {
source, parseErr := install.ParseSource(result.sourceArg)
if parseErr == nil && !source.IsGit() {
return nil, false, fmt.Errorf("--branch can only be used with git repository sources")
}
}
if result.opts.Into != "" {
if err := validate.IntoPath(result.opts.Into); err != nil {
return nil, false, err
}
}
return result, false, nil
}
func applyInstallJSONDefaults(parsed *installArgs) {
if !parsed.jsonOutput {
return
}
parsed.opts.Force = true
if !parsed.opts.HasSkillFilter() && !parsed.opts.HasAgentFilter() {
parsed.opts.All = true
}
}
// destWithInto returns the destination path, prepending opts.Into if set.
func destWithInto(sourceDir string, opts install.InstallOptions, skillName string) string {
if opts.Into != "" {
return filepath.Join(sourceDir, opts.Into, skillName)
}
return filepath.Join(sourceDir, skillName)
}
// agentsDirWithInto returns agentsDir joined with opts.Into (if set).
func agentsDirWithInto(agentsDir string, opts install.InstallOptions) string {
if opts.Into != "" {
return filepath.Join(agentsDir, opts.Into)
}
return agentsDir
}
// ensureIntoDirExists creates the Into subdirectory if opts.Into is set.
func ensureIntoDirExists(sourceDir string, opts install.InstallOptions) error {
if opts.Into == "" {
return nil
}
return os.MkdirAll(filepath.Join(sourceDir, opts.Into), 0755)
}
// parseOptsFromConfig builds install.ParseOptions from the global config.
func parseOptsFromConfig(cfg *config.Config) install.ParseOptions {
return install.ParseOptions{GitLabHosts: cfg.EffectiveGitLabHosts()}
}
// parseOptsFromProjectConfig builds install.ParseOptions from a project config.
func parseOptsFromProjectConfig(cfg *config.ProjectConfig) install.ParseOptions {
return install.ParseOptions{GitLabHosts: cfg.EffectiveGitLabHosts()}
}
// resolveSkillFromName resolves a skill name to source using metadata
func resolveSkillFromName(skillName string, cfg *config.Config) (*install.Source, error) {
store, err := install.LoadMetadataWithMigration(cfg.Source, "")
if err != nil {
return nil, fmt.Errorf("skill '%s' not found or has no metadata", skillName)
}
entry := store.GetByPath(skillName)
if entry == nil || entry.Source == "" {
return nil, fmt.Errorf("skill '%s' has no metadata, cannot update", skillName)
}
source, err := install.ParseSourceWithOptions(entry.Source, parseOptsFromConfig(cfg))
if err != nil {
return nil, fmt.Errorf("invalid source in metadata: %w", err)
}
source.Name = skillName
return source, nil
}
// resolveInstallSource parses and resolves the install source
func resolveInstallSource(sourceArg string, opts install.InstallOptions, cfg *config.Config) (*install.Source, bool, error) {
source, err := install.ParseSourceWithOptions(sourceArg, parseOptsFromConfig(cfg))
if err == nil {
return source, false, nil
}
// Try resolving from installed skill metadata if update/force
if opts.Update || opts.Force {
resolvedSource, resolveErr := resolveSkillFromName(sourceArg, cfg)
if resolveErr != nil {
return nil, false, fmt.Errorf("invalid source: %w", err)
}
ui.Info("Resolved '%s' from installed skill metadata", sourceArg)
return resolvedSource, true, nil // resolvedFromMeta = true
}
return nil, false, fmt.Errorf("invalid source: %w", err)
}
// dispatchInstall routes to the appropriate install handler
func dispatchInstall(source *install.Source, cfg *config.Config, opts install.InstallOptions) (installLogSummary, error) {
if opts.Track {
return handleTrackedRepoInstall(source, cfg, opts)
}
if source.IsGit() {
return handleGitInstall(source, cfg, opts)
}
return handleDirectInstall(source, cfg, opts)
}
func cmdInstall(args []string) error {
start := time.Now()
mode, rest, err := parseModeArgs(args)
if err != nil {
return err
}
cwd, err := os.Getwd()
if err != nil {
return fmt.Errorf("cannot determine working directory: %w", err)
}
if mode == modeAuto {
if projectConfigExists(cwd) {
mode = modeProject
} else {
mode = modeGlobal
}
}
applyModeLabel(mode)
if mode == modeProject {
parsed, showHelp, parseErr := parseInstallArgs(rest)
if showHelp {
printInstallHelp()
return parseErr
}
if parseErr != nil {
return parseErr
}
applyInstallJSONDefaults(parsed)
jsonUI := newJSONUISuppressor(parsed.jsonOutput)
defer jsonUI.Flush()
jsonWriteResult := func(summary installLogSummary, cmdErr error) error {
jsonUI.Flush()
return installOutputJSON(summary, start, cmdErr)
}
summary, err := cmdInstallProjectParsed(parsed, cwd)
if summary.Mode == "" {
summary.Mode = "project"
}
logInstallOp(config.ProjectConfigPath(cwd), rest, start, err, summary)
if parsed.jsonOutput {
return jsonWriteResult(summary, err)
}
return err
}
parsed, showHelp, parseErr := parseInstallArgs(rest)
if showHelp {
printInstallHelp()
return parseErr
}
if parseErr != nil {
return parseErr
}
applyInstallJSONDefaults(parsed)
// When no source is given, only bare "install" is valid — reject incompatible flags
if parsed.sourceArg == "" {
hasSourceFlags := parsed.opts.Name != "" || parsed.opts.Into != "" ||
parsed.opts.Track || parsed.opts.HasSkillFilter() || parsed.opts.HasAgentFilter() ||
len(parsed.opts.Exclude) > 0 || parsed.opts.Update || parsed.opts.Branch != "" ||
parsed.opts.Kind != ""
if hasSourceFlags || ((parsed.opts.All || parsed.opts.Yes) && !parsed.jsonOutput) {
return fmt.Errorf("flags --name, --into, --track, --skill, --agent, --kind, --exclude, --all, --yes, --branch, and --update require a source argument")
}
}
// In JSON mode, redirect all UI output to stderr early so the
// logo, spinner, step, and handler output don't corrupt stdout.
jsonUI := newJSONUISuppressor(parsed.jsonOutput)
defer jsonUI.Flush()
jsonWriteError := func(err error) error {
jsonUI.Flush()
return writeJSONError(err)
}
jsonWriteResult := func(summary installLogSummary, cmdErr error) error {
jsonUI.Flush()
return installOutputJSON(summary, start, cmdErr)
}
cfg, err := config.Load()
if err != nil {
if parsed.jsonOutput {
return jsonWriteError(err)
}
return fmt.Errorf("failed to load config: %w", err)
}
if parsed.opts.AuditThreshold == "" {
parsed.opts.AuditThreshold = cfg.Audit.BlockThreshold
}
// No source argument: install from global config
if parsed.sourceArg == "" {
summary, err := installFromGlobalConfig(cfg, parsed.opts)
logInstallOp(config.ConfigPath(), rest, start, err, summary)
if parsed.jsonOutput {
return jsonWriteResult(summary, err)
}
return err
}
parsed.opts.SourceDir = cfg.Source
source, resolvedFromMeta, err := resolveInstallSource(parsed.sourceArg, parsed.opts, cfg)
if err == nil && parsed.opts.Branch != "" {
source.Branch = parsed.opts.Branch
}
if err != nil {
logInstallOp(config.ConfigPath(), rest, start, err, installLogSummary{
Source: parsed.sourceArg,
Mode: "global",
})
if parsed.jsonOutput {
return jsonWriteError(err)
}
return err
}
summary := installLogSummary{
Source: parsed.sourceArg,
Mode: "global",
DryRun: parsed.opts.DryRun,
Tracked: parsed.opts.Track,
Into: parsed.opts.Into,
SkipAudit: parsed.opts.SkipAudit,
AuditVerbose: parsed.opts.AuditVerbose,
AuditThreshold: parsed.opts.AuditThreshold,
}
// If resolved from metadata with update/force, go directly to install
if resolvedFromMeta {
summary, err = handleDirectInstall(source, cfg, parsed.opts)
if summary.Mode == "" {
summary.Mode = "global"
}
if summary.Source == "" {
summary.Source = parsed.sourceArg
}
if err == nil && !parsed.opts.DryRun && len(summary.InstalledSkills) > 0 {
store, storeErr := install.LoadMetadataWithMigration(cfg.Source, "")
if storeErr != nil {
ui.Warning("Failed to load metadata: %v", storeErr)
} else if rErr := config.ReconcileGlobalSkills(cfg, store); rErr != nil {
ui.Warning("Failed to reconcile global skills config: %v", rErr)
}
}
logInstallOp(config.ConfigPath(), rest, start, err, summary)
if parsed.jsonOutput {
return jsonWriteResult(summary, err)
}
return err
}
summary, err = dispatchInstall(source, cfg, parsed.opts)
if summary.Mode == "" {
summary.Mode = "global"
}
if summary.Source == "" {
summary.Source = parsed.sourceArg
}
if err == nil && !parsed.opts.DryRun && len(summary.InstalledSkills) > 0 {
store, storeErr := install.LoadMetadataWithMigration(cfg.Source, "")
if storeErr != nil {
ui.Warning("Failed to load metadata: %v", storeErr)
} else if rErr := config.ReconcileGlobalSkills(cfg, store); rErr != nil {
ui.Warning("Failed to reconcile global skills config: %v", rErr)
}
}
logInstallOp(config.ConfigPath(), rest, start, err, summary)
if parsed.jsonOutput {
return jsonWriteResult(summary, err)
}
return err
}
// installOutputJSON converts an install summary to JSON and writes to stdout.
func installOutputJSON(summary installLogSummary, start time.Time, installErr error) error {
output := installJSONOutput{
Source: summary.Source,
Tracked: summary.Tracked,
DryRun: summary.DryRun,
Into: summary.Into,
Skills: summary.InstalledSkills,
Failed: summary.FailedSkills,
Duration: formatDuration(start),
}
return writeJSONResult(&output, installErr)
}
func logInstallOp(cfgPath string, args []string, start time.Time, cmdErr error, summary installLogSummary) {
status := statusFromErr(cmdErr)
if len(summary.InstalledSkills) > 0 && len(summary.FailedSkills) > 0 {
status = "partial"
}
e := oplog.NewEntry("install", status, time.Since(start))
fields := map[string]any{}
source := summary.Source
if len(args) > 0 {
source = args[0]
}
if source != "" {
fields["source"] = source
}
if summary.Mode != "" {
fields["mode"] = summary.Mode
}
if summary.DryRun {
fields["dry_run"] = true
}
if summary.Tracked {
fields["tracked"] = true
}
if summary.Into != "" {
fields["into"] = summary.Into
}
if summary.SkipAudit {
fields["skip_audit"] = true
}
if summary.AuditVerbose {
fields["audit_verbose"] = true
}
if summary.AuditThreshold != "" {
fields["threshold"] = strings.ToUpper(summary.AuditThreshold)
}
if summary.SkillCount > 0 {
fields["skill_count"] = summary.SkillCount
}
if len(summary.InstalledSkills) > 0 {
fields["installed_skills"] = summary.InstalledSkills
if _, ok := fields["skill_count"]; !ok {
fields["skill_count"] = len(summary.InstalledSkills)
}
}
if len(summary.FailedSkills) > 0 {
fields["failed_skills"] = summary.FailedSkills
}
if len(fields) > 0 {
e.Args = fields
}
if cmdErr != nil {
e.Message = cmdErr.Error()
}
oplog.WriteWithLimit(cfgPath, oplog.OpsFile, e, logMaxEntries()) //nolint:errcheck
}
func printInstallHelp() {
fmt.Println(`Usage: skillshare install [source|skill-name] [options]
Install skills from a local path, git repository, or global config.
When run with no arguments, installs all skills listed in config.yaml.
When using --update or --force with a skill name, skillshare uses stored metadata to resolve the source.
Sources:
user/repo GitHub shorthand (expands to github.com/user/repo)
user/repo/path/to/skill GitHub shorthand with subdirectory
github.com/user/repo Full GitHub URL (discovers skills)
github.com/user/repo/path Subdirectory in GitHub repo (direct install)
https://github.com/... HTTPS git URL
git@github.com:... SSH git URL
~/path/to/skill Local directory
Options:
--name <name> Override installed name when exactly one skill is installed
--kind <kind> Restrict discovery/install to skill or agent
--into <dir> Install into subdirectory (e.g. "frontend" or "frontend/react")
--force, -f Overwrite existing skill; also continue if audit would block
--update, -u Update existing (git pull if possible, else reinstall)
--branch, -b <name> Git branch to clone from (default: remote default)
--track, -t Install as tracked repo (preserves .git for updates)
--agent, -a <names> Select specific agents from a multi-agent repo (comma-separated)
--skill, -s <names> Select specific skills from multi-skill repo (comma-separated;
supports glob patterns like "core-*", "test-?")
--exclude <names> Skip specific skills during install (comma-separated;
supports glob patterns like "test-*")
--all Install all discovered skills without prompting
--yes, -y Auto-accept all prompts (equivalent to --all for multi-skill repos)
--dry-run, -n Preview the installation without making changes
--skip-audit Skip security audit entirely for this install
--audit-verbose Show full audit finding lines (default: compact summary)
--audit-threshold, --threshold, -T <t>
Block install by severity at/above: critical|high|medium|low|info
(also supports c|h|m|l|i)
--json Output results as JSON (implies --force --all)
--project, -p Use project-level config in current directory
--global, -g Use global config (~/.config/skillshare)
--help, -h Show this help
Examples:
skillshare install anthropics/skills
skillshare install anthropics/skills/skills/pdf
skillshare install ComposioHQ/awesome-claude-skills
skillshare install ~/my-skill
skillshare install github.com/user/repo --force
skillshare install ~/my-skill --skip-audit # Bypass scan (no findings generated)
skillshare install user/repo --all --audit-verbose
skillshare install ~/my-skill -T high # Override block threshold for this run
Selective install (non-interactive):
skillshare install org/agents --kind agent # Agents only
skillshare install org/agents -a reviewer,tutor # Specific agents
skillshare install anthropics/skills -s pdf,commit # Specific skills
skillshare install anthropics/skills -s "core-*" # Glob pattern
skillshare install anthropics/skills --all # All skills
skillshare install anthropics/skills -y # Auto-accept
skillshare install anthropics/skills -s pdf --dry-run # Preview selection
skillshare install repo --all --exclude cli-sentry # All except specific
skillshare install repo --all --exclude "test-*" # Exclude by pattern
Organize into subdirectories:
skillshare install anthropics/skills -s pdf --into frontend
skillshare install user/repo --track --into devops
skillshare install ~/my-skill --into frontend/react
Tracked repositories (Team Edition):
skillshare install team/shared-skills --track # Clone as _shared-skills
skillshare install _shared-skills --update # Update tracked repo
Install from config (no arguments):
skillshare install # Install all skills from config.yaml
skillshare install --dry-run # Preview config-based install
Update existing skills:
skillshare install my-skill --update # Update using stored source
skillshare install my-skill --force # Reinstall using stored source
skillshare install my-skill --update -n # Preview update`)
}