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 ¶
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 PinNpmSource ¶ added in v0.6.0
PinNpmSource applies an explicit --pieces-version to an npm: source. It refuses a non-npm source (a dir or URL has no version to pin) and a source that already carries a pin (two pins is a contradiction, not a merge).
func RenderSummary ¶
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 ¶
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. For the npm
// fetcher it is the CONFIGURED spec until the first successful Fetch resolves
// a release, and the fully pinned npm:<pkg>@<version> afterwards — so a caller
// recording it must read it AFTER fetching (Add does).
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 ¶
NewFetcher returns the Fetcher for a resolved source: an npm:<pkg>[@version] spec gets the versioned npm fetcher, an http(s) URL prefix the network fetcher, anything else a local directory path.
type FileWrite ¶
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"`
// Puzzle is the compiler version that performed the last add — with the
// resolved registry coordinates it makes a bug report's provenance exact.
Puzzle string `json:"puzzle,omitempty"`
Pieces map[string]LockEntry `json:"pieces"`
}
Lock is the pieces.lock document. Field order here is the emitted key order (version, registry, puzzle, pieces); map keys marshal sorted, giving a stable, diff-friendly file.
type LockEntry ¶
LockEntry records a piece's (or lib's) copied files: app-root-relative slash path → "sha256:<hex>".
type Options ¶
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 ¶
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.