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

```bash
# 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).