pieces

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Jul 28, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package pieces implements `puzzle add piece <name…>`: copying copy-in UI components ("pieces") out of a registry into a Puzzle app. Pieces are copied VERBATIM — the Go side never stamps, rewrites, or reformats a piece's bytes (that is the D3 print-don't-rewrite boundary the whole CLI honors). Instead of mutating copied files, we record a sha256 of every copied byte in pieces.lock, so a future diff/update command can tell "upstream changed" from "the user customized it locally" from "both" without ever having touched user content.

Index

Constants

View Source
const LockFileName = "pieces.lock"

LockFileName is the per-app manifest recording exactly which pieces were copied in and the sha256 of each copied file. It exists so a future diff/update command can distinguish upstream drift from local edits — the reason we copy verbatim instead of stamping.

Variables

This section is empty.

Functions

func RenderSummary

func RenderSummary(w io.Writer, out *ui.Printer, res *Result)

RenderSummary prints the copy report and next steps through the CLI's Printer, matching the init/add aesthetic (a header, one ✓ line per unit, a Next steps block). Lib deps get their own ✓ line so a shared util is shown once.

func ResolveSource

func ResolveSource(flag string) string

ResolveSource picks the registry source by the documented precedence: the --registry flag, then $PUZZLE_PIECES_REGISTRY, then the public default.

Types

type Fetcher

type Fetcher interface {
	// Fetch returns the bytes at rel, or an error naming the concrete location
	// (path or URL) that failed — the user needs to know WHERE we looked.
	Fetch(rel string) ([]byte, error)
	// Source is the canonical source string recorded verbatim in pieces.lock so
	// a later diff/update knows which registry a piece came from.
	Source() string
	// Ref renders rel as a human-readable location for advisories (the theme
	// merge hint) — a full path for a dir source, a full URL for an http one.
	Ref(rel string) string
}

Fetcher reads registry resources by their registry-relative slash path ("registry.json", "ui/button/Button.pzl", "lib/date-math.js"). It abstracts the two source shapes — a local directory on disk and an http(s) URL prefix — so Add is oblivious to where bytes come from and tests can drive a temp dir or an httptest.Server through the identical code path.

func NewFetcher

func NewFetcher(source string) Fetcher

NewFetcher returns the Fetcher for a resolved source: an http(s) URL prefix gets the network fetcher, anything else is treated as a local directory path.

type FileWrite

type FileWrite struct {
	Rel  string
	Abs  string
	Hash string
}

FileWrite is one copied file in the Result: its app-root-relative slash path, absolute path, and recorded hash.

type Lock

type Lock struct {
	Version  int                  `json:"version"`
	Registry string               `json:"registry"`
	Pieces   map[string]LockEntry `json:"pieces"`
}

Lock is the pieces.lock document. Field order here is the emitted key order (version, registry, pieces); map keys marshal sorted, giving a stable, diff-friendly file.

type LockEntry

type LockEntry struct {
	Files map[string]string `json:"files"`
}

LockEntry records a piece's (or lib's) copied files: app-root-relative slash path → "sha256:<hex>".

type Options

type Options struct {
	AppRoot   string
	Names     []string
	Fetcher   Fetcher
	Overwrite bool
}

Options configures one `add piece` run. AppRoot is already resolved (the cmd layer walks up for package.json/puzzle.config.js) and Fetcher is already bound to a source, so this package does no path walking or source selection.

type Piece

type Piece struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Files       []string `json:"files"`
	// RegistryDependencies is a mixed list: a bare name ("calendar") is another
	// PIECE; a "lib/…"-prefixed value ("lib/date-math.js") is a shared JS util
	// copied to app/lib/. The prefix is the ONLY discriminator (see resolveAll).
	RegistryDependencies []string `json:"registryDependencies"`
	// Dependencies are npm package names the piece needs at runtime. We never run
	// npm (D3) — they are accumulated and printed as a next step.
	Dependencies []string `json:"dependencies"`
	// TargetDir is the app-relative destination for this piece's files; empty
	// means the default (app/components/ui).
	TargetDir string `json:"targetDir"`
}

Piece is one registry entry.

type Registry

type Registry struct {
	Version int     `json:"version"`
	Theme   string  `json:"theme"`
	Pieces  []Piece `json:"pieces"`
}

Registry is the parsed registry.json index.

type Result

type Result struct {
	AppRoot  string
	Source   string
	Units    []Unit
	NpmDeps  []string // deduped + sorted; never installed (D3)
	Theme    string   // non-empty ⇒ the `@import './pieces.css';` next-step advisory
	LockPath string
}

Result reports what Add copied and what the user still has to do by hand.

func Add

func Add(opts Options) (*Result, error)

Add resolves the requested pieces (with transitive deps), copies every file verbatim into AppRoot, records hashes in pieces.lock, and returns the next steps (npm install line, theme import advisory) for the caller to print. It is all-or-nothing on conflicts: if any destination exists and Overwrite is false, nothing is written.

type Unit

type Unit struct {
	Name  string
	IsLib bool
	Files []FileWrite
}

Unit groups the files copied for one piece or one lib dep. Name is the piece name ("button") or the lib registry path ("lib/date-math.js") — the same key used in pieces.lock.

Jump to

Keyboard shortcuts

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