# src

## Purpose

Contains the `flow` CLI implementation for this repo.

## Modules

- `cli.js`: process entrypoint and command dispatch for `init`, `config`, `run`, `resume`, `set-step`, `status`, `list`, and `logs`, including `flow init --template` / `--list-templates`
- `config.js`: config defaults, YAML parsing, merge precedence across global/project/workflow/workflow-local/env/flag layers, workflow-local path discovery, and validation
- `init-project.js`: filesystem logic for `flow init`, reusable template discovery under `.flow/templates/<name>/workflow.yaml`, strict template-name validation before CLI/path use, template placeholder resolution for `{{template.*}}` prompts and `{{config.*}}` config-backed values, and safe non-overwriting scaffold creation
- `run-workflow.js`: workflow YAML parsing, workflow `parameters` definitions with string/number/boolean typing plus defaults and required flags, conditional `if` expressions with `env.*`, `steps.*.(stdout|stderr|exit_code)`, and `parameters.*` references, first-class `gate` steps with `gate_action: fail|warn` and optional messages, first-class `subflow` steps with child run IDs, parent linkage, `with` parameter passing, child `FLOW_PARAM_*` env injection, per-workflow hierarchical config resolution for top-level and nested workflows, persisted child `run_started.parameters` metadata, output aggregation, and failure propagation, `step_skipped` persistence plus deterministic resume for skipped steps, manual `step_set` overrides with interactive confirmation plus auditable resume-position changes for failed and completed runs, `for_each` loop expansion with strict loop-template validation plus `{{item}}`/iteration metadata templating, shell-escaped loop-item interpolation for `run` commands, ordered execution with optional parallel batches, loop batches that finish every iteration before surfacing failure, `depends_on` validation with cycle and same-batch dependency checks, append-only JSONL event persistence under `.flow/runs/`, optional structured harness-event emission to stdout when `HARNESS_SESSION_ID` is set, nested execution-path metadata for root and subflow runs, persisted run-status reconstruction for `flow status`, persisted run listing and status filtering for `flow list`, persisted log reconstruction and step filtering for `flow logs`, failed-run replay plus manual-reset replay for `flow resume`, run-ID validation for persisted status/log lookups, stable failure event schemas for timeouts, non-zero exits, gate failures, and subflow failures, persisted stdout/stderr for completed and failed steps, per-step timeout overrides, streamed output with per-step prefixes during parallel and loop execution, coordinated cancellation for parallel children on step failure or workflow signals, previous-step output env propagation, loop metadata env propagation, ANSI-colored run output, and failure diagnostics with recent output plus resume hints

## Conventions

- Keep source in ESM JavaScript under `src/`
- Export small public functions with JSDoc
- Prefer pure helpers around filesystem decisions where practical
- Preserve idempotent CLI behavior; do not overwrite user files silently
- Add tests in `tests/` for every new branch in CLI behavior

## Verification

- Run `npm test`
- Run `npm run coverage`
- Run `npx eslint src/ --fix`
- Run `npx eslint src/`