Files
skillshare/cmd/skillshare/install.go
T
Willie bf1731dec4 feat(move): move installed skills and folders without losing their records (#520)
Add skillshare move and POST /api/resources/batch/move so skills and
whole folders can change folder inside the source while keeping their
.metadata.json entry, accepted audit findings, lockfile pin, config
group, .gitignore and literal .skillignore lines. Moving by hand lost
the record and made the next install start over. install --into now
refuses a folder inside a skill or a tracked checkout.

Refs #510
2026-10-11 00:43:47 +08:00

678 lines
23 KiB
Go

package main
import (
"fmt"
"os"
"path/filepath"
"strings"
"time"
"skillshare/internal/config"
"skillshare/internal/install"
"skillshare/internal/oplog"
"skillshare/internal/skillmove"
"skillshare/internal/sourcefs"
"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
Err error // the batch could not start, e.g. a refused --into folder
}
// 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
result.opts.AuditOverride = 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)
trackableLocal := result.opts.Track && source != nil &&
source.Type == install.SourceTypeLocalPath && install.IsLocalGitRepo(source.Path)
if parseErr == nil && !source.IsGit() && !trackableLocal {
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
}
// Force only: --json must not silently override the audit gate.
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. It
// first refuses a folder an install must not land in: inside a skill or inside
// a tracked checkout. Links are sourcefs's to follow or refuse.
func ensureIntoDirExists(sourceDir string, opts install.InstallOptions) error {
if opts.Into == "" {
return nil
}
if err := checkIntoFolder(sourceDir, opts); err != nil {
return err
}
return sourcefs.MkdirAllIn(sourceDir, opts.Into, opts.SourceFollow)
}
// checkIntoFolder reports why opts.Into is no place for an install, with the
// code move uses for it; nil when it is fine or unset.
func checkIntoFolder(sourceDir string, opts install.InstallOptions) error {
if opts.Into == "" {
return nil
}
_, refusal := skillmove.CheckDest(opts.Into, skillmove.Options{SourceDir: sourceDir, Follow: opts.SourceFollow, Install: true})
if refusal == nil {
return nil
}
return fmt.Errorf("%s (%s)", refusal.Error(), refusal.Code)
}
// parseOptsFromConfig builds install.ParseOptions from the global config.
func parseOptsFromConfig(cfg *config.Config) install.ParseOptions {
return install.ParseOptions{
GitLabHosts: cfg.EffectiveGitLabHosts(),
AzureHosts: cfg.EffectiveAzureHosts(),
CNBHosts: cfg.EffectiveCNBHosts(),
GiteaHosts: cfg.EffectiveGiteaHosts(),
}
}
// parseOptsFromProjectConfig builds install.ParseOptions from a project config.
func parseOptsFromProjectConfig(cfg *config.ProjectConfig) install.ParseOptions {
return install.ParseOptions{
GitLabHosts: cfg.EffectiveGitLabHosts(),
AzureHosts: cfg.EffectiveAzureHosts(),
CNBHosts: cfg.EffectiveCNBHosts(),
GiteaHosts: cfg.EffectiveGiteaHosts(),
}
}
// resolveSkillFromName resolves a skill name to source using metadata
func resolveSkillFromName(skillName string, cfg *config.Config) (*install.Source, error) {
store, err := install.LoadMetadataWithMigration(cfg.EffectiveSkillsSource(), "")
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.Note(fmt.Sprintf("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, "--name", "--audit-threshold", "--threshold", "-T", "--branch", "-b", "--kind", "--agent", "-a", "--skill", "-s", "--exclude", "--into")
if err != nil {
return err
}
cwd, err := os.Getwd()
if err != nil {
return fmt.Errorf("cannot determine working directory: %w", err)
}
mode = resolveAutoMode(mode, cwd)
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
}
parsed.opts.SourceFollow = cfg.SkillsWalk().Follow
// 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.EffectiveSkillsSource()
source, resolvedFromMeta, err := resolveInstallSource(parsed.sourceArg, parsed.opts, cfg)
if err == nil && parsed.opts.Branch != "" {
source.Branch = parsed.opts.Branch
}
// Global metadata has no fixed base for a relative path, so `update` and
// `check` would resolve it against whatever directory they run in.
// Project mode keeps relative sources: they are relative to the project
// root and the project config is shared across machines.
if err == nil && source.Type == install.SourceTypeLocalPath {
source.Raw = source.Path
}
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 {
store, storeErr := install.LoadMetadataWithMigration(cfg.EffectiveSkillsSource(), "")
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 {
store, storeErr := install.LoadMetadataWithMigration(cfg.EffectiveSkillsSource(), "")
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() {
printHelp("skillshare install [source|skill-name] [options]", "Install skills from a local path, git repository, or global config.\nWhen run with no arguments, installs all skills listed in config.yaml.\nWhen using --update or --force with a skill name, skillshare uses stored metadata to resolve the source.",
helpGroup{title: "Sources", rows: []helpRow{
{"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"},
}},
helpGroup{title: "Options", rows: []helpRow{
{"--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\")"},
{"-f, --force", "Overwrite existing skill; also continue if audit would block"},
{"-u, --update", "Update existing (git pull if possible, else reinstall)"},
{"-b, --branch <ref>", "Git branch, tag, or commit SHA to install from (default: remote default)"},
{"-t, --track", "Install as tracked repo (preserves .git for updates; a local\npath works if it is a git repository)"},
{"-a, --agent <names>", "Select specific agents from a multi-agent repo (comma-separated)"},
{"-s, --skill <names>", "Select specific skills from multi-skill repo (comma-separated;\nsupports glob patterns like \"core-*\", \"test-?\")"},
{"--exclude <names>", "Skip specific skills during install (comma-separated;\nsupports glob patterns like \"test-*\")"},
{"--all", "Install all discovered skills without prompting"},
{"-y, --yes", "Auto-accept all prompts (equivalent to --all for multi-skill repos)"},
{"-n, --dry-run", "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)"},
{"-T, --audit-threshold, --threshold <t>", ""},
{"", "Block install by severity at/above: critical|high|medium|low|info\n(also supports c|h|m|l|i)"},
{"--json", "Output results as JSON (implies --force --all)"},
{"-p, --project", "Use project-level config in current directory"},
{"-g, --global", "Use global config (~/.config/skillshare)"},
}},
helpExamples(
helpRow{"skillshare install anthropics/skills", ""},
helpRow{"skillshare install anthropics/skills/skills/pdf", ""},
helpRow{"skillshare install ComposioHQ/awesome-claude-skills", ""},
helpRow{"skillshare install ~/my-skill", ""},
helpRow{"skillshare install github.com/user/repo --force", ""},
helpRow{"skillshare install ~/my-skill --skip-audit", "Bypass scan (no findings generated)"},
helpRow{"skillshare install user/repo --all --audit-verbose", ""},
helpRow{"skillshare install ~/my-skill -T high", "Override block threshold for this run"},
),
helpGroup{title: "Selective install (non-interactive)", examples: true, rows: []helpRow{
{"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"},
}},
helpGroup{title: "Organize into subdirectories", examples: true, rows: []helpRow{
{"skillshare install anthropics/skills -s pdf --into frontend", ""},
{"skillshare install user/repo --track --into devops", ""},
{"skillshare install ~/my-skill --into frontend/react", ""},
}},
helpGroup{title: "Tracked repositories (Team Edition)", examples: true, rows: []helpRow{
{"skillshare install team/shared-skills --track", "Clone as _team-shared-skills"},
{"skillshare install _team-shared-skills --update", "Update tracked repo"},
}},
helpGroup{title: "Install from config (no arguments)", examples: true, rows: []helpRow{
{"skillshare install", "Install all skills from config.yaml"},
{"skillshare install --dry-run", "Preview config-based install"},
}},
helpGroup{title: "Update existing skills", examples: true, rows: []helpRow{
{"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"},
}},
)
}