Kenn Forge Ephemeral Dev

Kenn Forge Ephemeral Dev

Core Rule

Use make dev-ephemeral when the user wants a local kenn-forge dev stack without fixed ports or without mutating the normal config/database. Do not hand-roll separate make dev and make frontend-dev commands unless the user explicitly asks for manual process control.

Workflow

1. Start the stack:

   make dev-ephemeral
   

   Provider sync is disabled by default. Opt in only when fresh provider data is required:

   make dev-ephemeral ARGS="-sync"
   

2. The default work directory is tmp/dev-ephemeral. Re-running the command while that stack is live prints the existing status instead of starting a duplicate stack.

3. For a separate concurrent run directory or explicit ports, pass ARGS:

   make dev-ephemeral ARGS="-work-dir tmp/my-run"
   make dev-ephemeral ARGS="-backend-port 19091 -frontend-port 15174 -mcp-port 19092"
   

4. Use a fresh empty DB only when requested:

   make dev-ephemeral ARGS="-fresh-db"
   

Behavior Contract

• The launcher starts both backend and frontend.
• The backend disables provider sync by default; -sync explicitly enables it.
• It writes a generated config at <work-dir>/config.toml.
• When the source config enables MCP, the generated config moves the MCP listener to a free port (or -mcp-port) so the ephemeral backend never fights the live daemon for the configured one; the status JSON reports it as mcp_port and mcp_url, omitted when MCP is disabled.
• It copies the configured source SQLite DB by default into <work-dir>/data/forge.db.
• It passes KENN_FORGE_CONFIG=<work-dir>/config.toml to both processes.
• It passes KENN_FORGE_API_URL=<backend-url> to the frontend.
• It writes typed status JSON at <work-dir>/dev-ephemeral.json.
• make dev-ephemeral-stop without arguments stops the default tmp/dev-ephemeral stack.
• The launcher is intentionally unsupported on Windows for now.

Status JSON

Read <work-dir>/dev-ephemeral.json when another tool or response needs process discovery:

{
  "pid": 1001,
  "backend_pid": 1002,
  "frontend_pid": 1003,
  "backend_port": 19091,
  "frontend_port": 15174,
  "mcp_port": 19092,
  "config_path": "tmp/my-run/config.toml",
  "data_dir": "tmp/my-run/data",
  "backend_url": "http://127.0.0.1:19091",
  "frontend_url": "http://127.0.0.1:15174",
  "mcp_url": "http://127.0.0.1:19092"
}

Treat this as the source of truth for selected ports and PIDs instead of scraping terminal output.

Verification

For changes to the workflow or this skill, run:

go test ./tools/devephemeral -shuffle=on
go run ./cmd/testify-helper-check ./tools/devephemeral
make help

Before claiming the stack is running, verify the status file exists and contains both child PIDs and both URLs.