pluginformat

package
v0.45.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 2, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package pluginformat decides which runtime loads a `plugins:` entry.

A plugin directory belongs to one of two families (ADR 0094): a manifest bundle a runtime reads at startup (a Claude plugin, marked by plugin.json at its root or by Claude Code's own .claude-plugin/plugin.json), or a code module the runtime loads and executes (pi's `-e <dir>` extensions). One harness key lists both, so something has to tell them apart per entry — that is this package.

It is a leaf: it imports neither internal/harness nor internal/runtime, because both import it (harness validates entries with it, the runtime filters the entries of its own kind with it).

Index

Constants

View Source
const ExtensionUnsafeNameChars = "\n\r\\"

ExtensionUnsafeNameChars are the characters a file or directory name in an extension tree may not contain. GNU sha256sum escapes all three and prefixes the line with "\", which the Go side of the tree hash does not mirror, and a newline would break the directory listing too — so the host and sandbox implementations could not agree on such a name.

Variables

View Source
var PiReservedExtensionNames = []string{"fullsend-hooks", "fullsend-agent", "fullsend-edit-repair", "anthropic-vertex", "xai-vertex"}

PiReservedExtensionNames are the sandbox names the pi runtime owns: the basenames of the extensions Bootstrap embeds (hook adapter, Agent tool, edit repair) and the vendored provider extensions Run loads by path. A declared extension uploads under its directory basename, so one of these names would shadow — or be mistaken for — runner-owned code. runtime.piResolveRunPlugins refuses them again at bootstrap; the check here is so a harness author learns at load which entry is the problem. The list lives in this package because both internal/harness and internal/runtime read it.

Functions

func ExtensionEntryProblem

func ExtensionEntryProblem(rel string, mode fs.FileMode) string

ExtensionEntryProblem reports why one entry of an extension tree is not admissible, or "" when it is. It is the single definition of the rule the tree hash (runtime.piExtensionTreeHash and its POSIX-sh twin), the injection scan and harness validation all apply: regular files and directories only, with reproducible names.

Refusing symlinks is not tidiness. pi follows a symlink when it resolves an entry point, and the sandbox-side `find . ! -type f ! -type d` probe prints nothing for such a tree, so a symlink left in the verdict would be a way to swap an extension's code without moving its hash. Trees fetched from a forge cannot carry symlinks anyway, so nothing legitimate is lost. The extension root itself may still be a symlink — cache paths are named symlinks into the content-addressed store — because callers resolve it with filepath.EvalSymlinks before walking.

func PiArgsProblem

func PiArgsProblem(args []string) string

PiArgsProblem reports why an entry's `pi: {args}` list is not admissible, or "" when it is. It checks the args against the shape pi's own parser gives them (cli/args.ts parseArgs at 0.84.4; 0.85.0 changes only the help text, adding PI_SERVER_DIR/PI_SERVER_ID):

  • `--flag=value` sets the flag and consumes nothing after it;
  • a bare `--flag` consumes the next element as its value, but only when that element starts with neither "-" nor "@";
  • every other element that is not dash-prefixed is pushed onto `messages` — pi *prompt text*, prepended to the runner's own prompt. `@word` is read as a file to attach.

So a bare word is legal exactly once, directly after a `--flag` written without "=". Two in a row, or one after `--flag=value`, is prompt injection through the harness rather than a flag value.

func PiLoadProblem

func PiLoadProblem(files, dirs map[string]bool, read func(rel string) ([]byte, error)) string

PiLoadProblem reports why pi would load nothing from an extension directory given with `-e <dir>`, or "" when pi would load it. It mirrors pi's own rule for a local directory source (core/package-manager.ts resolveLocalExtensionSource -> collectPackageResources, core/pi-manifest.ts readPiManifest, verified at 0.84.4 by reading the source and by running each shape below):

  1. If package.json parses and carries a "pi" *object*, readPiManifest returns non-null, collectPackageResources adds the manifest entries and returns true — so the directory itself is never loaded and index.* and "main" are never consulted. The verdict then rests entirely on "pi.extensions": `{"pi":{}}`, `{"pi":{"skills":[...]}}` and a "pi.extensions" whose entries do not resolve all load *nothing*, silently, with pi exiting 0.
  2. Otherwise, if any of extensions/, prompts/, skills/ or themes/ exists, the directory is a package: index.* is ignored and nothing is loaded from a `-e` that named it.
  3. Otherwise a package.json "main" pointing at an existing file, or one of index.js/index.ts/index.mjs/index.cjs.

Outside the "pi" manifest there is deliberately no discovery branch: a bare top-level tools.js or a subdirectory with its own index.js is *not* loaded (pi exits 1 with `Failed to load extension ... Cannot find module`), so accepting either here would let a harness ship an extension that cannot start.

files and dirs are the listings of regular files and of directories, as slash-separated paths relative to the directory; read returns a file's bytes (only package.json files are read). Used on local directories and on fetched trees alike so a harness never ships an extension pi refuses.

func PiTreeLoadProblem

func PiTreeLoadProblem(tree map[string][]byte) string

PiTreeLoadProblem applies PiLoadProblem to a fetched tree map (relative path → content). Directories are derived from the file paths: a forge tree carries no empty directories (and no symlinks), so the parents of the fetched files are the whole directory set.

func TreeEntriesProblem

func TreeEntriesProblem(dir string) (string, error)

TreeEntriesProblem walks a plugin directory and reports the first entry no runtime may load — a symlink, a special file, a name the sandbox preflight could not reproduce (ExtensionEntryProblem) — or "" when the tree is clean. The pi detector applies the same rule as part of its own walk; a Claude plugin is claimed by its marker alone, so harness validation calls this for it separately. The rule is one for every kind: the upload would carry a symlink's target into the sandbox, and the injection scan (which refuses the same entries) only runs when security is enabled.

Types

type Kind

type Kind string

Kind is the runtime family a plugin directory belongs to. The zero value is the undetected kind: Detect and DetectTree return it together with the problem string that says why neither family claimed the directory.

const (
	// KindClaude is a Claude Code plugin: a directory carrying one of the
	// claudeMarkerFiles, uploaded into the runtime's plugins/ directory.
	KindClaude Kind = "claude"
	// KindPi is a pi extension: a directory pi's `-e <dir>` loader resolves
	// an entry point in, uploaded and loaded as code.
	KindPi Kind = "pi"
)

func Detect

func Detect(dir string) (Kind, string, error)

Detect reports the kind of a local plugin directory. The second return is empty on success and, when no family claims the directory, says why — both halves of the verdict, so the harness author does not have to guess which one was meant. The error is reserved for a directory that cannot be read or holds an entry no runtime may load (a symlink, a special file, a name the sandbox preflight could not reproduce).

The Claude markers are checked first, and a directory that has one is never put through pi's rule: a Claude plugin that bundles a Node MCP server ships a package.json whose "main" resolves, which would otherwise make it look like a pi extension as well.

func DetectTree

func DetectTree(files map[string][]byte) (Kind, string)

DetectTree is Detect for a fetched tree (relative slash path → content), the form base composition and the forge fetchers work in. It applies the same precedence and returns the same verdict; a tree carries no symlinks or special files, so there is no error return.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL