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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildGraph ¶
BuildGraph constructs the batch adopt graph for one scope group (phase-8 step 33 slice A).
Shape (the settled gather + field-projection design): a deduplicated `file.mkdir` pre-stage — one node per unique destination directory, ahead of the gather because concurrent per-item creation of a shared directory would be same-resource production — followed by one `flow.gather` over the item records. Each iteration runs the in-graph destination guard and the adoption chain, all slots projected from the iteration item (plan.Provider.Item):
gather items=[{source, dest_path}, …] limit=4
└── choose( file.exists(dest_path) → flow.failed | default: file.move → file.link )
Failure follows the policies as defined: a failed adoption fails the run, the executor unwinds, and completed iterations compensate (links removed, moves reversed, created directories pruned).
Parameters:
- `env`: the planning runtime environment; supplies the receiver registry for provider-method lookup.
- `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 trace as the receipt.
Groups run in deterministic (sorted-root) order. Each group plans once (BuildGraph) and runs once; the trace persists via cli.WriteTrace 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 planning, preflight, or a run fails.
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
// LayerPath is the resolved path to the layer directory.
LayerPath string
// Project is the origin name within the layer.
Project 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.
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
}
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