Features

Service orchestration, readiness checks, hot-reload, log streaming, and more.

Service Orchestration & Tiers

Fuku starts services in tier order — earlier tiers fully start (and pass readiness checks) before later tiers begin. Within a tier, services start concurrently up to the configured worker limit.

Example tier setup:

services:
  postgres:
    dir: infrastructure/postgres
    tier: foundation            # Starts first

  redis:
    dir: infrastructure/redis
    tier: foundation            # Same tier — starts with postgres

  api:
    dir: backend/api
    tier: platform              # Starts after foundation is ready

  web:
    dir: frontend
    tier: edge                  # Starts after platform is ready

On shutdown, services stop in reverse tier order — edge first, then platform, then foundation.

Readiness Checks

Readiness checks confirm a service is truly ready before the next tier starts. Three check types are supported:

HTTP

Wait for an HTTP endpoint to respond with a 2xx status:

readiness:
  type: http
  url: http://localhost:8080/health
  timeout: 30s
  interval: 1s

TCP

Wait for a TCP port to accept connections:

readiness:
  type: tcp
  address: localhost:6379
  timeout: 10s
  interval: 1s

Log

Wait for a pattern to appear in service output:

readiness:
  type: log
  pattern: "gRPC server started"
  timeout: 30s

Field	Description
`type`	`http`, `tcp`, or `log`
`url`	HTTP endpoint to check (http type only)
`address`	Host:port to connect to (tcp type only)
`pattern`	String to match in log output (log type only)
`timeout`	Maximum time to wait before failing
`interval`	Time between check attempts (http/tcp only)

Hot-Reload

Fuku watches for file changes and automatically restarts the affected service. A debounce timer prevents restart storms when multiple files change at once.

services:
  api:
    dir: ./api
    watch:
      include: ["**/*.go"]           # Glob patterns to watch
      ignore: ["**/*_test.go"]       # Patterns to ignore
      shared: ["pkg/common"]         # Shared paths (triggers restart)
      debounce: 300ms                # Debounce duration (default: 300ms)

Field	Description
`include`	Glob patterns for files to watch
`ignore`	Glob patterns for files to exclude
`shared`	Paths shared across services — changes trigger a restart for this service
`debounce`	Wait time after last change before restarting (default: 300ms)

Log Streaming

While fuku is running, you can stream logs from a separate terminal using fuku logs. Logs are streamed over Unix sockets with service name prefixes.

# All services
fuku logs

# Specific services
fuku logs api auth

# Filter by profile
fuku logs --profile core api

Per-Service Log Output

Control which output streams are captured per service:

services:
  api:
    dir: ./api
    logs:
      output: [stdout]              # Only capture stdout
  worker:
    dir: ./worker
    logs:
      output: [stdout, stderr]      # Capture both (default)

Valid values: stdout, stderr. When omitted, both streams are captured.

Pre-flight Cleanup

Before starting services, fuku automatically detects and terminates orphaned processes from previous runs. This prevents port conflicts and zombie processes.

Pre-flight checks each service directory for leftover PID files and kills any stale processes before starting fresh.

Graceful Shutdown

When you press q in the TUI or send SIGINT/SIGTERM, fuku performs a graceful shutdown:

Services are stopped in reverse tier order (edge → platform → foundation)
Each service receives SIGTERM first
If the service doesn't exit within the timeout, SIGKILL is sent