ship

package
v0.7.51 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package ship lays a knowledge pack into a QuickAgent's package so the release carries it: the pack's files under knowledge/<name>/ with the manifest.json the registry holds a shipped pack to, the entry in the package's knowledge.ships and the patterns of publish.include that put it in the archive, and the sidecar that records where the pack was laid down from.

A shipped pack is part of the release. Everyone who can download the release can read it, so the commands that ship one ask the publisher to confirm it, and the confirmation names each pack with the origin laid down here (Entry.Origin) for the registry to check against its own records.

Index

Constants

The most a release ships: packs, and the size and files of each, as the registry holds them.

View Source
const (
	KindOwn = "own"
	KindOrg = "org"
)

The kinds of store a shipped pack is laid down from.

View Source
const IncludeAll = manifest.KnowledgeDir + "/**"

IncludeAll is the publish.include pattern that puts every shipped pack in the archive.

View Source
const RecordFile = ".agentry/knowledge-ships.json"

RecordFile is the sidecar, relative to the package, that remembers where each shipped pack was laid down from. It is not part of the manifest and not part of the release: publish.include never names it.

View Source
const RecordSchema = "knowledge-ships/v1"

RecordSchema is the sidecar's format.

Variables

View Source
var ErrPastCap = errors.New("knowledge pack is past what a release ships")

ErrPastCap is a pack past what a release may ship.

Functions

func Check

func Check(p *knowledge.Pack) error

Check holds a pack to what a release may ship, before anything is written: at most 10 MB with its manifest.json and 2,000 files.

func Covers

func Covers(include []string, name string) bool

Covers says whether the include patterns put a pack's files in the archive: its manifest.json and its index.

func Dir

func Dir(agentDir, name string) string

Dir is the pack's folder in a package.

func DirSize

func DirSize(agentDir, name string) (bytes int64, files int, err error)

DirSize is the bytes and files of everything under a shipped pack's folder, as the archive will carry it.

func Names

func Names(packs []Pack) []string

Names are the packs the entries name, in order.

func Remove

func Remove(agentDir, name string) error

Remove takes the pack's folder out of the package. A pack that is not there is not an error.

func Ships

func Ships(agentYAML []byte) ([]string, error)

Ships are the names agent.yaml's knowledge.ships lists.

func WriteRecord

func WriteRecord(agentDir string, r Record) error

WriteRecord writes the sidecar, or removes it when no pack is left.

Types

type Edit

type Edit struct {
	YAML []byte
	Did  []string
}

Edit is a change to a package's agent.yaml and what it did, one plain sentence each.

func AddShip

func AddShip(agentYAML []byte, name string) (Edit, error)

AddShip puts the pack's name in agent.yaml's knowledge.ships and the pattern that puts knowledge/ in the archive in publish.include, when they are not there. The rest of the file is kept as written.

func RemoveShip

func RemoveShip(agentYAML []byte, name string) (Edit, error)

RemoveShip takes the pack's name out of knowledge.ships. A block left with nothing to say goes with it, and so does the knowledge/** pattern once no pack is shipped.

type Entry

type Entry struct {
	Name string `json:"name"`
	// SHA256 is the tree digest that was laid down. The origin is claimed
	// only while the pack's manifest.json still says it.
	SHA256 string `json:"sha256"`
	// Registry is the registry the origin's pack id belongs to.
	Registry string  `json:"registry,omitempty"`
	Origin   *Origin `json:"origin,omitempty"`
}

Entry is the sidecar's record of one shipped pack.

type Laid

type Laid struct {
	Name  string
	Pages int
	// Bytes is every file of the pack, its manifest.json included, as the
	// registry counts it against the 10 MB a pack may be.
	Bytes int64
	// Files is the files of the pack's tree, as the registry counts them
	// against the 2,000 a pack may hold.
	Files int
	// SHA256 is the tree's digest, the one in the pack's manifest.json.
	SHA256 string
}

Laid is a pack as it now stands under knowledge/<name>/.

func Lay

func Lay(agentDir string, p *knowledge.Pack) (Laid, error)

Lay puts the verified pack p under agentDir/knowledge/<name>/, replacing what is there: its tree, and a manifest.json the registry accepts. The pack is written beside its place and moved in whole, so a refusal leaves the folder as it was. It refuses a pack past what a release ships.

func (Laid) String

func (l Laid) String() string

String names a laid pack for the person: its pages and its size.

type Origin

type Origin struct {
	Kind   string `json:"kind"`
	Org    string `json:"org,omitempty"`
	PackID string `json:"packId"`
}

Origin is the stored pack in a registry that a shipped pack was laid down from: the claim the publish confirmation carries, which the registry checks (the pack exists and is ready, it is the publisher's own or the organization's, and its digest is the shipped pack's).

func OriginOf

func OriginOf(agentDir string, r Record, name, reg string) (*Origin, string)

OriginOf is the origin to claim for the shipped pack of that name when the package is published to the registry at reg, or why none is claimed: it belongs to another registry, or the pack's manifest.json is no longer the one that was laid down (the pack was replaced or edited by hand). A pack with no origin is sent as the publisher's own files, and the reason is empty when the sidecar never recorded one.

type Pack

type Pack struct {
	Name   string  `json:"name"`
	Origin *Origin `json:"origin,omitempty"`
}

Pack is one shipped pack as the publish confirmation names it: its name and, when it was laid down from a stored pack, the origin. A pack with no origin is the publisher's own files.

type Record

type Record struct {
	Schema string  `json:"schema"`
	Packs  []Entry `json:"packs"`
}

Record is the sidecar.

func ReadRecord

func ReadRecord(agentDir string) (Record, error)

ReadRecord reads the package's sidecar: an empty record when there is none.

func (Record) Find

func (r Record) Find(name string) (Entry, bool)

Find is the entry of that name.

func (*Record) Remove

func (r *Record) Remove(name string)

Remove forgets the pack of that name.

func (*Record) Set

func (r *Record) Set(e Entry)

Set records e, replacing the entry of its name.

Jump to

Keyboard shortcuts

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