honey-biscuit-workshop/AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2026-06-12T16:08:15Z Commit: 3629c33 Branch: feat/bake-dag-tester

OVERVIEW

HoneyBiscuitWorkshop (蜜饼工坊) — Rust-based CI/CD system inspired by Concourse CI. Pipeline: prebake.yml → bake.sh → finalize.yml. Multi-builder (Docker, Firecracker, bare metal). Plugin system.

STRUCTURE

./
├── workshop-baker/       # Main binary + lib — orchestrator, CLI, plugins
├── workshop-engine/      # Core execution engine — process mgmt, package managers
├── workshop-schedule/    # DAG scheduling library (petgraph-based)
├── workshop-getterurl/   # URL fetching with hash verification
├── workshop-baker-params/ # Config/parameter type definitions
├── docs/                 # mdBook documentation (Chinese, 3 volumes)
├── templates/            # Pipeline config templates (prebake/bake/finalize)
└── .github/workflows/    # CI (tests workshop-baker + workshop-engine)

No root Cargo workspace — crates linked by path deps. Build per-crate.

WHERE TO LOOK

Task	Location	Notes
CLI definition	workshop-baker/src/lib.rs	Clap Cli/Commands/BareCommands
Pipeline orchestration	workshop-baker/src/main.rs	prebake→bake→finalize→notify flow
Decorator parsing	workshop-baker/src/bake/decorator.rs	# @decorator(args) syntax
Build execution	workshop-baker/src/bake/execute.rs	Script execution with timeout/retry
Docker integration	workshop-baker/src/prebake/env/container.rs	Bollard-based
Package managers	workshop-engine/src/pm/	apt, pacman, dnf, apk
User package managers	workshop-engine/src/upm/	rustup, uv, go
Notification system	workshop-baker/src/notify/	Email, webhook, IM
Plugin system	workshop-baker/src/finalize/plugin/	shell, dylib, rhai, internal
Error types	workshop-baker/src/error.rs	CliError + HasExitCode
Exit codes	workshop-engine/src/error.rs	EXITCODE_* constants
DAG scheduling	workshop-schedule/src/dag.rs	Topological sort, batch picking
Pipeline templates	templates/	Reference config DSL

ENTRY POINTS

Entry	Type	Path	Role
workshop-baker	Rust bin	workshop-baker/src/main.rs	Primary CLI — dispatch: default (full pipeline), bare (single stage), daemon (unimplemented)
workshop_baker	Rust lib	workshop-baker/src/lib.rs	Baker library + CLI structs
workshop_engine	Rust lib	workshop-engine/src/lib.rs	Core engine — ExecutionContext, EventSender, Executor
workshop_schedule	Rust lib	workshop-schedule/src/lib.rs	Dag, DagNode, EdgeKind
workshop_baker_params	Rust lib	workshop-baker-params/src/lib.rs	Layered config: defaults → base → courier
workshop_getterurl	Rust lib	workshop-getterurl/src/lib.rs	GetterUrl, fetch() — http/git/file
docs	mdBook	docs/book.toml	Project documentation site

CODE MAP

Crate Dependency Graph

workshop-baker (bin)
  ├── workshop-engine
  ├── workshop-schedule
  ├── workshop-baker-params
  └── workshop-getterurl

workshop-baker Module Map

Module	Submodules	Role
bake	decorator, execute, parser, schedule, builder, trivial, util, constant, error	Script parsing + execution
prebake	config, stage (bootstrap, depssystem, depsuser, environment, hook), env (container, firecracker, baremetal, custom), security, event, types, constant, error	Environment setup
finalize	plugin (shell, dylib, rhai, internal), stage, template, types, config, constant, error, event	Post-build hooks
notify	handler, queue, rule, template, types, util, error	Async notification dispatch
bare	—	Standalone single-stage CLI mode
types	resource, buildstatus	Shared type definitions
utils	—	Cross-cutting utilities

CONVENTIONS

• Edition: Rust 2024 (requires Rust 1.85+)
• Formatting: Default rustfmt — no rustfmt.toml / .editorconfig
• Lint overrides (workshop-baker only): dead_code = "allow", unreachable_code = "allow", inherent_to_string = "allow", non_canonical_partial_ord_impl = "allow"
• Import order: std → external crates → crate:: (blank line between groups)
• Error handling: thiserror for libraries, anyhow for binaries. Implement HasExitCode for exit code mapping.
• Type system: Newtype pattern preferred (e.g., MemSize(u64)). Shared types in types/ module. types/ must NOT depend on bake/, engine/, prebake/, finalize/.
• Tests: Inline #[cfg(test)] mod tests at bottom of source files. Async: #[tokio::test]. CI runs cargo test --all-features.
• Commits: type(scope): description — feat|fix|docs|test|refactor|style
• AI annotation: // Code in this module PARTIALLY or FULLY utilized AI Coding Agent — never delete if present
• Docs language: Chinese (zh-CN), mdBook
• No no_std: Explicitly unsupported

ANTI-PATTERNS (THIS PROJECT)

• Do NOT derive production behavior from bare mode — bare mode is dev-only, ctx.privileged is fake
• Do NOT use detect()/adopt() PM methods in production — PM selection must come from env config
• drop_after < DepsUser is FORBIDDEN — will break system dependency installation (needs root)
• Do NOT add magic URL inference — URL is URL, behavior bound explicitly via getter:: prefix
• Do NOT use @ for version locking in URLs — it's an auth delimiter; use ?ref=
• Do NOT duplicate type definitions across modules — single source of truth in types/
• Careful with unimplemented!() — Daemon mode, Rhai/Dylib plugins, and Custom builder are stubs
• Security: PIPELINE_CONTAINER_PRIVILEGED, PIPELINE_BAREMETAL_ELEVATE, PIPELINE_UNCOVER_SECRET require explicit approval + audit

COMMANDS

# Build (per crate, no workspace)
cd workshop-baker && cargo build --all-features

# Test (per crate)
cd workshop-baker && cargo test --all-features
cd workshop-engine && cargo test --all-features

# Lint (CI gate)
cargo fmt -- --check
cargo clippy --all-features -- -D warnings

# Docs
cd docs && mdbook build     # output in docs/book/
cd docs && mdbook serve     # local preview at localhost:3000

NOTES

• No workspace Cargo.toml at root — each crate has its own Cargo.lock. Build individually.
• CI only tests workshop-baker and workshop-engine; smaller crates tested transitively.
• quicktest.sh in workshop-baker/ is a dev smoke-test script (Docker-based, not CI).
• Git submodules: rust-tongsuo, RustyVault (crypto — not yet integrated into build).
• .secret/ contains real credentials — never commit, never read into context.
• See docs/src/zh-CN/vol3_dev/ for full developer documentation (architecture, design decisions, code style).