honey-biscuit-workshop/workshop-engine/src/AGENTS.md

workshop-engine/src

Generated: 2026-05-19 Commit: 28abc5d

Execution engine extracted from workshop-baker. Process management, package detection, resource isolation.

STRUCTURE

src/
├── lib.rs             # Module declarations + 10+ convenience re-exports
├── error.rs           # ExecutionError + DependencyError + HasExitCode trait
├── types.rs           # ExecutionContext, ExecutionResult, Engine, etc.
├── child.rs           # ManagedChild + TokioChild process wrappers
├── command.rs         # CustomCommand builder
├── executor.rs        # Script execution
├── time.rs            # Duration parsing helpers
├── pm.rs              # PackageManager trait + detection
├── pm/                # Backends: apt, apk, dnf, pacman
├── upm.rs             # UserPackageManager trait
├── upm/               # Backends: rust (cargo), python (pip), go, custom
├── repology.rs        # RepologyEndpoint enum
└── repology/          # Package name resolution (local/)

KEY EXPORTS

Symbol	Type	Role
ExecutionContext	struct	Pipeline context (task_id, username, env, etc.)
Engine	struct	Script executor (placeholder)
ExecutionError	enum	Error types with exit codes
HasExitCode	trait	Exit code protocol for all error types
ManagedChild	struct	Child process wrapper with managed lifecycle
TokioChild	struct	Tokio-based child process wrapper
CustomCommand	struct	Builder for command execution
PackageManager	trait	System package manager abstraction
UserPackageManager	trait	User-level package manager abstraction
RepologyEndpoint	enum	Package name resolution endpoint
ExecutionEvent	enum	Event stream (TaskStarted, OutputChunk, etc.)
ExecutionResult	struct	Command execution result (exit_code, stdout, stderr)
EventSender	type alias	Option<mpsc::Sender<ExecutionEvent>>

CONVENTIONS

• Exit codes: Centralized in error.rs — EXITCODE_OK=0 through EXITCODE_PRIV_DROP_FAILED=201
• ExecutionContext: Defaults to current directory, bash shell, non-privileged
• PackageManagers: Auto-detected via os_info, fallback chain (apt→apk→dnf→pacman)
• Engine: Currently a unit struct with execute_script() method
• All errors implement HasExitCode: Enables uniform error propagation up to CLI

ANTI-PATTERNS

1. Engine is a stub — types.rs:99 — pub struct Engine; with no fields, minimal implementation