Files
skillshare/internal/plugin/model.go
T
Krishnaswamy Subramanian eb9b2b28f9 feat(plugin): add --all flag to plugin update and enable antigravity-cli updates (#656)
* Add --all flag to plugin update and enable agy

Add -a/--all to skillshare plugin update so users can update all
tracked plugins in a single command without tying slow target CLI runs
to skillshare update --all or sync --all.

- Reject --all outside plugin update or when combined with a plugin
  name or --source-ref
- Share source repository discoveries and discovery errors across the
  Preview and Apply lifecycle via Service.WithDiscoveryCache so multi-
  plugin marketplaces are cloned at most once per command
- Isolate source, manifest, and target failures per binding when --all
  is active so healthy plugins update while partial failures exit
  non-zero and leave failed bindings unchanged in config.yaml
- Skip unfiltered OMP bindings during --all updates so sibling targets
  on the same package still update without failing the batch
- Enable plugin update for antigravity-cli while skipping disabled
  plugins when agy extensions list reports an entry as disabled

Closes #653

* Add plugin update --all to docs and completions

Advertise -a/--all for skillshare plugin across all five shell
completion scripts and document the bulk update workflow and
antigravity-cli update support in the user and built-in skill docs.

- Add --all and -a to plugin completions in bash, zsh, fish,
  PowerShell, and Nushell with TestPluginCompletionsIncludeAllFlag
- Document update [NAME | --all], -a/--all, and antigravity-cli source
  updates in website/docs/reference/commands/plugin.md (and its
  zh-Hans, zh-Hant, ja, and ko translations), sharing-plugins.md, and
  quick-reference.md
- Document plugin update --all and antigravity-cli enablement checks in
  skills/skillshare/references/plugins.md

* Require known enabled state for native updates

Require a matching EnabledKnown && Enabled inventory entry before
updating copilot or antigravity-cli bindings, and align the localized
plugin workflow pages with the English docs.

- Skip copilot and antigravity-cli updates in Service.Preview and
  refuse reinstallation in applyNativeTarget when the binding is absent
  from native inventory or not known to be enabled
- Cover absent native inventory in
  TestAntigravityCLIUpdateRespectsEnablement
- Synchronize plugin update [name | --all] and Antigravity CLI update
  guidance across the ja, ko, zh-Hans, and zh-Hant copies of
  quick-reference.md and sharing-plugins.md
2026-10-27 20:57:43 +08:00

297 lines
12 KiB
Go

// Package plugin manages complete plugins through their native host CLIs.
// Plugin components are never published as standalone skills or MCP entries.
package plugin
import (
"context"
"encoding/json"
"errors"
"slices"
)
var Targets = func() []string {
var targets []string
for _, d := range TargetDefinitions() {
targets = append(targets, d.Target)
}
return targets
}()
type Binding struct {
// PiRegistration references a private, content-addressed native entry. Values
// never enter shared config or API responses; only its digest is recorded.
PiRegistration string `json:"piRegistration,omitempty" yaml:"pi_registration,omitempty"`
Entry string `json:"entry,omitempty" yaml:"entry,omitempty"`
SourceRef string `json:"sourceRef,omitempty" yaml:"source_ref,omitempty"`
Commit string `json:"commit,omitempty" yaml:"commit,omitempty"`
Components []string `json:"components,omitempty" yaml:"components,omitempty"`
Sync *bool `json:"sync,omitempty" yaml:"sync,omitempty"`
ID string `json:"id" yaml:"id"`
Source string `json:"source,omitempty" yaml:"source,omitempty"`
Plugin string `json:"plugin,omitempty" yaml:"plugin,omitempty"`
Digest string `json:"digest,omitempty" yaml:"digest,omitempty"`
Version string `json:"version,omitempty" yaml:"version,omitempty"`
Pending string `json:"pending,omitempty" yaml:"pending,omitempty"`
}
// Source, SourceRef, Plugin, Entry and Version keep a package managed while no Agent is bound,
// so Agents can be bound later from the same source and the dashboard can still show its version.
type Package struct {
Version string `json:"version,omitempty" yaml:"version,omitempty"`
Source string `json:"source,omitempty" yaml:"source,omitempty"`
SourceRef string `json:"sourceRef,omitempty" yaml:"source_ref,omitempty"`
Plugin string `json:"plugin,omitempty" yaml:"plugin,omitempty"`
Entry string `json:"entry,omitempty" yaml:"entry,omitempty"`
Bindings map[string]Binding `json:"bindings" yaml:"bindings"`
}
type Request struct {
Entry string `json:"entry,omitempty"`
SourceRef string `json:"sourceRef,omitempty"`
Action string `json:"action"`
Name string `json:"name,omitempty"`
Source string `json:"source,omitempty"`
Plugin string `json:"plugin,omitempty"`
Targets []string `json:"targets,omitempty"`
From string `json:"from,omitempty"`
All bool `json:"all,omitempty"`
}
// ProblemKey names the sentence the dashboard can translate and ProblemArgs fill its
// {placeholders}. Problem stays the English the CLI prints, and is the fallback.
type TargetPackage struct {
Manifest string `json:"manifest"`
// Path is set when this Agent's catalog points at its own folder; empty means Candidate.Path.
Path string `json:"path,omitempty"`
Marketplace string `json:"marketplace,omitempty"`
Version string `json:"version,omitempty"`
Logo string `json:"logo,omitempty"`
Entry string `json:"entry,omitempty"`
Components []string `json:"components"`
Problem string `json:"problem,omitempty"`
ProblemKey string `json:"problemKey,omitempty"`
ProblemArgs map[string]string `json:"problemArgs,omitempty"`
}
// block records why this Agent cannot take the package.
func (p *TargetPackage) block(key, message string, args map[string]string) {
p.Problem, p.ProblemKey, p.ProblemArgs = message, key, args
}
type Candidate struct {
TargetInfo map[string]TargetPackage `json:"targetInfo,omitempty"`
Name string `json:"name"`
Description string `json:"description"`
Version string `json:"version"`
Marketplace string `json:"marketplace,omitempty"`
Path string `json:"path"`
Entry string `json:"entry,omitempty"`
Targets []string `json:"targets"`
Components []string `json:"components"`
Problem string `json:"problem,omitempty"`
ProblemKey string `json:"problemKey,omitempty"`
ProblemArgs map[string]string `json:"problemArgs,omitempty"`
// catalogEntry keeps the component fields a Claude catalog entry defines itself, for the
// catalog Skillshare writes at install time (strict: false plugins have nothing else).
catalogEntry map[string]json.RawMessage
}
// pathFor is the folder, relative to the source, that target installs from.
func (c Candidate) pathFor(target string) string {
if p := c.TargetInfo[target].Path; p != "" {
return p
}
return c.Path
}
// collectTargets derives shared metadata from TargetInfo; only matching versions are shared.
func (c *Candidate) collectTargets() {
c.Targets, c.Components, c.Version = []string{}, []string{}, ""
for target, info := range c.TargetInfo {
if info.Problem != "" {
continue
}
if len(c.Targets) == 0 {
c.Version = info.Version
} else if c.Version != info.Version {
c.Version = ""
}
c.Targets = append(c.Targets, target)
for _, component := range info.Components {
if !slices.Contains(c.Components, component) {
c.Components = append(c.Components, component)
}
}
if target == "opencode" {
c.Entry = info.Entry
}
}
slices.Sort(c.Targets)
slices.Sort(c.Components)
}
// block records why this package cannot be installed from the source.
func (c *Candidate) block(key, message string, args map[string]string) {
c.Problem, c.ProblemKey, c.ProblemArgs = message, key, args
}
type Discovery struct {
Warnings []string `json:"warnings,omitempty"`
TargetDefinitions []TargetDefinition `json:"targetDefinitions"`
SourceRef string `json:"sourceRef,omitempty"`
Commit string `json:"commit,omitempty"`
Source string `json:"source"`
Digest string `json:"digest"`
Candidates []Candidate `json:"candidates"`
}
type Installed struct {
ID string `json:"id,omitempty"`
PluginID string `json:"pluginId,omitempty"`
Name string `json:"name,omitempty"`
Marketplace string `json:"marketplaceName,omitempty"`
Version string `json:"version,omitempty"`
Scope string `json:"scope,omitempty"`
ProjectPath string `json:"projectPath,omitempty"`
EnabledKnown bool `json:"enabledKnown"`
Enabled bool `json:"enabled"`
Installed bool `json:"installed"`
Filtered bool `json:"filtered,omitempty"`
Importable bool `json:"importable,omitempty"`
}
// What a caller would do about a host, so the dashboard can group Agents by the
// remedy instead of reading the English message back out of Error.
const (
HostReady = "ready" // usable
HostMissing = "missing" // its CLI is not installed or not on PATH here
HostBlocked = "blocked" // reachable, but the Agent itself has to be dealt with
)
// NoteKey and ErrorKey name the fixed sentences the dashboard can translate. Note and
// Error stay the English the CLI prints, and are the fallback when a locale lacks the key.
// A key is absent whenever the message is assembled at runtime.
type Host struct {
Target string `json:"target"`
Fingerprint string `json:"fingerprint,omitempty"`
Note string `json:"note,omitempty"`
NoteKey string `json:"noteKey,omitempty"`
Version string `json:"version"`
Status string `json:"status"`
Error string `json:"error,omitempty"`
ErrorKey string `json:"errorKey,omitempty"`
Installed []Installed `json:"installed"`
// ErrorArgs fill the {placeholders} of ErrorKey's sentence.
ErrorArgs map[string]string `json:"errorArgs,omitempty"`
// Marketplaces maps each Claude/Codex marketplace name to its root; nil when unknown.
Marketplaces map[string]string `json:"marketplaces,omitempty"`
// ManagedMarketplaces names the ones Skillshare registered from its own state directory.
ManagedMarketplaces []string `json:"managedMarketplaces,omitempty"`
// ompCacheRoot is the folder OMP caches marketplace plugins in, shared by its user scope and
// every project; a cache folder that exists there may be in use by a project not visible here.
ompCacheRoot string
}
// fail records a failure and buckets it by its cause. A failed inventory call leaves
// Installed nil, which encodes as null and breaks the dashboard's list.
func (h *Host) fail(err error) {
if h.Installed == nil {
h.Installed = []Installed{}
}
h.Error = err.Error()
h.ErrorKey, h.ErrorArgs = "", nil
h.Status = HostBlocked
var keyed agentError
if errors.As(err, &keyed) {
h.ErrorKey, h.ErrorArgs = keyed.key, keyed.args
}
if errors.Is(err, ErrCLIMissing) {
h.Status = HostMissing
}
}
// block records a failure the caller resolves in the Agent, not by installing anything.
// key names the sentence for the dashboard; message is the English the CLI prints.
func (h *Host) block(key, message string) {
h.Error = message
h.ErrorKey = key
h.Status = HostBlocked
}
type Inventory struct {
TargetDefinitions []TargetDefinition `json:"targetDefinitions"`
Packages map[string]Package `json:"packages"`
Hosts []Host `json:"hosts"`
}
type Change struct {
PreservedKeys []string `json:"preservedKeys,omitempty"`
piRecord []byte
piSettingsHash string
piRestores map[string]piRestoreReceipt
ompRemoval *ompRemoval
ompRuntimePath string
// piRecordAfter records the entry Pi writes on install, which keeps another version's filters.
piRecordAfter bool
batchError bool
Name string `json:"name"`
Target string `json:"target"`
ID string `json:"id"`
Action string `json:"action"`
Message string `json:"message,omitempty"`
// MessageKey names Message for the dashboard to translate, with MessageArgs.
MessageKey string `json:"messageKey,omitempty"`
MessageArgs map[string]string `json:"messageArgs,omitempty"`
Binding Binding `json:"binding"`
Components []string `json:"components,omitempty"`
// Logo is the package logo for a change with no Agent, as a data: URI.
Logo string `json:"logo,omitempty"`
}
type Plan struct {
Revision string `json:"revision"`
Blocked bool `json:"blocked"`
Changes []Change `json:"changes"`
}
type Outcome struct {
Name string `json:"name"`
Target string `json:"target"`
Status string `json:"status"`
Message string `json:"message,omitempty"`
// MessageKey names Message for the dashboard to translate, with MessageArgs.
MessageKey string `json:"messageKey,omitempty"`
MessageArgs map[string]string `json:"messageArgs,omitempty"`
}
type Result struct {
Results []Outcome `json:"results"`
}
// Runner runs one native CLI: a working directory, environment entries on top of the
// process environment, the binary and its arguments.
type Runner func(context.Context, string, []string, string, ...string) ([]byte, error)
type Service struct {
ConfigPath string
StateDir string
ProjectRoot string
// GlobalConfigPath is the global config when ConfigPath is a project's: the plugins
// it binds own the global Pi packages a project inherits.
GlobalConfigPath string
// Accounts are the targets that are another config directory of a built-in Agent,
// keyed by the name the config gives them.
Accounts map[string]Account
// ExtrasSources maps each extra to its source folder, so a Pi extension that an
// extra links into Pi's folder is shown as that extra's file.
ExtrasSources map[string]string
Run Runner
// findCodex stands in for the Codex CLI search in tests; nil searches this machine.
findCodex func() (string, []string)
// discoveries keeps each source UpdateBatch read while it runs, so its plugins share one copy.
discoveries map[string]*Discovery
discoveryErrs map[string]error
}
func (b Binding) Selected() bool { return b.Sync == nil || *b.Sync }