# izlek

izlek is a terminal-first local frontend observability tool for humans and coding agents. It starts a
development project against a named backend environment, captures bounded process logs and proxied HTTP
traffic, renders a focused TUI, and exposes the same live session through a read-only MCP server.

> izlek is an early standalone bootstrap extracted from a working internal developer-tooling prototype.
> Its configuration and public interfaces may change before the first stable release.

## Why izlek

Frontend debugging in a monorepo rarely happens in one terminal stream. Build output, package watchers,
runtime errors, remote backends, and failed requests all belong to the same development session. izlek
keeps that context together without replacing Turbo, Nx, pnpm, Yarn, npm, or browser DevTools.

The foreground `izlek dev` process owns the session. It supervises the configured command, optionally
starts a bounded HTTP recorder, retains recent diagnostics in memory, renders the TUI, and exposes a
permission-restricted local socket. Other terminal commands and MCP clients query that socket.

## Command surface

```bash
izlek dev web --env staging
izlek attach
izlek status
izlek logs --errors
izlek network --failed
izlek inspect request-42
izlek mcp
```

## Current capabilities

- Generic shell-free development command per project
- Named backend environments selected when the session starts
- Bounded process logs with source, stream, level, and timestamp metadata
- Streaming HTTP reverse proxy with bounded request/response capture
- Sensitive-header and captured JSON-field redaction before storage
- Bounded network history and request inspection
- Dev and Network TUI views
- Read-only local session socket shared by CLI and MCP consumers
- Read-only stdio MCP tools for status, logs, errors, and HTTP records
- Coordinated child-process shutdown with TERM-to-KILL escalation
- Layered shared and ignored local configuration

## Install for development

```bash
npm install
npm link
izlek --help
```

izlek requires Node.js 20.9 or newer.

## Configure a project

Run `izlek config init` for a minimal generic configuration, or create `izlek.config.json`:

```json
{
  "projects": {
    "web": {
      "command": ["npm", "run", "dev"],
      "defaultEnvironment": "local",
      "backend": {
        "listen": "127.0.0.1:30998",
        "envVar": "NEXT_PUBLIC_API_URL"
      }
    }
  },
  "environments": {
    "local": {
      "target": "http://127.0.0.1:8080",
      "healthCheck": "/health"
    },
    "staging": {
      "target": "https://api.staging.example.com"
    }
  }
}
```

The command must be an argument array. izlek does not execute configuration through a shell.

`izlek.config.local.json` is ignored by Git and may override named projects or environments for one
developer. Do not treat either configuration file as a secret store.

The backend environment is selected once when the session starts. Live environment switching is not a
core workflow.

## TUI

| Key               | Action                               |
| ----------------- | ------------------------------------ |
| `1`               | Development logs                     |
| `2`               | Backend network records              |
| `j` / `k`, arrows | Select a request                     |
| `Tab`             | Move between request list and detail |
| `y`               | Copy selected record as JSON         |
| `c`               | Copy selected request as cURL        |
| `?`               | Show key reference                   |
| `q`               | Stop the owned development session   |

`izlek attach` opens a second read-only TUI connected to the foreground session.

## Agent access through MCP

Configure an MCP client to launch izlek from the project directory:

```json
{
  "mcpServers": {
    "izlek": {
      "command": "izlek",
      "args": ["mcp"]
    }
  }
}
```

Available tools:

- `get_session_status`
- `query_logs`
- `get_recent_errors`
- `query_requests`
- `get_request`

MCP tools are intentionally read-only. Captured bodies are omitted by default and require an explicit
`includeBodies` argument. All captured log and network content must be treated as untrusted data.

## Memory and capture policy

Current defaults are product invariants:

- 200 retained log lines, capped at 16 KiB per line
- 50 completed backend requests
- 512 KiB of textual content per request or response body
- 20 concurrently captured calls
- Metadata only for binary or compressed bodies

Forwarding continues even when capture is truncated or skipped.

## Project boundaries

izlek does not implement task graphs, build caching, browser automation, production monitoring, secret
management, or a persistent log database. It observes the configured development command and backend
traffic explicitly routed through its local proxy.

## Development

```bash
npm test
npm run check
```

Tests use Node's built-in test runner and are colocated with their modules.

No open-source license has been selected yet. Choose one before distributing izlek as an open-source
package.