pkgmgr

package
v0.34.0 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package pkgmgr installs and resolves resource packages: bundles of skills, prompt templates, themes and extensions distributed over npm, git, or a local directory.

A package is just a directory. What makes it a package is that tau knows how to fetch it, where it put it, and which files inside it count as resources — either because a manifest says so or because they sit where resources live.

Index

Constants

This section is empty.

Variables

View Source 
var ErrUntrusted = errors.New("project is not trusted")

ErrUntrusted is returned when a project-scoped operation is attempted in a directory the user has not trusted.

View Source 
var ResourceTypes = []ResourceType{TypeExtensions, TypeSkills, TypePrompts, TypeThemes}

ResourceTypes is every resource type, in the order they are collected.

Functions

func CollectFiles 

func CollectFiles(packageRoot string, t ResourceType) (all []string, enabled map[string]bool)

CollectFiles returns the resource files a manifest entry list resolves to, together with the subset the package itself leaves enabled.

A package speaks twice here: its source entries say what exists, and any override patterns among them say what starts switched off. Those are the package author's defaults; the user's own patterns are applied later, on top.

func ConventionDir 

func ConventionDir(packageRoot string, t ResourceType) string

ConventionDir is where a resource type lives when a package has no manifest.

func FilterPaths 

func FilterPaths(paths, patterns []string, baseDir string) []string

FilterPaths applies a user's enable/disable patterns to already-discovered resource paths.

This is the half of per-resource control that has nothing to do with packages: skills and prompts found in ~/.tau or the project can be switched off the same way, by naming them in settings with a "-" or "!".

func PackageIdent 

func PackageIdent(packageRoot string) (name, version string)

PackageIdent reads a package's declared name and version, for listings.

func SplitEntries 

func SplitEntries(entries []string) (paths, patterns []string)

SplitEntries separates plain resource paths from enable/disable patterns, so a settings list can hold both.

Types

type Entry 

type Entry struct {
	Source string `json:"source"`
	// Autoload false means nothing is loaded unless a pattern names it.
	Autoload *bool `json:"autoload,omitempty"`

	Extensions []string `json:"extensions,omitempty"`
	Skills     []string `json:"skills,omitempty"`
	Prompts    []string `json:"prompts,omitempty"`
	Themes     []string `json:"themes,omitempty"`
}

Entry is a package as named in settings: either a bare source string or an object that also says which of the package's resources to use.

func ParseEntries 

func ParseEntries(raws []json.RawMessage) ([]Entry, []string)

ParseEntries reads a settings packages list, returning the entries it could parse and a warning for each it could not. One malformed entry must not cost the user every other package they configured.

func ParseEntry 

func ParseEntry(raw json.RawMessage) (Entry, error)

ParseEntry reads a settings package entry in either form.

func (Entry) Patterns 

func (e Entry) Patterns(t ResourceType) ([]string, bool)

Patterns returns the entry's filter for one resource type, and whether the entry mentioned that type at all.

type Installed 

type Installed struct {
	Source  string
	Kind    Kind
	Scope   Scope
	Path    string
	Name    string
	Version string
}

Installed describes a package found on disk.

type Kind 

type Kind string

Kind is how a source is fetched. 

const (
	// KindNPM is an npm package, installed with npm into a managed prefix.
	KindNPM Kind = "npm"
	// KindGit is a git repository, cloned into a managed directory.
	KindGit Kind = "git"
	// KindLocal is a directory already on disk, used where it lies.
	KindLocal Kind = "local"
)

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager installs packages and resolves the resources they provide.

func New 

func New(opts Options) *Manager

New builds a Manager.

func (*Manager) Install 

func (m *Manager) Install(ctx context.Context, source string, scope Scope) (Source, string, error)

Install fetches a package and returns where it landed.

func (*Manager) InstallRoot 

func (m *Manager) InstallRoot(kind Kind, scope Scope) (string, error)

InstallRoot is the directory a source's packages live under.

func (*Manager) List 

func (m *Manager) List(scope Scope) ([]Installed, error)

List returns the packages installed in a scope, whether or not settings mention them — so a package installed and then unconfigured is still visible and can still be removed.

func (*Manager) PackagePath 

func (m *Manager) PackagePath(src Source, scope Scope) (string, error)

PackagePath is where a source's contents end up on disk.

A local source is not copied — it is used where it lies, so that editing a package under development takes effect without reinstalling it.

func (*Manager) Remove 

func (m *Manager) Remove(ctx context.Context, source string, scope Scope) error

Remove deletes an installed package. A local source is never deleted — tau did not put it there, and removing it means removing the user's own work.

func (*Manager) Resolve 

func (m *Manager) Resolve(entries []Entry, scope Scope) Resolution

Resolve turns configured package entries into resource paths.

Entries are resolved in the order given, project scope before user scope, so that a project's choice of package wins a collision — the same precedence the rest of tau's settings use.

func (*Manager) Update 

