# kaze (nishikaze) — 8‑Step Implementation Plan
This is a pragmatic, milestone-driven plan to rewrite **zync** into:
- **crate/package:** `nishikaze`
- **binary:** `kaze`
Each step is intended to be independently “useful” (you can stop after any step and still have something handy).
---
## Step 1 — Repo skeleton + execution engine
**Goal:** have a working CLI binary that can run external commands reliably (with good errors).
**Deliverables**
- `nishikaze` workspace layout (single crate or split core/cli—either is fine)
- Central process runner:
- runs a command with `cwd`, env
- streams stdout/stderr live
- captures exit status + last N lines for diagnostics
- verbosity controls (quiet/normal/verbose)
- Error types that include: command, args, cwd, exit code
---
## Step 2 — Project discovery + config loading (layered)
**Goal:** find the project root from *any* reasonable starting directory and load config.
**Deliverables**
- Project traversal:
- `--project <path>` overrides everything
- otherwise traverse upward from `cwd` to find `kaze.toml`
- if invoked from a build dir, still finds the owning project root
- Config loader with layers + precedence:
1) defaults
2) user config `~/.config/kaze/config.toml` (optional)
3) project config `<project>/kaze.toml`
4) env `KAZE_*` (optional early)
5) CLI overrides
- Typed config structs + validation (missing required values should be actionable)
---
## Step 3 — Resolution + interpolation (`${key}`)
**Goal:** match zync’s “resolve final config first, interpolate second” behavior.
**Deliverables**
- Profile selection rules:
- `--all` → all profiles
- else `--profile`
- else `default_profile`
- else first profile
- CLI overrides for `--board/--runner` applied before interpolation
- Interpolation engine implementing the spec:
- supported keys: `board`, `runner`, `profile`, `build_dir`, `project_dir`, `zephyr_ws`, `zephyr_base`, `cwd`, `is_build`, `sysbuild`
- missing keys remain unchanged
- single-pass, non-recursive, cycle-safe
- Arg merge order:
1) global args
2) profile args
3) CLI passthrough args after `--`
---
## Step 4 — `kaze doctor` + `profiles` (fast feedback loop)
**Goal:** immediate usefulness and a debugging tool for you and CI.
**Deliverables**
- `kaze doctor` prints:
- detected project root
- resolved profile (or profile-less)
- resolved `board`/`runner`
- build dir path
- Zephyr workspace/base discovery result
- key tool availability checks (cmake, ninja, west, etc.)
- `kaze profiles` lists configured profiles in selection order
---
## Step 5 — `init` (generate `kaze.toml`)
**Goal:** parity with `zync init`.
**Deliverables**
- `kaze init`:
- writes a minimal `kaze.toml` template at project root (fails safely if exists, or supports `--force`)
- includes sane defaults and comments
- optionally infers a default board/runner from environment hints (optional)
---
## Step 6 — Single-image pipeline: `conf`, `build`, `clean`
**Goal:** be able to build a normal Zephyr app without sysbuild.
**Deliverables**
- `kaze conf`:
- runs CMake configure in active build dir
- supports `-- <extra cmake args>`
- `kaze build`:
- runs Ninja build (auto-runs configure if needed)
- supports `-- <extra ninja args>`
- `kaze clean`:
- cleans root build directory (or active profile build dir depending on mode)
- Global `--clean` pre-clean support (`kaze --clean build`)
---
## Step 7 — Profiles + build layout + compile_commands symlink
**Goal:** match zync’s profile build ergonomics + editor integration.
**Deliverables**
- Build layout:
- profile-less → `./build/`
- profiles → `./build/<profile>/`
- Root `./build/compile_commands.json` symlink to default/first profile (when profiles enabled)
- Board-change detection behavior:
- if a user configures/builds for board A then requests board B, rebuild the appropriate build dir
---
## Step 8 — Sysbuild + `flash`/`run` parity (plus listing backends)
**Goal:** match the feature set that made zync worth writing.
**Deliverables**
- Sysbuild detection:
- `sysbuild.conf` and/or `sysbuild/` directory heuristics
- Sysbuild image discovery:
- `kaze flash --list`
- `kaze flash --image <name|index>`
- default to first non-bootloader image
- `flash`:
- uses runner + passthrough args `-- <extra>`
- `run`:
- pre-build by default
- execute simulator binary directly when found; append extra args after `--`
- fallback to `ninja run` if binary not found (no arg append)
- `--norebuild/-n` supported
- `boards` / `runners`:
- implement via Zephyr tooling backends (delegate rather than reimplement)
- Polish (optional but recommended):
- `--dry-run` and/or `kaze plan` (print command plan without executing)
- `--json` output mode for CI
- shell completions
---
## Suggested “definition of done” for the v0.1 release
- Can build + run `native_sim` with profiles
- Can build + flash a sysbuild project image via `--image`
- `doctor` provides enough detail to debug misconfiguration
- README includes: install, quickstart, config schema, common workflows