Watch Mode

Auto-compile .kern files on change with kern dev.

Usage

kern dev <file.kern|dir> [--target=<target>] [--outdir=<dir>] [--no-gaps] [--verify]

kern dev is the primary command for local development. It compiles all .kern files on startup, then watches for changes and recompiles automatically.

Flags

  • --target=<target> — Compilation target (overrides kern.config.ts). Valid: nextjs, tailwind, web, native, express, cli, terminal, ink, vue, nuxt, fastapi.
  • --outdir=<dir> — Output directory for generated files. Preserves relative directory structure from the source.
  • --no-gaps — Disable coverage gap reporting. By default, KERN writes gap analysis to .kern-gaps/.
  • --verify — Verify evolved node checksums on load. Used to detect tampered .kern/evolved/ definitions.

How It Works

On startup, kern dev performs these steps in order:

  1. Loads kern.config.ts from the project root (or auto-detects target from package.json)
  2. Applies CLI flag overrides (--target, --outdir)
  3. Auto-detects framework versions (Tailwind, Next.js) from the nearest package.json
  4. Loads template definitions from paths specified in config.templates
  5. Loads evolved nodes from .kern/evolved/ if present
  6. Performs initial compilation of all .kern files in the watched directory
  7. Starts file watcher (chokidar) for continuous recompilation

File Watching

The watcher responds to three events:

  • change — File modified. Recompiles and shows compilation time.
  • add — New .kern file created. Compiles immediately.
  • unlink — File deleted. Removes the corresponding generated output file.

The watcher uses a 100ms stability threshold to avoid partial-write compilations.

Directory Structure Preservation

When watching a directory with --outdir, KERN preserves the relative path structure from source to output:

# Source structure:
src/
  landing.kern
  docs/
    overview.kern
    getting-started.kern

# Command:
kern dev src/ --target=nextjs --outdir=app/

# Output:
app/
  landing/page.tsx
  docs/
    overview/page.tsx
    getting-started/page.tsx

Output File Extensions

The generated file extension depends on the target:

  • .tsx — nextjs, tailwind, web, native
  • .ts — express, cli, terminal
  • .vue — vue, nuxt
  • .py — fastapi

For the nextjs target, output files follow Next.js conventions: page.tsx, layout.tsx, loading.tsx, error.tsx.

Coverage Gaps

By default, kern dev analyzes each compiled file for coverage gaps and writes results to .kern-gaps/ in the project root. This helps track which parts of your .kern source could be improved.

To disable this behavior, pass --no-gaps.

Examples

# Watch a directory, compile to Next.js pages
kern dev src/kern/ --target=nextjs --outdir=app/

# Watch a single file
kern dev dashboard.kern --target=tailwind

# Watch with Vue target
kern dev kern/ --target=vue --outdir=src/components/

# Watch without coverage gap analysis
kern dev src/ --target=nextjs --outdir=app/ --no-gaps

# Watch with evolved node verification
kern dev src/ --target=nextjs --outdir=app/ --verify

Stopping

Press Ctrl+C to stop the watcher. kern dev prints “KERN dev stopped.” and exits cleanly.