Fraktos solves the headache of starting up and maintaining multiple local development servers concurrently. Whether you're running a backend in Python (FastAPI/Django), multiple frontends in React/Next.js, or supporting services in Go, Fraktos launches them in a coordinated, dependency-aware DAG, aggregates their logs with custom coloring, and guarantees clean, signal-level cleanup with absolutely zero zombie processes left behind.

✨ Features

• ⛓️ DAG-based Asynchronous Scheduler: Resolves dependencies asynchronously. Frontends start automatically and concurrently the millisecond their required backend services have spawned.
• 🎨 Log Multiplexing (Vibrant UX): Captures stdout/stderr from each sub-process, format-pipes it line-by-line, and prefixes it with the project's name in a unique color.
• 🛑 Graceful Process Group Teardown: Uses Unix process groups (via detached spawning) to forward termination signals down the entire execution subtree (e.g. killing npm run dev also terminates its child node servers).
• ⚙️ Localized Variables & Routing: Fine-grained controls over individual working directories (cwd) and env overrides.
• 🔌 Dual CLI & Programmatic API: Use as a standard command-line utility or import directly into your custom developer tools as a library.

🚀 Quick Start

1. Installation

To use it in your project:

npm install fraktos --save-dev

Or run it directly using npx:

npx fraktos --help

2. Configuration (fraktos.config.json)

Create a fraktos.config.json in the root of your project:

{
  "projects": [
    {
      "name": "backend-python",
      "path": "./backend",
      "command": "poetry run uvicorn main:app --port 8000",
      "env": {
        "DEBUG": "true",
        "DATABASE_URL": "sqlite:///local.db"
      }
    },
    {
      "name": "frontend-admin",
      "path": "./apps/admin",
      "command": "npm run dev",
      "depends_on": ["backend-python"]
    },
    {
      "name": "frontend-client",
      "path": "./apps/client",
      "command": "npm run dev",
      "depends_on": ["backend-python"]
    }
  ]
}

3. Execution

Launch your orchestrated workspace by running:

npx fraktos

Need to use a custom configuration file? Simply specify it with the --config flag:

npx fraktos --config ./configs/my-custom-config.json

💻 Programmatic Usage

Fraktos can be imported and executed programmatically within your node-based scripts:

import { loadConfig, FraktosRunner, setupGracefulShutdown } from 'fraktos';

// Load and validate configuration
const { config, configDir } = loadConfig('./fraktos.config.json');

// Initialize the runner
const runner = new FraktosRunner(config, configDir);

// Register process SIGINT / SIGTERM hook traps
setupGracefulShutdown(runner);

// Run the tasks asynchronously
await runner.run();

🛠️ Architecture

Fraktos is structured as follows:

graph TD
  CLI[src/cli.ts] --> Config[src/config.ts]
  Config --> Runner[src/runner.ts]
  Runner --> Logger[src/logger.ts]
  Runner --> Shutdown[src/shutdown.ts]
  
  subgraph Runner Operations
    Spawn[child_process.spawn]
    ProcessGroup[Detached PGID]
  end

  Runner --> Spawn
  Spawn --> ProcessGroup

• src/config.ts: Configuration loading, validation, and cycle detection using DFS back-edge validation.
• src/logger.ts: Output formatting and line-by-line streaming.
• src/runner.ts: Asynchronous topology engine and environment manager.
• src/shutdown.ts: Intercepts terminal interrupts and applies process-group level teardown sequence.

📄 License

MIT © Fraktos Contributors.