pigdocs

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package pigdocs materializes the reference documentation embedded in Stock Pig under the user's config root.

Pig ships as a standalone binary. Unlike upstream Pi, which installs package documentation beside its npm entry point, Pig cannot assume that a source checkout exists. The embedded bundle lets the running agent inspect the exact extension, Package, and Piglet contracts that its binary implements.

Each build writes its bundle to its own content-addressed directory, so PiG builds that share a config root (two installed versions, or stock PiG beside a Piglet Binary) never rewrite each other's docs, and a running session's docs never change under it. Users can also force a sync or read the bundle through `pig docs`. A session leases its bundle (HoldBundle), so another build's eviction never removes the pages the session's prompt names. This is stock distribution infrastructure; it does not activate an extension or optional Piglet.

Output layout

~/.pig/docs/
  bundle-<hash>/       one build's bundle; <hash> is its content digest
    README.md          index
    commands.md        slash commands + CLI verbs
    ...                one page per embedded content/*.md
    .pig-docs-digest   the full digest, written last

Index

Constants

View Source
const (

	// SubDir is the docs directory name under the pig config root.
	SubDir = "docs"
)

Variables

This section is empty.

Functions

func DocsDir

func DocsDir(configRoot string) string

DocsDir returns the absolute directory of this build's bundle for a given config root.

func EnsureSynced

func EnsureSynced(configRoot string) error

EnsureSynced is the idempotent startup helper. A complete bundle of this build costs one marker read and, at most hourly, a recorded use time; otherwise it syncs. All errors are returned to the caller; Pig core treats any failure as the bundle being absent.

func HoldBundle

func HoldBundle(configRoot string) (release func())

HoldBundle leases this build's bundle in configRoot for as long as the process lives, so another build's eviction does not remove the pages a running session's prompt names. It does nothing when the bundle is not complete on disk, and nothing is written. A session does not call the returned release until it exits (the exit path calls it just before the exit record counts descriptors) and tests call it. The bundle is read again once leased, so an eviction between the check and the lease is not mistaken for a held bundle. pig additive (D22): Pi's package docs stay where they are for as long as Pi runs; PiG's bundle lives in a directory that other builds evict.

func List

func List() []string

List returns the embedded doc filenames in stable alphabetical order. It is the canonical source for `pig docs list` and for any caller that needs to enumerate available topics.

func Prepare

func Prepare(configRoot string) (present, pending bool, err error)

Prepare is the startup check that defers the write of the bundle until something can read it. It returns present, whether text may name the bundle, and pending, whether EnsureSynced must run before anything other than PiG reads it. A complete bundle of this build costs one marker read and, at most hourly, a recorded use time; it is present and nothing is pending. Otherwise the bundle is named when the config root lets this process create it, the condition under which EnsureSynced writes it; nothing is written here. pig additive (D22): Pi's package docs exist before it starts; PiG writes its bundle before the first reader instead of at every start.

func Read

func Read(name string) ([]byte, error)

Read returns the embedded bytes of a single doc file. Names may be given with or without the .md suffix; ".." and absolute paths are rejected so this is safe to drive from CLI input.

func RunCommand

func RunCommand(args []string, stdout, stderr io.Writer) int

RunCommand implements the stock pre-session `pig docs` command. It returns -1 when the arguments target another command.

pig docs                       sync + summary (default)
pig docs sync                  force re-sync embedded docs
pig docs path                  print docs dir
pig docs list                  list available doc files
pig docs show <name>           print one doc to stdout

func Sync

func Sync(configRoot string) ([]string, error)

Sync writes this build's bundle directory from the embedded docs, replacing a directory already there, and returns the page names written. `pig docs sync` uses it to repair edited or removed pages.

Types

This section is empty.

Jump to

Keyboard shortcuts

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