63 lines
3.8 KiB
Text
63 lines
3.8 KiB
Text
|
# schemas/lib/playbook.ncl — PlaybookDef and PlaybookStep contracts
|
||
|
|
#
|
||
|
|
# Every playbook in extensions/playbooks/<name>/playbook.ncl validates against this schema.
|
||
|
|
# validate-playbooks reflection mode (TASK-C6) checks:
|
||
|
|
# - playbook.ncl conforms to PlaybookDef
|
||
|
|
# - run.nu exists for each step that references it
|
||
|
|
# - rollback.nu exists when rollback_strategy = 'automatic
|
||
|
|
# - tests/dry_run.nu is checked with nu --ide-check when present
|
||
|
|
#
|
||
|
|
# Usage:
|
||
|
|
# let pb = import "schemas/lib/playbook.ncl" in
|
||
|
|
# { .. } | pb.PlaybookDef
|
||
|
|
|
||
|
|
let _RollbackStrategy = [| 'automatic, 'manual, 'none |] in
|
||
|
|
|
||
|
|
let _StepErrorAction = [| 'Stop, 'Rollback, 'Continue |] in
|
||
|
|
|
||
|
|
# A declared parameter the playbook accepts — forwarded as env vars to step scripts.
|
||
|
|
let _ParamDef = {
|
||
|
|
name | String | doc "Parameter name (becomes env var: PLAYBOOK_PARAM_<NAME>)",
|
||
|
|
description | String,
|
||
|
|
required | Bool | doc "When true, absence causes the runner to abort before any step" | default = true,
|
||
|
|
default_val | String | doc "Default value used when required = false and the caller omits the param" | default = "",
|
||
|
|
} in
|
||
|
|
|
||
|
|
# A single step in a playbook. Each step maps to a script relative to the playbook root.
|
||
|
|
let _PlaybookStep = {
|
||
|
|
id | String | doc "Unique step identifier within this playbook; used in depends_on refs",
|
||
|
|
name | String | doc "Human-readable step label shown in dry-run output",
|
||
|
|
script | String | doc "Path to the Nushell step script relative to the playbook directory (e.g., 'run.nu', 'steps/deploy.nu')",
|
||
|
|
dry_run_arg | String | doc "Flag appended to script invocation when running in dry-run mode" | default = "--dry-run",
|
||
|
|
params | { _ | String } | doc "Static key-value params forwarded to the step script as env vars; caller params overlay these" | default = {},
|
||
|
|
on_error | _StepErrorAction | doc "Action taken when this step exits non-zero" | default = 'Stop,
|
||
|
|
depends_on | Array String | doc "Step IDs that must complete successfully before this step runs" | default = [],
|
||
|
|
} in
|
||
|
|
|
||
|
|
# The full playbook declaration. Consumed by 'prvng playbook run <id>' and the
|
||
|
|
# validate-playbooks reflection mode.
|
||
|
|
let _PlaybookDef = {
|
||
|
|
id | String | doc "Machine-readable playbook identifier matching the directory name (e.g., 'bootstrap_initial')",
|
||
|
|
name | String | doc "Human-readable playbook title",
|
||
|
|
description | String,
|
||
|
|
version | Number | doc "Schema version — must be 1" | default = 1,
|
||
|
|
preconditions | Array String | doc "Human-readable preconditions the operator must verify before running; printed in dry-run output" | default = [],
|
||
|
|
params | Array _ParamDef | doc "Declared parameters; absent required params abort before step 1" | default = [],
|
||
|
|
steps | Array _PlaybookStep | doc "Ordered step declarations; topological sort applied using depends_on",
|
||
|
|
rollback_strategy | _RollbackStrategy | doc "automatic: rollback.nu is invoked on any step failure; manual: operator handles; none: no rollback path" | default = 'none,
|
||
|
|
success_criteria | Array String | doc "Human-readable criteria printed after a successful run to help the operator verify the outcome" | default = [],
|
||
|
|
emit_audit | Bool | doc "When true, playbook runner emits ops.audit events at step start and completion" | default = false,
|
||
|
|
adr_refs | Array String | doc "ADR IDs this playbook implements (e.g., 'adr-037', 'adr-039')" | default = [],
|
||
|
|
} in
|
||
|
|
|
||
|
|
{
|
||
|
|
RollbackStrategy = _RollbackStrategy,
|
||
|
|
StepErrorAction = _StepErrorAction,
|
||
|
|
ParamDef = _ParamDef,
|
||
|
|
PlaybookStep = _PlaybookStep,
|
||
|
|
PlaybookDef = _PlaybookDef,
|
||
|
|
|
||
|
|
make_step | not_exported = fun data => data | _PlaybookStep,
|
||
|
|
make_playbook | not_exported = fun data => data | _PlaybookDef,
|
||
|
|
}
|