func (m *Manager) Update(ctx context.Context, source string, scope Scope) (bool, error)

Update refetches an installed package. A pinned source is left alone: the user asked for that exact version, and quietly moving it would be a lie.

type Manifest 

type Manifest struct {
	Extensions []string `json:"extensions,omitempty"`
	Skills     []string `json:"skills,omitempty"`
	Prompts    []string `json:"prompts,omitempty"`
	Themes     []string `json:"themes,omitempty"`
}

Manifest is the resource declaration inside a package's package.json.

Each field lists source entries — paths or globs relative to the package root — optionally mixed with the override forms from pattern.go, which let a package ship something disabled by default.

func ReadManifest 

func ReadManifest(packageRoot string) *Manifest

ReadManifest returns a package's resource declaration, or nil if it has none. A package.json that is missing, unreadable, or malformed yields nil rather than an error: the package still works by convention, and refusing to load a whole package over a stray comma would be worse than ignoring the file.

func (*Manifest) Empty 

func (m *Manifest) Empty() bool

Empty reports that the manifest declares nothing at all, which is treated the same as having no manifest.

func (*Manifest) Entries 

func (m *Manifest) Entries(t ResourceType) ([]string, bool)

Entries returns the manifest's declaration for one resource type. The second result distinguishes "declared as empty" from "not declared", which decide different things: an empty list ships nothing, an absent one falls back to the conventional directory.

type Options 

type Options struct {
	// AgentDir is the user-scope root (~/.tau/agent).
	AgentDir string
	// Cwd is the project directory; ProjectDir is its .tau.
	Cwd string
	// ProjectTrusted gates every project-scoped operation. Installing into a
	// repository writes into it and running its packages executes its code,
	// so an untrusted checkout gets neither.
	ProjectTrusted bool
	// Run executes npm and git; nil means run them for real.
	Run Runner
}

Options configures a Manager.

type Resolution 

type Resolution struct {
	Resources []Resource
	Warnings  []string
}

Resolution is everything the configured packages provide.

func (Resolution) Enabled 

func (r Resolution) Enabled(t ResourceType) []string

Enabled returns the enabled paths of one type, in resolution order.

type Resource 

type Resource struct {
	Path     string
	Type     ResourceType
	Enabled  bool
	Package  string // the source string, for diagnostics
	Root     string // the package directory the path is relative to
	Scope    Scope
	Priority int // lower wins on a name collision
}

Resource is one file a package provides.

type ResourceType 

type ResourceType string

ResourceType is a kind of resource a package can provide. 

const (
	TypeExtensions ResourceType = "extensions"
	TypeSkills     ResourceType = "skills"
	TypePrompts    ResourceType = "prompts"
	TypeThemes     ResourceType = "themes"
)

type Runner 

type Runner func(ctx context.Context, dir, name string, args ...string) (string, error)

Runner executes an external command. It exists so tests can drive the manager without npm or git installed.

type Scope 

type Scope string

Scope is where a package is installed: for the user, or for one project. 

const (
	ScopeUser    Scope = "user"
	ScopeProject Scope = "project"
)

type Source 

type Source struct {
	Kind Kind
	// Raw is the string the user wrote, kept verbatim so settings round-trip.
	Raw string

	// Spec, Name and Version describe an npm source. Spec is what npm is
	// asked to install ("pkg@^1.2.0"); Name is the bare package name, which
	// is also the directory it lands in.
	Spec    string
	Name    string
	Version string

	// Repo, Host, Path and Ref describe a git source. Repo is a URL git can
	// clone; Host and Path decide where the clone lands.
	Repo string
	Host string
	Path string
	Ref  string

	// LocalPath is the directory of a local source, as written.
	LocalPath string

	// Pinned reports that the source names an exact version or ref, so
	// updating it would contradict what the user asked for.
	Pinned bool
}

Source is a parsed package source.

func ParseGitURL 

func ParseGitURL(source string) (Source, bool)

ParseGitURL parses a git source, returning false if the string is not one.

With a "git:" prefix, shorthand is accepted: host/owner/repo and git@host:… as well as full URLs. Without one, only an explicit scheme counts, because "some/path" has to stay a directory rather than silently becoming a clone of somebody's repository.

A ref may be appended as "@ref" or "#ref". Pi resolves shorthand through hosted-git-info, which additionally knows a handful of host aliases; tau covers the aliases it documents (github:, gitlab:, bitbucket:) and otherwise requires a real hostname. The cost of the gap is that an undocumented alias is treated as a path, which fails loudly at install time rather than quietly fetching the wrong thing.

func ParseSource 

func ParseSource(s string) Source

ParseSource classifies a package source string.

The rules are Pi's: an "npm:" prefix is npm, an obvious filesystem path is local, a parseable git URL is git, and anything left over is local. The last case is deliberate — a bare name that is not a URL is far more likely to be a mistyped directory than a repository nobody can reach.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.