# 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
