npm package: @lumiotech/faux
Description: A CLI for local dependency stacks, mock endpoints, and app-ready env output.
Author: Lumio Tech
Latest version: 1.0.1

# Faux

Faux is a small CLI for local development stacks. You describe the services your app depends on and the external systems you want to mock in `faux.yaml`, and Faux turns that into a Docker Compose setup you can validate, start, inspect, and wire into your app quickly.

Its most useful developer features live around the daily workflow: `faux validate` catches config footguns before startup, and `faux env` prints local connection variables from the same config you use to boot the stack so you do not have to manually translate ports into `.env` values every time you start working.

## What Faux Does Well

- Runs local dependency services like Postgres and Redis from a small config file.
- Creates lightweight HTTP and MQTT mock endpoints for third-party integrations.
- Validates Faux-owned config before startup and env export.
- Captures mock traffic so you can inspect requests in the dashboard.
- Prints canonical local connection variables with `faux env`.

## Installation

Install Faux globally:

```bash
npm install -g @lumiotech/faux
```

Or run it directly with `npx`:

```bash
npx @lumiotech/faux start
```

## Quick Start

Create a `faux.yaml` file in your project:

```yaml
services:
  postgres:
    image: postgres:15
    port: 5432
    environment:
      - POSTGRES_PASSWORD=secret

  redis:
    image: redis:7
    port: 6379

external_mocks:
  stripe:
    type: http
    port: 9001

  github:
    type: http
    port: 9002
```

Validate the config first:

```bash
faux validate
```

Start the local stack:

```bash
faux start
```

Print the local connection variables Faux derives from that config:

```bash
faux env
```

Example output:

```dotenv
# Faux local environment
# Copy the values you need into your app config.

# Services
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
REDIS_HOST=localhost
REDIS_PORT=6379

# External mocks
STRIPE_HOST=localhost
STRIPE_PORT=9001
STRIPE_URL=http://localhost:9001
GITHUB_HOST=localhost
GITHUB_PORT=9002
GITHUB_URL=http://localhost:9002
```

Launch the dashboard to inspect running containers and captured mock requests:

```bash
faux ui
```

The default dashboard URL is [http://localhost:4000](http://localhost:4000).

## Validation And Failure Behavior

Use `faux validate` when you want a quick preflight in the terminal or CI:

```bash
faux validate
```

Example output when the config has both blocking and non-blocking issues:

```text
Errors:
- external_mocks.mailer.type: Mock type must be either "http" or "mqtt".

Warnings:
- team: Unknown top-level key. Faux ignores this key.
```

Validation rules in this version focus on Faux-owned behavior:

- `services` and `external_mocks` must be mapping objects when present.
- Service and mock ports must be integers between `1` and `65535`.
- Mock `type` must be `http` or `mqtt`.
- Published ports cannot collide across services and mocks.
- Unknown top-level keys are warnings, not errors.
- `mode` supports `sbc`, and `profile: lightweight` remains accepted for backward compatibility.

`faux start` and `faux env` run this validation automatically. Errors stop the command with a non-zero exit code. Warnings print to `stderr`, but the command continues.

## How To Use Faux With Your App

Faux intentionally prints generic, zero-config variables based on your service and mock names. That keeps the feature predictable and avoids rewriting your app config behind your back.

If you want a helper file for your local session, redirect the output:

```bash
faux env > .env.faux
```

From there you can copy the values you need into your app's `.env`, or source the file in your own local workflow. Faux does not generate `DATABASE_URL` or other app-specific aliases in this version; it gives you stable building blocks like `POSTGRES_HOST`, `POSTGRES_PORT`, and `STRIPE_URL`.

Because validation warnings go to `stderr`, redirecting `faux env` to a file keeps the dotenv output clean on `stdout`.

## Commands

- `faux start` starts the stack defined in `faux.yaml`.
- `faux validate` checks Faux-owned config rules before you start services or export env vars.
- `faux env` prints local connection variables in dotenv format.
- `faux ui` starts the local dashboard on port `4000` by default.
- `faux status` shows `docker compose ps` output for the generated stack.
- `faux logs` tails logs from the running stack.
- `faux stop` stops and removes the generated stack.
- `faux import <docker-compose.yml>` converts an existing Compose file into a basic `faux.yaml`.

## Configuration

### `services`

Use `services` for local dependencies such as databases, caches, or internal tooling containers. Faux passes most service configuration through to Docker Compose. If you want `faux env` to export a service, give it an explicit `port`.

### `external_mocks`

Use `external_mocks` for systems you do not want to hit for real during development.

- `type: http` creates a local HTTP mock endpoint and captures requests in the dashboard.
- `type: mqtt` creates a local MQTT broker and captures published messages in the dashboard.
- If `type` is omitted, Faux treats the mock as HTTP.

### `mode`

Set `mode: sbc` if you want Faux to apply lightweight resource limits and ARM-oriented platform hints for small Linux devices such as Raspberry Pi boards.

## Example Workflow

```bash
faux validate
faux start
faux env > .env.faux
faux ui
```

This gives you:

- running local dependencies
- local mock endpoints for integrations
- inspectable request history
- a single place to discover the localhost values your app needs

## Roadmap

Ideas that are still future work:

- app-specific alias mapping such as `DATABASE_URL`
- optional env file writing as a first-class command behavior
- auto-port collision resolution

## Contributing

Contributions are welcome. Before opening a pull request:

```bash
npm install
npm test -- --runInBand
npm run lint
```

See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development process.