Files
Rusty ShacklefordandWillie 43059a1428 fix(opencode): preserve v2 hook and plugin directory packages (#915)
* fix(opencode): preserve v2 directory packages

Stage the reviewed issue 913 source for isolated fork validation. Preserve
package directories and manifests without executing managed packages or
installing their dependencies, and include receipt and localized UI fixes.

Reviewed local source: 15ac88e2f266571b8a6dc8d777302db0f4dcae44
Exact source tree: 45ebabfe2b

Static checks and independent inspection completed. Go, integration,
dashboard, rendering, and hosted runtime validation remain pending.
This fork staging commit is not an upstream publication or merge.

* test(opencode): align schema and snapshot assertions

Check the version-aware binding schema and verify native unregister retains the unchanged managed snapshot.

* fix(opencode): resolve Windows npm native launchers

Probe recognized native Opencode executables without invoking a batch shell; exercise the default version probe on hosted Windows.

* test(opencode): normalize Windows fixture line endings

Avoid doubling carriage returns when Git checks out the npm fixture with CRLF.

* fix(opencode): keep an undetected OpenCode version from blocking other agents

Review of the v2 directory package change found that one failed
`opencode --version` probe failed the whole hooks plan, so a machine
without the binary (a second machine sharing the config, CI, a
devcontainer) could no longer sync hooks to any agent, and doctor and
the dashboard preview failed with it.

Hooks:
- A probe that fails or reports an unknown major now skips only the
  OpenCode bindings with one warning per target. Outputs already owned
  there are parked, so they are neither rewritten nor removed while the
  layout is unknown. The probe runs once per plan, list and import.
- A `package` binding on OpenCode v1 is skipped with a warning instead
  of failing the plan.
- The v2 dependency warning is reported once, and only when a package
  file is written, so a synced hook no longer keeps doctor yellow.
- `hooks import` reports an unreadable file such as a symlink as that
  package's problem; other packages and flat files stay importable.
  The package validation problem is reported once instead of twice.
- Directories under `plugins/` are listed as unmanaged only on v2.

Plugins:
- The inventory leaves `plugins/skillshare-NAME` registrations to
  hooks, so a synced v2 hook is not offered as an importable plugin.

Dashboard: the new warnings are translated in every locale, a
`hook NAME:` prefix no longer defeats translation, the native preview
translates its per-file error, and the YAML editor documents `package`.

Docs: the English pages and the built-in skill describe the behavior
above; the ja, ko, zh-Hans and zh-Hant pages now carry the same
content as the English ones. The runbook drives the CLI with mdproof
assertions instead of prose expectations.

Refs #913.

---------

Co-authored-by: Willie <egg358358@gmail.com>
2026-11-16 01:50:14 +08:00

570 lines
19 KiB
Go

package plugin
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"slices"
"strings"
)
// Declarations deliberately cannot encode native IDs or installation progress.
type declaration struct {
Source string `yaml:"source,omitempty" json:"source,omitempty"`
SourceRef string `yaml:"source_ref,omitempty" json:"sourceRef,omitempty"`
Plugin string `yaml:"plugin,omitempty" json:"plugin,omitempty"`
Entry string `yaml:"entry,omitempty" json:"entry,omitempty"`
Imported bool `yaml:"imported,omitempty" json:"imported,omitempty"`
Sync *bool `yaml:"sync,omitempty" json:"-"`
}
type packageDeclaration struct {
Source string `yaml:"source,omitempty"`
SourceRef string `yaml:"source_ref,omitempty"`
Plugin string `yaml:"plugin,omitempty"`
Entry string `yaml:"entry,omitempty"`
Bindings map[string]declaration `yaml:"bindings"`
}
type receipt struct {
Intent string `json:"intent"`
Store string `json:"store"`
Binding Binding `json:"binding"`
Action string `json:"action,omitempty"`
OMPRemovalVersion string `json:"ompRemovalVersion,omitempty"`
}
type localBinding struct {
Applied *receipt `json:"applied,omitempty"`
Pending *receipt `json:"pending,omitempty"`
// Legacy is a passive proof candidate, never executable installation state.
Legacy *receipt `json:"legacy,omitempty"`
// LegacySeen survives cleanup so unchanged v1 YAML cannot recreate ownership.
LegacySeen bool `json:"legacySeen,omitempty"`
}
type localState struct {
Version int `json:"version"`
Bindings map[string]map[string]localBinding `json:"bindings"`
Versions map[string]packageVersion `json:"versions,omitempty"`
}
func (b declaration) fingerprint() string { b.Sync = nil; raw, _ := json.Marshal(b); return hash(raw) }
func (b declaration) runtime() Binding {
r := Binding{Source: b.Source, SourceRef: b.SourceRef, Plugin: b.Plugin, Entry: b.Entry, Sync: b.Sync, Imported: b.Imported}
if isNpmSource(b.Source) {
r.Source = ""
} // The adapter's npm contract has no snapshot.
return r
}
func declareBinding(b Binding) declaration {
return declaration{Source: b.Source, SourceRef: b.SourceRef, Plugin: b.Plugin, Entry: b.Entry, Imported: b.Source == "", Sync: b.Sync}
}
func (s *Service) statePath() string { return filepath.Join(s.managedRoot(), "state.json") }
func (s *Service) operationLockPath() string {
return filepath.Join(s.managedRoot(), ".operation.lock")
}
// storeIdentity prevents an old receipt from removing a plugin in a new account.
func (s *Service) storeIdentity(target string) string {
a, account := s.account(target)
home, _ := os.UserHomeDir()
dir := a.Dir
agent := s.agentOf(target)
if !account {
switch agent {
case "pi":
dir, _ = s.piSettingsPath(target)
case "opencode":
dir, _ = s.openCodeConfigPath(target)
case "claude":
dir = os.Getenv(accountEnv[agent])
if dir == "" {
dir = filepath.Join(home, ".claude")
}
case "codex":
dir = os.Getenv(accountEnv[agent])
if dir == "" {
dir = filepath.Join(home, ".codex")
}
case "omp":
dir = ompPluginRoot(home, "omp") + "\x00" + ompDefaultCacheRoot()
case "cursor", "antigravity":
dir, _, _ = s.localRoot(target)
default:
dir = home
}
}
raw, _ := json.Marshal([]any{agent, dir, a.CLI, s.ProjectRoot})
return string(raw)
}
func (s *Service) loadState(d *document) error {
path := s.statePath()
if err := noSymlink(s.StateDir, path); err != nil {
return err
}
raw, err := os.ReadFile(path)
if err != nil && !os.IsNotExist(err) {
return err
}
d.stateRaw = raw
d.state = localState{Version: 1, Bindings: map[string]map[string]localBinding{}}
if err == nil {
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&d.state); err != nil {
return fmt.Errorf("invalid plugin local state: %w", err)
}
if d.state.Version != 1 || d.state.Bindings == nil {
return fmt.Errorf("unsupported plugin local state version or bindings")
}
if dec.Decode(new(any)) != io.EOF {
return fmt.Errorf("invalid plugin local state document")
}
for name, targets := range d.state.Bindings {
if !namePattern.MatchString(name) {
return fmt.Errorf("invalid plugin local package")
}
for _, b := range targets {
if b.Legacy != nil && (b.Legacy.Action != "" || b.Legacy.Binding.Pending != "") {
return fmt.Errorf("invalid passive plugin legacy hint for %s", name)
}
for _, r := range []*receipt{b.Applied, b.Pending, b.Legacy} {
if r == nil {
continue
}
var store []string
if json.Unmarshal([]byte(r.Store), &store) != nil || len(store) != 4 || !validTargetID(store[0], r.Binding.ID) || r.Intent == "" || r.Action != "" && !slices.Contains([]string{"install", "update", "remove", "uninstall", "import", "forget"}, r.Action) {
return fmt.Errorf("invalid plugin local receipt for %s", name)
}
}
}
}
}
// A disappeared shared file is not a declaration to remove every local plugin.
if d.raw == nil && d.hasReceipts() {
return fmt.Errorf("plugin configuration is missing; restore it before reconciling local installations")
}
s.compose(d)
return nil
}
func (s *Service) compose(d *document) {
d.packages = map[string]Package{}
for name, p := range d.intent {
pack := d.packageWithVersion(name, p)
for target, decl := range p.Bindings {
b := decl.runtime()
local := d.state.Bindings[name][target]
r := local.Applied
if r == nil && local.Pending != nil {
r = local.Pending
}
if r != nil {
b = r.Binding
b.Sync = decl.Sync
// Older native-only receipts predate the explicit Imported flag.
// Managed npm receipts also omit Source, but retain an npm recipe fingerprint.
imported := r.Binding.Imported || r.Binding.Source == "" && r.Intent == (declaration{Imported: true}).fingerprint()
b.Imported = decl.Imported || imported
b.ImportRetained = imported && !decl.Imported && r.Intent != decl.fingerprint()
b.Cleanup = !imported && r.Intent != decl.fingerprint() && (r.Binding.Source != decl.Source || r.Binding.Plugin != decl.Plugin || r.Binding.Entry != decl.Entry || decl.Imported)
b.ContextChanged = r.Store != s.storeIdentity(target)
b.RefChanged = b.Selected() && sameDistribution(r.Binding, decl) && r.Binding.SourceRef != decl.SourceRef
if local.Pending != nil && local.Pending.Intent == decl.fingerprint() {
b.Pending = local.Pending.Action
}
}
pack.Bindings[target] = b
}
d.packages[name] = pack
}
for name, targets := range d.state.Bindings {
pack := d.packages[name]
if pack.Bindings == nil {
pack.Bindings = map[string]Binding{}
}
for target, local := range targets {
if _, ok := pack.Bindings[target]; ok {
continue
}
r := local.Applied
if r == nil {
r = local.Pending
}
if r == nil {
continue
}
b := r.Binding
b.Cleanup = true
b.ContextChanged = r.Store != s.storeIdentity(target)
pack.Bindings[target] = b
}
if len(pack.Bindings) > 0 {
d.packages[name] = pack
}
}
}
// UnimportTargets lists local imports backed by this target's shared source recipe.
func (s *Service) UnimportTargets(name string) ([]string, error) {
d, err := s.load()
if err != nil {
return nil, err
}
var targets []string
for target := range d.packages[name].Bindings {
if d.canUnimport(name, target) {
targets = append(targets, target)
}
}
slices.Sort(targets)
return targets, nil
}
func (d *document) canUnimport(name, target string) bool {
decl, declared := d.intent[name].Bindings[target]
b := d.packages[name].Bindings[target]
return declared && !decl.Imported && decl.Source != "" && b.Imported && b.ID != ""
}
func (s *Service) saveState(d *document) error {
if !filepath.IsAbs(s.StateDir) {
return fmt.Errorf("plugin state directory must be absolute")
}
path := s.statePath()
if err := noSymlink(s.StateDir, path); err != nil {
return err
}
current, err := os.ReadFile(path)
if err != nil && !os.IsNotExist(err) {
return err
}
if !bytes.Equal(current, d.stateRaw) {
return fmt.Errorf("plugin local state changed; preview again")
}
data, err := json.MarshalIndent(d.state, "", " ")
if err != nil {
return err
}
data = append(data, '\n')
if bytes.Equal(current, data) {
return nil
}
if err := os.MkdirAll(s.managedRoot(), 0700); err != nil {
return err
}
if err := atomicNativeWrite(s.StateDir, path, data, 0600); err != nil {
return err
}
d.stateRaw = data
return nil
}
func (d *document) putLocal(name, target string, b localBinding) {
if b.Applied == nil && b.Pending == nil && b.Legacy == nil && !b.LegacySeen {
delete(d.state.Bindings[name], target)
if len(d.state.Bindings[name]) == 0 {
delete(d.state.Bindings, name)
}
return
}
if d.state.Bindings[name] == nil {
d.state.Bindings[name] = map[string]localBinding{}
}
d.state.Bindings[name][target] = b
}
func (d *document) checkIntent(path string) error {
raw, err := os.ReadFile(path)
if err != nil && !os.IsNotExist(err) {
return err
}
if !bytes.Equal(raw, d.raw) {
return fmt.Errorf("configuration changed; preview again")
}
return nil
}
// checkApplyIntent is also called at adapter write boundaries after materialization.
func (s *Service) checkApplyIntent() error {
if s.applyConfig == nil {
return nil
}
return (&document{raw: *s.applyConfig}).checkIntent(s.ConfigPath)
}
// captureLegacy runs before intent mutation: a later proof must retain the
// original declaration and store even if the shared target is removed or replaced.
func (s *Service) captureLegacy(d *document) {
for name, p := range d.legacy {
for target, b := range p.Bindings {
local := d.state.Bindings[name][target]
if local.LegacySeen {
continue
}
local.LegacySeen = true
if local.Applied == nil && local.Legacy == nil {
b.Pending = ""
local.Legacy = &receipt{Intent: declareBinding(b).fingerprint(), Store: s.storeIdentity(target), Binding: b}
}
d.putLocal(name, target, local)
}
}
}
// Legacy candidates become receipts only after the same scoped native, snapshot
// and private-registration proofs, independently of today's shared declarations.
// Names optionally limit a read-only projection to its requested packages.
func (s *Service) adoptLegacy(d *document, host func(string) Host, names ...string) {
prove := func(name, target string, hint *receipt) {
if len(names) > 0 && !slices.Contains(names, name) {
return
}
local := d.state.Bindings[name][target]
if local.Applied != nil || hint.Store != s.storeIdentity(target) {
return
}
b := hint.Binding
h := host(target)
if h.Error != "" || !slices.ContainsFunc(h.Installed, func(i Installed) bool { return i.ID == b.ID }) {
return
}
if b.Source != "" {
if !s.ownedSnapshot(b, target) {
return
}
if marketplaceAgent(s.agentOf(target)) {
_, market, _ := strings.Cut(b.ID, "@")
if filepath.Clean(h.Marketplaces[market]) != s.snapshotPath(b, target) {
return
}
}
}
if b.PiRegistration != "" {
if _, err := s.readPiRegistration(b.PiRegistration, target, b.ID); err != nil {
return
}
}
b.Pending = ""
local.Applied = &receipt{Intent: hint.Intent, Store: hint.Store, Binding: b}
local.Legacy = nil
d.putLocal(name, target, local)
}
for name, targets := range d.state.Bindings {
for target, local := range targets {
if local.Legacy != nil {
prove(name, target, local.Legacy)
}
}
}
for name, p := range d.legacy {
for target, b := range p.Bindings {
// A captured candidate's context and fingerprint take precedence over current intent.
if local := d.state.Bindings[name][target]; local.Legacy != nil || local.LegacySeen {
continue
}
prove(name, target, &receipt{Intent: declareBinding(b).fingerprint(), Store: s.storeIdentity(target), Binding: b})
}
}
s.compose(d)
}
func (s *Service) ownedSnapshot(b Binding, target string) bool {
if b.Source == "" || b.ID == "" || b.Digest == "" {
return false
}
root := s.snapshotPath(b, target)
if err := noSymlink(s.managedRoot(), root); err != nil {
return false
}
owner, err := os.ReadFile(filepath.Join(root, ".skillshare-owner"))
if err != nil || string(owner) != b.Source+"\n"+b.Plugin {
return false
}
recorded, err := os.ReadFile(filepath.Join(root, ".skillshare-digest"))
if err != nil || string(recorded) != b.Digest {
return false
}
actual, err := treeDigest(filepath.Join(root, "content"))
if err != nil || actual != b.Digest {
return false
}
agent := s.agentOf(target)
if agent == "pi" || agent == "opencode" {
disc, err := discoverRoot(filepath.Join(root, "content"), b.Source, b.Entry)
if err != nil {
return false
}
for _, c := range disc.Candidates {
if c.Name == b.Plugin {
path := filepath.Join(root, "content", filepath.FromSlash(c.pathFor(agent)))
if agent == "opencode" {
return b.ID == fileURL(path) || b.ID == fileURL(filepath.Join(path, c.Entry))
}
return b.ID == path
}
}
return false
}
return true
}
func sameDistribution(b Binding, decl declaration) bool {
return !decl.Imported && b.Source == decl.Source && b.Plugin == decl.Plugin && b.Entry == decl.Entry
}
// Native IDs for reviewed source installations are still generated by add's
// existing discovery and adapters, including target-specific nested paths.
func (s *Service) sourceChange(ctx context.Context, name, target string, decl declaration, all bool, cleanup *ompRemoval) (Change, error) {
p, err := s.preview(ctx, Request{Action: "add", Name: name, Targets: []string{target}, Source: decl.Source, SourceRef: decl.SourceRef, Plugin: decl.Plugin, Entry: decl.Entry}, cleanup)
if err != nil {
return sourceChangeFailure(name, target, all, err)
}
if len(p.Changes) != 1 {
return Change{}, fmt.Errorf("source preview did not resolve one target")
}
c := p.Changes[0]
c.Binding.Sync = decl.Sync
return c, nil
}
func localImportMessage() string {
return "Import required on this machine; use plugin import --from TARGET --name NAME with its local native identifier."
}
// declarationForAdd retains the recipe even when the adapter adopts a native ID.
func declarationForAdd(r Request, c Change) declaration {
if c.recipe != nil {
return *c.recipe
}
if isNpmSource(r.Source) {
return declaration{Source: r.Source, Sync: c.Binding.Sync}
}
b := declareBinding(c.Binding)
if c.Binding.Source == "" {
b = declaration{Source: canonicalSource(r.Source), SourceRef: r.SourceRef, Plugin: r.Plugin, Entry: r.Entry, Sync: c.Binding.Sync}
if b.Plugin == "" {
b.Plugin = c.Name
}
}
return b
}
// Source errors use the same per-binding failure contract as update --all.
func sourceChangeFailure(name, target string, all bool, err error) (Change, error) {
if !all {
return Change{}, err
}
key, args := ErrorKey(err)
return Change{Name: name, Target: target, Action: "skip", Failed: true, Message: err.Error(), MessageKey: key, MessageArgs: args}, nil
}
// Prepare the replacement before scheduling cleanup, so a failed batch target
// keeps its existing local installation and cleanup receipt.
func (s *Service) sourceReplacementChanges(ctx context.Context, r Request, name, target string, decl declaration, declared bool, removal Change) ([]Change, error) {
changes := []Change{removal}
if r.Action != "remove" && declared && (decl.Sync == nil || *decl.Sync) && !decl.Imported {
c, err := s.sourceChange(ctx, name, target, decl, r.isolatesTargets(), removal.ompRemoval)
if err != nil {
return nil, err
}
if r.isolatesTargets() && c.Action == "blocked" {
c.Action, c.Failed = "skip", true
}
if c.Failed {
return []Change{c}, nil
}
changes = append(changes, c)
}
return changes, nil
}
// importMatchesRecipe compares package identities, not a dashboard's logical alias.
// Native paths need their manifest identity; their basename may just be index.js.
func (s *Service) importMatchesRecipe(ctx context.Context, target string, installed Installed, decl declaration) (bool, error) {
if isNpmSource(decl.Source) {
return sameNpmPackage(installed.ID, decl.Source), nil
}
nativeName := installed.Name
agent := s.agentOf(target)
switch {
case marketplaceAgent(agent) || agent == "omp" && strings.Contains(installed.ID, "@"):
nativeName, _, _ = strings.Cut(installed.ID, "@")
case isNpmSource(installed.ID):
nativeName = logicalName(installed.ID)
case agent == "opencode":
id := installed.ID
if path, err := s.openCodeLocalPath(target, id); err != nil {
return false, err
} else if path != "" {
id = path
}
root, ok := openCodeImportRoot(id, decl.Entry)
if !ok {
return false, nil
}
if root != "" {
nativeName = importManifestName(root, decl, "")
}
case agent == "pi":
settings, err := s.piSettingsPath(target)
if err != nil {
return false, err
}
scope := "user"
if s.ProjectRoot != "" {
scope = "project"
}
path := resolvePiSource(installed.ID, filepath.Dir(settings), filepath.Dir(settings), scope).install
if filepath.IsAbs(path) {
if info, err := os.Stat(path); err == nil && !info.IsDir() {
path = filepath.Dir(path)
for parent := path; ; parent = filepath.Dir(parent) {
if info, err := os.Stat(filepath.Join(parent, "package.json")); err == nil && info.Mode().IsRegular() {
path = parent
break
}
if filepath.Dir(parent) == parent {
break
}
}
}
nativeName = importManifestName(path, decl, nativeName)
}
}
if decl.Plugin != "" {
return nativeName == decl.Plugin, nil
}
// Import observes local installations. Do not fetch a remote recipe to infer
// a missing identity: accepting an alias would also admit unrelated plugins.
source := canonicalSource(decl.Source)
info, err := os.Stat(source)
if err != nil || !info.IsDir() {
return false, agentError{key: "plugins.error.importRecipeIdentityRequired", message: "This remote recipe has no plugin identity. Set plugin: to the native package name in the shared declaration before importing; import does not download source."}
}
source, err = filepath.Abs(source)
if err != nil {
return false, err
}
disc, err := s.discover(ctx, source, decl.SourceRef, decl.Entry)
if err != nil {
return false, err
}
for _, candidate := range disc.Candidates {
if candidate.Name == nativeName && slices.Contains(candidate.Targets, agent) && candidate.Problem == "" {
return true, nil
}
}
return false, nil
}
// importManifestName reads native package identity without acquiring source.
func importManifestName(path string, decl declaration, fallback string) string {
if native, err := discoverRoot(path, path, decl.Entry); err == nil {
for _, candidate := range native.Candidates {
if candidate.Name == decl.Plugin || decl.Plugin == "" && len(native.Candidates) == 1 {
return candidate.Name
}
}
}
return fallback
}