Files
skillshare/internal/plugin/pi_npm.go
T
Willie 3ba95ef49e feat(plugin): add npm packages from pi.dev through Pi (#363)
* chore(design): export dashboard tokens for design tools

Mockup tools read a design system's tokens.json rather than our CSS, so
designs drifted from the dashboard's Clean theme. The script derives the
tokens from components.css, and CI runs its test so a new color
variable without a usage note fails instead of silently going missing.

* feat(plugin): add npm packages from pi.dev through Pi

Pi packages on pi.dev are npm packages, which Plugins could not add:
it only took local or Git sources, so users had to install them with Pi
and import them. `plugin add npm:<package>` now hands them to
`pi install` for Pi targets and records the binding like an import.

Skillshare can't fetch or review an npm package, and Pi runs its install
scripts, so the preview says so, discover refuses npm sources, and only
targets that run pi itself take them. Pi keeps one entry per package
name, so another version replaces it in place and keeps its extension
filters; Skillshare records the new entry so a reinstall restores them,
and refuses a package another Skillshare package already manages, since
removing one would remove both. Pinned versions are skipped on update
because pi update keeps them.

The dashboard accepts npm sources, a pasted `pi install` command or a
pi.dev address, lists only Pi targets, and the Pi Extensions tab links
to adding a package with that target selected. Pi packages show Pi's
mark in the plugin list.

A blocked change now keeps its own reason when the Agent's CLI is also
missing, and the message key always matches the message the CLI prints.

* fix(plugin): keep npm package names and accept pi by path

The default name of an npm package went through the file-path rule, which
cut its last dot segment as an extension: npm:foo.bar was recorded as foo,
and adding npm:foo.bar@1.2.3 later derived foo.bar and was refused as
another package managing the same Pi entry. npm names are now taken from
the package spec.

A Pi account whose CLI is an absolute path to pi was treated as running
another executable, so it could not take npm packages. It now uses the
same path- and platform-aware check as the Pi Extensions tab.

* docs(wiki): add a pull-requests topic for Codex review rounds

Handling Codex's review was only known from practice: confirm each
finding, fix it with a failing test first, reply in its thread, ask for
another review, and follow up until it answers. Writing it down keeps
agents from resolving threads, amending pushed commits, or stopping at
the 👀 that only means the review is still running.

* feat(ui): give the Extras AGENTS.md and Memory tabs one layout

The two tabs shared a page but looked like different products: the header
shifted between them, notes sat in a joined box with an icon toolbar, and
agents showed as an icon strip in a side card. Switching tabs felt jarring.

Memory now follows the AGENTS.md layout: a sticky list column with search,
the note's name with Edit and a More actions menu, the same preview box,
and Use with agents as one row per tool under the note. Long notes open
collapsed like shared files do. The AGENTS.md list gains a search box and
the same sticky column. The Memory tab label stays English in every locale,
like AGENTS.md. Docs and screenshots follow the new layout.

* chore(docs): add a script that serves the Memory screenshot homes

The Memory how-to screenshots came from demo homes that were never
recorded, so reshooting them meant rebuilding the data by hand. The script
rebuilds the fresh and the populated home inside the devcontainer, serves
each behind the Vite dev server, and hands the port back to air afterwards.

* fix(plugin): refuse npm sources Pi can't resolve

validNpmSource accepted specs such as npm:foo/bar, npm:foo@ and names
containing "..", which Pi's own parser rejects. They passed preview, and
Apply recorded a pending binding before pi install failed, leaving an
entry every later sync retried. Validate with the same grammar the Pi
settings reader uses, which also covers a scope without a package name.

* fix(ui): show the default name when adding an npm package to Pi

The name field for an npm source was blank, so it looked like a name was
missing. Leaving it empty records the package name without its version or
scope, as the git flow already shows; the field now shows that name as its
placeholder.
2026-10-04 00:43:43 +08:00

139 lines
5.3 KiB
Go

package plugin
import (
"context"
"fmt"
"regexp"
"runtime"
"strings"
)
// An npm source (npm:<package>[@version], as on pi.dev) is installed by Pi itself. Skillshare
// can't fetch or review the package first, and Pi's npm install runs the package's install
// scripts, so the preview says so. The binding has no Source: like an imported package, it
// is reinstalled, updated and removed through Pi.
func isNpmSource(source string) bool { return strings.HasPrefix(source, "npm:") }
// npmSpec splits a source the way Pi does: the name keeps a leading @scope.
func npmSpec(source string) (name, version string) {
spec := strings.TrimSpace(strings.TrimPrefix(source, "npm:"))
start := 0
if strings.HasPrefix(spec, "@") {
start = 1
}
if i := strings.Index(spec[start:], "@"); i >= 0 {
return spec[:start+i], spec[start+i+1:]
}
return spec, ""
}
// exactNpmVersion is what Pi pins: an exact semver version, not a range or tag.
var exactNpmVersion = regexp.MustCompile(`^v?\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$`)
// validNpmSource accepts what Pi itself resolves as an npm package (see resolvePiSource), so
// a source Pi can't install is refused before a binding is recorded.
func validNpmSource(source string) bool {
m := piNpmSpec.FindStringSubmatch(strings.TrimPrefix(source, "npm:"))
return m != nil && piNpmName.MatchString(m[1]) && !strings.Contains(m[1], "..") && validTargetID("pi", source) && !strings.ContainsAny(source, " \t")
}
// sameNpmPackage reports whether a binding ID is an npm source of the same package, which Pi
// keeps in one entry whatever the version.
func sameNpmPackage(id, source string) bool {
a, _ := npmSpec(id)
b, _ := npmSpec(source)
return isNpmSource(id) && a == b
}
// otherPiCLI is the executable a Pi account runs instead of pi, such as a fork; Skillshare
// does not know how a fork installs npm packages.
func (s *Service) otherPiCLI(target string) string {
if a, ok := s.account(target); ok && a.CLI != "" && !piCLIIsNative(a.CLI, runtime.GOOS) {
return a.CLI
}
return ""
}
func (s *Service) npmTarget(target string) bool {
return s.agentOf(target) == "pi" && s.otherPiCLI(target) == ""
}
// npmChange plans adding an npm package to one target. installed is that target's native
// inventory, to adopt the package when Pi already has it; owner is another Skillshare package
// bound to the same Pi package there.
func (s *Service) npmChange(name, target, source, owner string, old Binding, bound bool, installed []Installed) Change {
c := Change{Name: name, Target: target, ID: source, Binding: Binding{ID: source}, Action: "install"}
if s.agentOf(target) != "pi" {
c.Action, c.Message, c.MessageKey = "blocked", "npm packages are installed by Pi; choose a Pi target.", "plugins.error.npmPiOnly"
return c
}
if cli := s.otherPiCLI(target); cli != "" {
c.Action, c.Message, c.MessageKey = "blocked", fmt.Sprintf("This account runs %s; Skillshare installs npm packages only through pi. Install it in %s, then import it.", cli, cli), "plugins.error.npmOtherCli"
c.MessageArgs = map[string]string{"cli": cli}
return c
}
if owner != "" {
c.Action, c.Message = "blocked", fmt.Sprintf("Skillshare package %s already manages this Pi package; update or remove that one instead.", owner)
return c
}
// Pi keeps one entry per package name, and installing another version replaces its source.
existing := ""
for _, item := range installed {
if sameNpmPackage(item.ID, source) {
existing = item.ID
break
}
}
if bound {
if !sameNpmPackage(old.ID, source) {
c.Action, c.Message = "blocked", "Package already has a different binding for this target; choose another name or remove it first."
return c
}
c.Binding = old
c.Binding.ID = source
// Pi keeps the entry's keys when it replaces the source, so the old version's record is stale.
if old.ID != source {
c.Binding.PiRegistration = ""
}
if old.ID == source && existing == source {
c.Action = "noop"
return c
}
} else if existing == source {
c.Action, c.Message = "import", "Already installed natively; adopt without reinstalling."
return c
}
c.Message, c.MessageKey = "Pi installs this package from npm and runs its install scripts; Skillshare can't review its content first.", "plugins.note.npmInstall"
if existing != "" && existing != source {
c.Message = fmt.Sprintf("Pi replaces %s with this version in its settings, installs it from npm and runs its install scripts; Skillshare can't review its content first.", existing)
c.MessageKey, c.MessageArgs = "plugins.note.npmReplace", map[string]string{"from": existing}
}
return c
}
// pinnedNpm reports the exact version an npm binding is pinned to, which pi update keeps.
func pinnedNpm(id string) string {
if !isNpmSource(id) {
return ""
}
if _, version := npmSpec(id); exactNpmVersion.MatchString(version) {
return version
}
return ""
}
// recordPiEntry records the entry Pi wrote for b, as an import does, so a reinstall restores
// its filters.
func (s *Service) recordPiEntry(ctx context.Context, target string, b *Binding) error {
c := Change{Target: target, ID: b.ID, Action: "import", Binding: *b}
if err := s.preparePiRegistration(ctx, &c); err != nil {
return err
}
if err := s.savePiRegistration(c); err != nil {
return err
}
b.PiRegistration = c.Binding.PiRegistration
return nil
}