Documentation
¶
Overview ¶
Package deploy plans and executes writ deployments on the sealed graph model (phase-8 step 47 slice 1).
A deployment walks the layered source tree (base → team → personal, segment/platform variants, cross-layer collision resolution — all owned by the tree package), plans one immutable graph per target scope through plan.Provider (file links, template render chains, sops decrypts, and manifest-resolved package units), and executes each graph under a confined root. The plan persists once via cli.WriteGraph; every run's trace persists via cli.WriteTrace win or lose; both writes append to the store's run index. The graph's origin annotations carry the writ metadata bag — including the per-unit file inventory the readback package folds.
Index ¶
- func CommonAncestor(a, b string) string
- func Execute(ctx context.Context, cfg *Config) (graphs []*op.Graph, err error)
- func PlanFileChain(provider *plan.Provider, f *tree.FileEntry, data map[string]any) (*op.Invocation, string, error)
- func PlanSpacePath(runtimeEnvironment *op.RuntimeEnvironment, abs string) (string, error)
- func RenderData(segments segment.Segments, vars map[string]any) map[string]any
- type BuildResult
- type Config
- type PinInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CommonAncestor ¶
CommonAncestor returns the deepest directory containing both `a` and `b`.
Parameters:
- `a`: the first absolute path.
- `b`: the second absolute path.
Returns:
- `string`: the deepest common ancestor directory.
func Execute ¶
Execute runs the full deploy operation: pin layers, build the per-scope graphs, and execute them.
Multi-source mode pins every layer source to a git-worktree snapshot before planning (refusing dirty layers unless `AllowDirty`); the pin's commit hashes ride the graphs' origin annotations. Dry-run serializes the planned graphs to stdout and stops. Execution is fail-forward across scopes — System first, then Home — with each graph persisted via cli.WriteGraph before its run and each run's trace persisted via cli.WriteTrace win or lose.
Parameters:
- `ctx`: the cancellation context for planning and execution.
- `cfg`: the resolved deploy configuration.
Returns:
- `graphs`: the plan, under --dry-run; nil when the run executed (or there was nothing to do).
- `err`: non-nil when pinning or planning fails, or when one or more scopes fail to execute.
func PlanFileChain ¶
func PlanFileChain(provider *plan.Provider, f *tree.FileEntry, data map[string]any) (*op.Invocation, string, error)
PlanFileChain plans one file entry's pipeline and returns the target-producing invocation.
Exported as the family's shared chain seam: upgrade re-plans copied entries through the same pipelines. The tree's pipelines map onto the sealed actions as: `[file.link]` → one `file.link`; `[encryption.decrypt, file.copy]` → one `encryption.decrypt_sops_file` (the decrypt is compound — it reads, decrypts, and writes 0600); `[template.render_bytes, file.copy]` → `file.read_text` → `template.render_text` → `file.write_text` (promise-chained); the decrypt+render pipeline decrypts to the target, then reads the decrypt's product, renders, and rewrites it 0600.
Parameters:
- `provider`: the plan provider to register invocations into.
- `f`: the tree entry to plan.
- `data`: the template data map for render chains.
Returns:
- `*op.Invocation`: the final, target-producing invocation (the readback correlates on its unit ID).
- `string`: the final invocation's action name.
- `error`: non-nil when the pipeline is unknown or a planning call fails.
func PlanSpacePath ¶
func PlanSpacePath(runtimeEnvironment *op.RuntimeEnvironment, abs string) (string, error)
PlanSpacePath renders the machine-absolute `abs` in plan space: the slash-canonical rel against the planning environment's root.
writ's planners choose their run root as the common ancestor of every involved path ([runRootFor] and the per-command equivalents), so a path outside the root is a planning defect, not an input case.
Parameters:
- `runtimeEnvironment`: the planning environment; its root is the run root the rel binds to.
- `abs`: the machine-absolute path to render.
Returns:
- `string`: the slash-canonical rel.
- `error`: non-nil when `abs` cannot be made relative to the root, or escapes it.
func RenderData ¶
RenderData assembles the render-chain data map: the builtin platform/user/XDG values overlaid with the user-configured variables.
Exported as the family's shared data seam: upgrade builds the same map for its re-planned chains.
Parameters:
- `segments`: the segments projected into `.Segments`.
- `vars`: the user-configured variables, merged over the builtins.
Returns:
- `map[string]any`: the merged template data.
Types ¶
type BuildResult ¶
type BuildResult struct {
// Graphs holds one assembled, immutable graph per populated target scope.
Graphs []*op.Graph
// Collisions are the cross-layer/specificity conflicts the tree build resolved.
Collisions []tree.Collision
}
BuildResult is the outcome of planning.
One graph per populated target scope, plus the tree's collision report for command-layer presentation.
func BuildGraphs ¶
BuildGraphs walks the source tree and plans one immutable graph per populated target scope.
Single-source mode (no layer sources) yields one unscoped graph against `cfg.TargetRoot`. Multi-source mode partitions the tree's winning entries by target scope ("System" / "Home") and yields one graph per populated scope, each against its own target root. Each graph's origin annotations carry the writ metadata bag — source and target roots, projects, segments, layers, the pin's commit hashes and dirty layers, the run root, and the per-unit file inventory (`files`) the readback package folds.
Parameters:
- `ctx`: the planning context.
- `cfg`: the resolved deploy configuration.
- `pin`: the layer-pinning results; zero-valued in single-source mode.
Returns:
- `*BuildResult`: the per-scope graphs and the collision report.
- `error`: non-nil when the tree build or any scope's planning fails.
type Config ¶
type Config struct {
// SourceRoot is the source directory for single-source mode; ignored when LayerSources is populated.
SourceRoot string
// TargetRoot is the target directory for single-source mode (e.g. $HOME).
TargetRoot string
// LayerSources are the layer sources for multi-source mode; each carries its own target scope and root.
LayerSources []tree.LayerSource
// Projects selects the projects to deploy (e.g. ["all", "noblefactor"]).
Projects []string
// Segments are the platform/custom segments for variant matching and template data.
Segments segment.Segments
// Vars are the user-configured template variables, merged over the builtin template data.
Vars map[string]any
// Conflict is the occupied-target policy (phase-8 step 49). The zero value is [op.ConflictStop] — the
// ruled default: the pre-flight refuses foreign or locally-modified occupants (naming them and this flag)
// while writ's own unmodified outputs are cleared for replacement, so redeploys flow. `skip` and `replace`
// hand the per-target decision to the file provider's write seam.
Conflict op.ConflictPolicy
// ManifestPlanner resolves packages-manifest files into package units; nil skips manifest resolution
// with a note.
ManifestPlanner *lore.Planner
// AllowDirty permits planning against layers with uncommitted changes.
AllowDirty bool
// DryRun serializes the planned graphs to stdout instead of executing them.
DryRun bool
// Verbose narrates planning context and per-run receipts via [cli.Note].
Verbose bool
}
Config carries the resolved settings for one deploy operation.
type PinInfo ¶
type PinInfo struct {
// CommitHashes maps each pinned layer to the commit hash its snapshot was taken at.
CommitHashes map[string]string
// DirtyLayers names the layers that had uncommitted changes at pin time (planning proceeded under
// --allow-dirty).
DirtyLayers []string
}
PinInfo carries the layer-pinning results that ride the graphs' origin annotations.
Source Files