honey-biscuit-workshop/workshop-baker/AGENTS.md

WORKSHOP-BAKER CRATE KNOWLEDGE BASE

OVERVIEW

Primary crate — the only crate with a [[bin]] target. Contains the workshop-baker binary and workshop_baker library. Orchestrates the full CI/CD pipeline: prebake (env setup) → bake (script execution) → finalize (plugins, cleanup) → drain notification queue. ~69 .rs source files.

STRUCTURE

src/
├── main.rs              # Entry: default(full pipeline) | bare(dev-only) | daemon(unimplemented)
├── lib.rs               # Clap Cli/Commands/BareCommands — CLI structs in lib, not bin
├── error.rs             # CliError enum (wraps stage errors, delegates exit_code)
├── bare.rs              # Dev-only single-stage execution, ctx.privileged always false
├── utils.rs             # Cross-cutting helpers
├── bake/                # Script parsing + DAG scheduling + execution
│   ├── decorator.rs     # @decorator(args) parsing, 81 tests — heaviest coverage in crate
│   ├── parser.rs        # Step/function extraction
│   ├── schedule.rs      # DAG build → topological sort
│   ├── execute.rs       # Per-step timeout/retry
│   ├── builder.rs       # Script assembly
│   ├── trivial.rs       # Trivial step detection (skip in dry-run)
│   ├── constant.rs / error.rs / util.rs
├── prebake/             # Environment provisioning
│   ├── config.rs        # PrebakeConfig deserialization
│   ├── stage.rs + stage/{bootstrap,depssystem,depsuser,environment,hook}.rs
│   ├── env.rs + env/{container,firecracker,baremetal,custom}.rs  # Builder dispatch
│   ├── security.rs      # Privilege/sandbox checks
│   ├── event.rs         # Event sender/receiver channel
│   ├── types.rs + types/{memsize,cache,builderconfig,architecture}.rs
│   ├── constant.rs / error.rs
├── finalize/            # Post-build hooks + plugins
│   ├── config.rs        # FinalizeConfig
│   ├── stage.rs + stage/hook.rs
│   ├── template.rs      # Output templating (minijinja)
│   ├── plugin.rs + plugin/{shell,dylib,rhai,internal}.rs
│   │   └── plugin/internal/{dummy,mail,satori,webhook,insitenotify}.rs
│   ├── types.rs + types/compression.rs
│   ├── constant.rs / error.rs / event.rs
├── notify/              # Async notification dispatch
│   ├── queue.rs         # NotificationQueue — drain on pipeline complete
│   ├── handler.rs / rule.rs / template.rs / types.rs / util.rs / error.rs
└── types/               # Shared types — ZERO deps on stage modules
    ├── resource.rs      # ResourceRegistry (populated pre-pipeline, consumed read-only)
    └── buildstatus.rs

WHERE TO LOOK

Task	Location	Notes
CLI args + subcommands	src/lib.rs	Cli, Commands(Bare/Daemon), BareCommands
Pipeline orchestration	src/main.rs	worker_main(): prebake→bake→finalize→queue.drain()
Decorator syntax	src/bake/decorator.rs	# @decorator or # @decorator(args), line-by-line regex
Build execution	src/bake/execute.rs	timeout, retry, exit code capture
DAG scheduling	src/bake/schedule.rs	Uses workshop-schedule crate
Docker builder	src/prebake/env/container.rs	Bollard-based, buildkit support
Firecracker / Bare metal	.../firecracker.rs, .../baremetal.rs	MicroVM;
needs PIPELINE_BAREMETAL_ELEVATE
Plugin dispatch	src/finalize/plugin.rs	Dispatches shell / dylib(stub) / rhai(stub) / internal
Notification queue	src/notify/queue.rs	Spawned early, drained after pipeline, retry support
Error type	src/error.rs	CliError wraps PrebakeError/BakeError/FinalizeError/anyhow
Dev bare mode	src/bare.rs	ctx.privileged=false always; do not extrapolate to production

DEPENDENCIES

Internal: workshop-engine, workshop-schedule, workshop-getterurl, workshop-baker-params. External: bollard (Docker), clap (CLI), axum 0.7 (HTTP), lettre 0.11 (email), minijinja (templates), cgroups-rs (limits), privdrop.

CONVENTIONS (CRATE-SPECIFIC)

• Lint overrides (this crate only): dead_code=allow, unreachable_code=allow, inherent_to_string=allow, non_canonical_partial_ord_impl=allow
• CLI structs in lib.rs, not main.rs — enables integration tests to import and construct Cli directly.
• Pipeline stages return anyhow::Result<()> — stages propagate with ?; only main.rs converts to CliError.
• ResourceRegistry pattern — populated before pipeline stages, consumed read-only by stages. New resource types go in types/resource.rs.
• Notification queue fire-and-forget + drain — notify tasks spawned early, send during pipeline, drain on completion. NotificationQueue::drain() must be called.
• Trivial step detection — steps with no external deps can be marked trivial (trivial.rs), skipped in dry-run.

ANTI-PATTERNS (THIS CRATE)

• Do NOT derive production behavior from bare mode — ctx.privileged is hardcoded false.
• Do NOT add CLI args bypassing prebake→bake→finalize ordering — the pipeline is linear. Parallelism lives in the DAG scheduler within bake.
• Do NOT import types/ from bake/, prebake/, or finalize/ — types/ must have zero crate-internal deps.
• Do NOT add lint allows without justification — the four existing overrides are intentional.
• Do NOT spawn blocking work on tokio runtime — use spawn_blocking for CPU-heavy tasks.
• Decorator regex is line-by-line — multi-line decorators need a parser rewrite, not a regex hack.
• Careful with unimplemented!() — Daemon, Rhai/Dylib plugins, Custom builder are stubs. Prefer error over crash.