devflow_core/lib.rs
1//! DevFlow — Agent-agnostic development workflow automation.
2//!
3//! The core library returns structured types and performs workflow mechanics;
4//! frontends such as the CLI format output for humans or machines.
5//!
6//! ## Logging
7//!
8//! DevFlow uses the [`tracing`] crate for structured, level-aware logging. All
9//! log output goes to **stderr** so stdout remains available for agent output,
10//! structured results, and machine-readable data.
11//!
12//! ### Log Levels
13//!
14//! Set the `RUST_LOG` environment variable to control verbosity:
15//!
16//! | Level | Use case |
17//! |---------|----------|
18//! | `error` | Fatal conditions that abort the workflow |
19//! | `warn` | Unexpected but recoverable conditions (e.g., force operations) |
20//! | `info` | Normal workflow events (state transitions, git operations) |
21//! | `debug` | Detailed I/O and git commands |
22//! | `trace` | Full tracing subscriber internals |
23//!
24//! ```bash
25//! RUST_LOG=info devflow start --phase 3 --agent claude --mode auto # Default: shows state transitions
26//! RUST_LOG=debug devflow start --phase 3 --agent claude --mode auto # Also shows git commands and file I/O
27//! RUST_LOG=warn devflow status # Suppress info, show only warnings
28//! ```
29//!
30//! The default log level is `info` when `RUST_LOG` is not set.
31//!
32//! ### JSON Output
33//!
34//! Set `DEVFLOW_LOG_FORMAT=json` for machine-readable JSON log lines on stderr:
35//!
36//! ```bash
37//! DEVFLOW_LOG_FORMAT=json RUST_LOG=info devflow status 2>log.json
38//! ```
39//!
40//! Each line is a JSON object with `timestamp`, `level`, `fields`, and
41//! `target` keys. Structured events like `step_entered`/`step_exited` include
42//! `phase` and step-name fields.
43//!
44//! ### Structured Events
45//!
46//! State machine transitions emit structured `tracing` events:
47//!
48//! - `step_exited` — emitted when leaving a step, with `phase` and step name
49//! - `step_entered` — emitted when entering a step, with `phase` and step name
50//!
51//! These events are at `INFO` level and include the phase number as a named
52//! field, making them filterable and parseable by external tooling.
53
54pub mod agent;
55pub mod agent_result;
56pub mod agents;
57pub mod config;
58pub mod events;
59pub mod gates;
60pub mod git;
61pub mod hooks;
62pub mod lock;
63pub mod mode;
64pub mod monitor;
65pub mod prompt;
66pub mod recover;
67pub mod ship;
68pub mod stage;
69pub mod state;
70pub mod version;
71pub mod workflow;
72pub mod worktree;
73
74// Re-exports for convenience.
75pub use mode::Mode;
76pub use stage::Stage;
77pub use state::{AgentKind, State};