Manifest reference — migration-machine

Shape

{
  "name": "Human-readable name",
  "description": "Optional notes.",
  "config": { ... },
  "steps": [ ... ]
}

config

A flat object of string values. Each key is exported to step scripts as CFG_<UPPERCASE_KEY>. Keys used by the shipped steps:

Key	Used by	Meaning
`packageManager`	package-manager, packages	`brew` or `port`
`dotfilesRepo`	dotfiles	git URL to clone (SSH for private submodules)
`dotfilesCloneDir`	dotfiles	clone path relative to `$HOME`
`dotfilesInstall`	dotfiles	installer command run inside the repo
`commitMonoUrl`	dotfiles	optional font zip staged before install
`brewfile`	packages	Brewfile path relative to the data dir
`portfile`	packages	port list path relative to the data dir
`macportsPkgUrl`	package-manager	`.pkg` URL for your macOS version
`secretsDmg`	secrets	encrypted bundle path relative to the data dir
`extraDefaults`	macos-defaults	optional extra `defaults` script path

Add your own keys; they become CFG_* for any custom step you write.

steps

An ordered array. Each step:

Field	Req	Meaning
`id`	yes	stable identifier, used by `--only`
`title`	yes	shown in the progress UI
`subtitle`	no	shown under the title in the GUI
`run`	yes	path to the step script, relative to the repo root
`validation`	no	shell expression run with `bash -c`. Passes before → step is skipped. Empty → always run.
`required`	no	`true` aborts the run on failure; otherwise warn and continue

Execution model

For each step the engine:

Skips it if --only is set to a different id.
Runs validation. If it passes, the step is "Already set" and skipped.
Otherwise runs the script, streaming output to the terminal and the log.
Re-checks validation. A still-failing check counts as a failure.
On failure: abort if required, else warn and continue.

Step script contract

A step script is plain bash. It inherits this environment:

`MIGRATE_ROOT`	repo root — call `"$MIGRATE_ROOT/migrate" restore ...` to reuse restore phases
`MIGRATION_DATA`	data directory (`payload/`, `manifest/`, `secrets/`); also aliased as `BASE`
`STEP_ID`	this step's id
`CFG_*`	every key from `config`

Make it idempotent, return non-zero only on real failure, and prefer a manifest validation over re-checking inside the script.

Example step

{
  "id": "dotfiles",
  "title": "Dotfiles",
  "subtitle": "Clone the repo and run its installer",
  "run": "steps/dotfiles.sh",
  "validation": "test -e $HOME/.config/dotfiles",
  "required": false
}

Full examples ship in the repo: manifests/example-homebrew.json and manifests/example-macports.json.