Documentation
¶
Overview ¶
Package adopt plans the `writ adopt` batch graph.
The cobra layer (`cmd/writ/writ/adopt_cmd.go`) enumerates the inputs — the locations of the files to adopt — into per-scope Item batches; BuildGraph turns one batch into one execution graph: a deduplicated mkdir pre-stage plus a `flow.gather` over the item records whose body guards and performs each adoption via field projections (the writ-adopt design, docs/plans/extract-starlark-from-op/phase-8/writ-adopt-command.md; phase-8 step 33 slice A on the step-45 projection surface).
Index ¶
- func BuildGraph(env *op.RuntimeEnvironment, cfg *Config, targetRoot string, items []Item) (*op.Graph, error)
- func Collect(cfg *Config) map[string][]Item
- func RunBatches(ctx context.Context, cfg *Config, groups map[string][]Item) (int, error)
- func ValidatePlatform(platform string) error
- type Config
- type Item
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildGraph ¶
func BuildGraph(env *op.RuntimeEnvironment, cfg *Config, targetRoot string, items []Item) (*op.Graph, error)
BuildGraph constructs the batch adopt graph for one scope group.
Shape (ruled 2026-09-23, #931, superseding the gather of the writ-adopt design): a deduplicated `file.mkdir` pre-stage -- one node per unique destination directory -- followed by **one chain per item**, so every adopted file has its own `file.link` unit and the graph's `files` annotation can name it, as a deploy's does:
mkdir₁ … mkdir_k per item: file.move → file.link (the existing-destination guard runs before the graph, in RunBatches)
The origin is a deployment record's: tool `writ`, the scope, `target_root`, and `files` keyed by each link unit's id with the target (the original location, now the link), the source (the project location, which is also what the run read), the action, the layer and the project. The fold reads an adoption as it reads a deploy.
Failure follows the policies as defined: a failed adoption fails the run, the executor unwinds, and completed items compensate (links removed, moves reversed, created directories pruned).
Parameters:
- `env`: the planning runtime environment; supplies the receiver registry for provider-method lookup.
- `cfg`: the adopt configuration; the layer and the project the record names.
- `targetRoot`: the scope's root, the annotation's `target_root`.
- `items`: the scope group's adoptions, destinations already derived.
Returns:
- *op.Graph: the assembled batch graph.
- `error`: non-nil when planning any invocation or the assembly fails.
func Collect ¶
Collect enumerates the configured files into per-scope adoption batches.
Enumeration is intent, not framework work: paths expand and absolutize, missing items report per-item errors, existing symlinks warn and skip, directories walk recursively, and each surviving file derives its destinations (Item) from its inferred scope. Under dry-run the would-do steps narrate here; nothing touches the filesystem in either mode.
Parameters:
- `cfg`: the adopt configuration.
Returns:
- map[string][]Item: the batches keyed by scope root (`cfg.TargetRoot` for Home, "/" for System).
func RunBatches ¶
RunBatches executes one adopt graph per scope group and persists each run's graph and trace as the record.
Groups run in deterministic (sorted-root) order. An occupied destination anywhere refuses the whole batch before a file moves. Each group plans once (BuildGraph) and runs once ([runBatch]); the trace persists into the current lifetime success or failure (a failed run's journal survives — the step-21 R4 stance). Per-file "Adopted" lines report post-run (the settled reporting ruling). A failed run stops the remaining groups.
Parameters:
- `ctx`: the cancellation context for the runs.
- `cfg`: the adopt configuration.
- `groups`: the per-scope batches from Collect.
Returns:
- `int`: the number of files adopted by the groups that completed.
- `error`: non-nil when there is no current deployment (66), a destination is occupied, or planning, persisting or a run fails.
func ValidatePlatform ¶
ValidatePlatform checks a `--platform` value against the segment vocabulary the layer tree matches on this platform (#931, ruled 2026-09-23: the segment vocabulary, not the lore token): each dotted part must be a value the detected segments carry -- the OS (`Darwin`, `Linux`, `Windows`), its family (`Unix`), the distro, the architecture -- so a suffix the deploy walk would never read cannot be minted.
Parameters:
- `platform`: the flag's value; "" is valid and means the platform-neutral directory.
Returns:
- `error`: non-nil, naming the vocabulary, when a part is not one the matcher knows here.
Types ¶
type Config ¶
type Config struct {
// Files are the items to adopt, as the user supplied them (files or directories; `~` expands).
Files []string
// TargetRoot is the Home scope's root (the user's home directory).
TargetRoot string
// Layer is the layer's name (personal, team, base); the record names it.
Layer string
// LayerPath is the resolved path to the layer directory.
LayerPath string
// Project is the origin name within the layer.
Project string
// Platform is the segment suffix the adopted files carry (#931): the project directory becomes
// `<project>.<Platform>`; "" is the platform-neutral directory.
Platform string
// Verbose narrates per-item progress.
Verbose bool
// DryRun narrates the would-do steps during enumeration; nothing is built or run.
DryRun bool
}
Config carries the adopt run's inputs from the cobra layer.
func (*Config) ProjectDirectory ¶
ProjectDirectory returns the project directory's name within a scope: the project, suffixed by the platform when one is named (#931): `noblefactor-ops`, `noblefactor-ops.Linux.Debian`.
Returns:
- `string`: the directory name the layer tree matches.
type Item ¶
type Item struct {
// Source is the absolute path of the file being adopted (the live location; the symlink lands here).
Source string
// RelPath is Source relative to the scope's target root — display/reporting only.
RelPath string
// DestDir is the destination directory (the parent of DestPath), created by the mkdir pre-stage.
DestDir string
// DestPath is the destination inside `<layer>/<scope>/<project>/`, preserving RelPath.
DestPath string
// Scope is the scope the item was inferred into (Home or System); the record names it.
Scope string
}
Item describes one file adoption: the source location and its plan-time-derived destinations.
The inputs to `writ adopt` are the locations of the files to adopt; the tool derives each location's destination path and directory at plan time and feeds the batch to BuildGraph (the writ-adopt design, docs/plans/extract-starlark-from-op/phase-8/writ-adopt-command.md).
Source Files