@matthesketh/fleet 1.2.0 → 1.7.0

package/README.md

@@ -2,6 +2,8 @@
 
 # fleet
 
+[![audited by auto-audit](https://img.shields.io/badge/audited_by-auto--audit-6366f1?logo=github&logoColor=white)](https://auto-audit.hesketh.pro)
+
 **Docker production management CLI + MCP server**
 
 [![CI](https://github.com/wrxck/fleet/actions/workflows/ci.yml/badge.svg)](https://github.com/wrxck/fleet/actions/workflows/ci.yml)
@@ -10,7 +12,9 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/github/license/wrxck/fleet)](LICENSE)
 
-Manages Docker Compose applications on a single server with systemd orchestration, nginx configuration, encrypted secrets, Git/GitHub workflows, health monitoring, dependency tracking, and Telegram alerts.
+Manage Docker Compose apps on a single server -- systemd orchestration, nginx routing, age-encrypted secrets, health monitoring, dependency tracking, Git workflows, and an MCP server for AI-assisted operations.
+
+[Documentation](https://fleet.hesketh.pro) -- [npm](https://www.npmjs.com/package/@matthesketh/fleet) -- [GitHub](https://github.com/wrxck/fleet)
 
 </div>
 
@@ -18,324 +22,252 @@ Manages Docker Compose applications on a single server with systemd orchestratio
 
 ## Architecture
 
+```mermaid
+graph TD
+    CLI["fleet CLI"]
+    TUI["TUI Dashboard"]
+    MCP["MCP Server"]
+    BOT["fleet-bot (Go)"]
+
+    CLI --> Core
+    TUI --> Core
+    MCP --> Core
+    BOT -->|"via MCP"| Core
+
+    subgraph Core["Core Modules"]
+        Registry["Registry"]
+        Docker["Docker Compose"]
+        Systemd["systemd"]
+        Nginx["nginx"]
+        Secrets["Secrets Vault"]
+        Health["Health Checks"]
+        Git["Git / GitHub"]
+        Deps["Dependency Monitor"]
+    end
+
+    Docker --> Containers["Containers"]
+    Systemd --> Services["systemd Services"]
+    Nginx --> Proxy["Reverse Proxy"]
+    Secrets --> Vault["vault/*.age"]
+    Secrets --> Runtime["/run/fleet-secrets"]
+    Health --> Alerts["Telegram / iMessage"]
 ```
-fleet CLI (TypeScript/Node.js)
-├── Commands          CLI interface (fleet <command>)
-├── MCP Server        Claude Code integration (fleet mcp)
-├── Registry          App inventory (data/registry.json)
-├── Secrets Vault     age-encrypted secrets (vault/*.age)
-├── Deps Monitor      Dependency health scanning + alerting
-└── Templates         systemd, nginx, gitignore generators
-
-fleet-bot (Go)
-└── Telegram bot that runs Claude Code sessions for remote management
+
+Each Docker Compose app is registered with its compose path, domains, port, and container names. Fleet generates systemd units so apps start on boot in the correct order. Secrets are encrypted at rest with [age](https://github.com/FiloSottile/age) and decrypted to a tmpfs on boot.
+
+## Install
+
+```bash
+npm install -g @matthesketh/fleet
 ```
 
-### How it works
+Requires Node.js 20+, Docker Compose v2, systemd, nginx, and [age](https://github.com/FiloSottile/age). See the [full setup guide](https://fleet.hesketh.pro/getting-started/) for details.
 
-Each Docker Compose app is registered in fleet's registry with its compose path, service name, domains, port, and container names. Fleet generates a systemd service unit for each app so they start on boot in the correct order (databases first, then dependents). Secrets are encrypted at rest using [age](https://github.com/FiloSottile/age) and decrypted to a tmpfs at `/run/fleet-secrets/` on boot via a systemd oneshot service.
+## Key Features
 
-## Requirements
+**Deploy and manage apps** -- `fleet deploy <app-dir>` registers, builds, and starts an app in one command. Control services with `start`, `stop`, `restart`, and `logs`.
 
-- Node.js 20+
-- Docker + Docker Compose v2
-- systemd
-- nginx
-- [age](https://github.com/FiloSottile/age) (for secrets)
-- [gh](https://cli.github.com/) (for GitHub operations)
+**Encrypted secrets** -- age-encrypted vault with automatic backups, pre-seal validation, drift detection, and atomic rollback. Decrypted to tmpfs at boot -- secrets never touch disk.
 
-## Install
+**Nginx routing** -- Generate proxy, SPA, or Next.js server blocks with `fleet nginx add`. Automatic config testing and reload.
 
-### From npm
+**Health monitoring** -- Three-layer checks (systemd + container + HTTP) with `fleet health`. The `watchdog` command runs on cron and sends alerts on failure.
 
-```bash
-npm install -g @matthesketh/fleet
-```
+**Dependency scanning** -- Detects outdated packages, CVEs (via OSV), Docker image updates, and runtime EOL across all registered apps.
 
-### From source
+**Git workflows** -- Onboard apps to GitHub, manage branches, PRs, and releases from the CLI.
 
-```bash
-git clone https://github.com/wrxck/fleet.git
-cd fleet
-npm install
-npm run build
-sudo npm link
-```
+**Interactive dashboard** -- Run bare `fleet` to launch a full-screen TUI with real-time status.
 
-### Install as Claude Code MCP server
+See the [CLI reference](https://fleet.hesketh.pro/cli/) for the complete command list.
 
-```bash
-sudo fleet install-mcp
-```
+## Secrets Flow
 
-This writes the MCP server config to `~/.claude.json` so all Claude Code sessions can use fleet tools. Alternatively, add manually:
-
-```json
-{
-  "mcpServers": {
-    "fleet": {
-      "command": "fleet",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+```mermaid
+graph LR
+    Import["fleet secrets import"]
+    Set["fleet secrets set"]
 
-## Usage
+    Import --> Encrypt["age encrypt"]
+    Set --> Encrypt
 
-Fleet requires root for all commands except `mcp` and `install-mcp`.
+    Encrypt --> Vault["vault/*.age"]
+    Vault -->|"boot / fleet secrets unseal"| Decrypt["age decrypt"]
+    Decrypt --> Runtime["/run/fleet-secrets (tmpfs)"]
+    Runtime -->|"env_file / secrets"| Containers["Docker Containers"]
 
-```bash
-fleet <command> [options]
+    Runtime -->|"fleet secrets seal"| Encrypt
+    Vault -.->|"drift detection"| Runtime
 ```
 
-### App lifecycle
+Secrets are imported or set individually, encrypted with age, and stored in the vault. On boot (or manually), they are decrypted to a tmpfs mount that Docker containers reference. Sealing writes runtime changes back to the vault. Drift detection compares vault vs runtime to catch unsaved changes.
 
-```bash
-fleet deploy <app-dir>          # Register, build, and start (full pipeline)
-fleet add <app-dir>             # Register an existing app without deploying
-fleet remove <app>              # Stop, disable, and deregister
-fleet init                      # Auto-discover all existing apps on the server
+### Per-secret rotation (v1.6)
+
+Each secret carries metadata (`lastRotated`, `provider`, `strategy`) so fleet knows when it's stale and how to safely rotate it.
+
+```
+fleet secrets ages [<app>]            # what's stale, who owns it, when last rotated
+fleet secrets ages --motd             # MOTD-formatted summary
+fleet secrets motd-init               # install /etc/update-motd.d/99-fleet-secrets
+
+fleet secrets rotate <app> [<KEY>]    # interactive walkthrough, [--dry-run] [--no-restart]
+fleet secrets rollback <app>          # restore latest snapshot, [--to <ts>]
+fleet secrets snapshots <app>         # list available snapshots
+fleet secrets rotate-key              # legacy: rotate the AGE master key
 ```
 
-`deploy` is the primary command -- it registers the app if needed, runs `docker compose build`, and starts/restarts the systemd service.
+Rotation strategies (auto-detected from secret name, see `src/core/secrets-providers.ts`):
 
-### Service control
+| Strategy | Examples | Behaviour |
+|---|---|---|
+| `immediate` | `STRIPE_SECRET_KEY`, `GITHUB_TOKEN`, `OPENAI_API_KEY` | Replace value, old dies |
+| `dual-mode` | `JWT_SECRET`, `NEXTAUTH_SECRET`, `SESSION_SECRET` | New becomes primary, **old kept as `<NAME>_PREVIOUS`** so existing user sessions stay valid through grace period (your app must read both for verification) |
+| `at-rest-key` | `ENCRYPTION_KEY`, `FIELD_ENCRYPTION_KEY` | Refused unless `--data-migrated` passed (you must re-encrypt stored data first) |
+| `user-issued` | `USER_API_TOKEN`, `CUSTOMER_API_KEYS` | Refused — rotate per-user inside your app |
 
-```bash
-fleet start <app>               # Start via systemctl
-fleet stop <app>                # Stop via systemctl
-fleet restart <app>             # Restart via systemctl
-fleet logs <app> [-f]           # Container logs (follow mode with -f)
-```
+Safety rails on every rotation:
+- Pre-rotation snapshot to `vault/.snapshots/<app>-<ts>.env.age` (atomic copy+rename)
+- Hidden input prompt; new value never echoed in full (only `prefix…suffix (N chars)` for confirmation)
+- Format validation against provider regex (catches paste typos)
+- Entropy check rejects placeholders (`changeme`, `password`, all-same-char, < 8 chars)
+- Auto-rollback on any failure during reseal
+- Restart + 5s healthcheck gate after re-unseal; manual `fleet rollback` always available
+- Append-only audit log at `~/.local/share/fleet/audit.jsonl` (mode 0600, never logs values)
 
-### Monitoring
+### Log lifecycle (v1.6)
 
-```bash
-fleet status                    # Dashboard: all apps, systemd state, containers, health
-fleet list [--json]             # List registered apps
-fleet health [app]              # Health checks: systemd + container + HTTP
-fleet watchdog                  # Check all services, send Telegram alert on failure
+```
+fleet logs setup <app>                # interactive: retention/size/level
+fleet logs setup --all                # bulk default (7d / 100MB / info)
+fleet logs status [<app>]             # per-container size, driver, policy applied
+fleet logs prune <app>                # vacuum journald + truncate runaway json-file logs
+fleet logs <app> --since 30m --grep err --level warn   # filtered tail
 ```
 
-`watchdog` is designed to run on a cron schedule. It checks systemd unit status, container state, and HTTP health endpoints, then sends a Telegram alert if anything is unhealthy. Configure Telegram credentials at `/etc/fleet/telegram.json`:
+`fleet logs setup` writes `<composePath>/.fleet/logging.override.yml` with json-file driver options for rotation. To activate, include the override in your compose start command (or fleet's systemd unit).
 
-```json
-{
-  "botToken": "123456:ABC-DEF...",
-  "chatId": "-100..."
-}
-```
+MCP tools — all token-conservative with small defaults and `truncated` flags:
+- `fleet_logs_recent(app, lines=50, level=warn, sinceMinutes=15)` — bounded tail
+- `fleet_logs_summary(app, sinceMinutes=60)` — counts + top 10 distinct error messages
+- `fleet_logs_search(app, query, sinceMinutes=60, maxResults=20)` — bounded grep
+- `fleet_logs_status(app?)` — driver + size per container
+- `fleet_egress_snapshot(app)` — outbound destinations + violations
 
-### Dependency health
+### Egress observation (v1.6)
 
-```bash
-fleet deps [app]                    # Summary dashboard or per-app detail
-fleet deps scan                     # Run fresh dependency scan
-fleet deps fix <app> [--dry-run]    # Create PR for fixable dependency updates
-fleet deps config                   # Show/set configuration
-fleet deps ignore <pkg> --reason .. # Suppress a finding
-fleet deps init                     # Install cron + MOTD for automated scanning
+```
+fleet egress observe <app>            # snapshot current outbound flows via nsenter+ss
+fleet egress show <app>               # show config + allowlist
+fleet egress allow <app> <host>       # add to allowlist (supports *.host wildcards)
 ```
 
-Scans all registered apps for outdated packages (npm, Composer, pip), Docker image updates, runtime EOL warnings (via endoflife.date), security vulnerabilities (via OSV API), and open dependency PRs on GitHub. Results are cached and surfaced via CLI, MOTD on SSH login, and Telegram notifications. Runs automatically every 6 hours via cron (configurable).
+v1 is **observe-only** — it never blocks packets, so zero risk of breaking apps. Reads each container's network namespace via `nsenter` so it sees real container egress (not just host-side NAT'd flows). Reverse-resolves remote IPs to hostnames best-effort. RFC1918 destinations don't count as violations.
 
-### Nginx management
+`enforce` mode (actual default-deny via nftables) is deferred to a future phase — by design, it requires the operator to explicitly promote a shadow-clean app, never auto-promotes.
 
-```bash
-fleet nginx add <domain> --port <port> [--type proxy|spa|nextjs]
-fleet nginx remove <domain>
-fleet nginx list
+## Deployment Flow
+
+```mermaid
+graph TD
+    Deploy["fleet deploy app-dir"]
+    Deploy --> Register{"Already\nregistered?"}
+    Register -->|No| Add["Register app"]
+    Register -->|Yes| Build
+    Add --> Build["docker compose build"]
+    Build --> Start{"Service\nrunning?"}
+    Start -->|No| StartSvc["systemctl start"]
+    Start -->|Yes| Restart["systemctl restart"]
+    StartSvc --> Healthy["App deployed"]
+    Restart --> Healthy
 ```
 
-Generates an nginx server block, writes it to `/etc/nginx/sites-available/`, symlinks to `sites-enabled/`, tests the config, and reloads nginx. Supports three config types:
+## Boot Refresh
+
+On every systemd start — including reboots — Fleet pulls the latest code from GitHub and rebuilds the image if needed, before starting the container. The flow is entirely fail-safe: any failure at any step (dirty working tree, no remote, fetch error, non-fast-forward merge, build failure, or a 900-second wall-clock timeout) is logged and falls through to a plain `docker compose up` with the existing image. The container will always start.
 
-- **proxy** -- reverse proxy to a backend port (default)
-- **spa** -- static SPA with `try_files` fallback to `index.html`
-- **nextjs** -- Next.js-specific proxy with static asset handling
+**New commands**
 
-### Secrets management
+| Command | Description |
+|---------|-------------|
+| `fleet boot-start <app>` | Entry point systemd now invokes (`ExecStart`). Runs refresh then `docker compose up`. Not typically run by hand. |
+| `fleet rollback <app>` | Re-tags `<image>:fleet-previous` → `<image>:latest` and restarts the service. Fleet tags the previous image automatically before every build. |
+| `fleet patch-systemd` | Rewrites `ExecStart` in all installed unit files to use `fleet boot-start`, sets `TimeoutStartSec=900`, and backs up originals to `<path>.service.bak`. |
+| `fleet patch-systemd --rollback` | Restores all `.bak` unit files and runs `daemon-reload`. |
 
-Fleet uses [age](https://github.com/FiloSottile/age) encryption for secrets at rest. Each app's secrets (`.env` files or secret directories) are encrypted as `.age` files in the `vault/` directory. On boot, a systemd oneshot service decrypts everything to `/run/fleet-secrets/` (tmpfs -- never touches disk).
+**Kill switch**
+
+To disable boot refresh entirely — next `systemctl start` goes straight to `docker compose up`:
 
 ```bash
-fleet secrets init                          # Create age keypair, install unseal service
-fleet secrets import <app> [path]           # Import .env or secrets dir into vault
-fleet secrets export <app>                  # Print decrypted .env to stdout
-fleet secrets list [app]                    # Show managed secrets (masked values)
-fleet secrets set <app> <KEY> <VALUE>       # Set a single secret
-fleet secrets get <app> <KEY>               # Print a single decrypted value
-fleet secrets seal [app]                    # Re-encrypt from runtime back to vault
-fleet secrets unseal                        # Decrypt vault to /run/fleet-secrets/
-fleet secrets drift [app]                   # Detect vault vs runtime differences
-fleet secrets restore <app>                 # Restore vault from backup
-fleet secrets rotate                        # Generate new age key, re-encrypt everything
-fleet secrets validate [app]                # Check compose env vars vs vault keys
-fleet secrets status                        # Vault state, key counts, seal status
+sudo touch /etc/fleet/no-auto-refresh
 ```
 
-Two secret types are supported:
-- **env** -- `.env` files (key=value pairs), encrypted as `<app>.env.age`
-- **secrets-dir** -- directories of secret files (e.g. database passwords), encrypted as `<app>.secrets.age`
+Remove the file to re-enable.
 
-#### Vault safety features
+**Registry field: `lastBuiltCommit`**
 
-All seal operations are protected with:
-- **Automatic backups** -- vault files are backed up before any mutation
-- **Pre-seal validation** -- rejects seal if >50% of keys would be removed (protects against accidental wipes)
-- **Atomic rollback** -- backup is restored automatically if encryption fails
-- **Drift detection** -- compare vault (survives reboot) vs runtime (lost on reboot) to catch unsaved changes
+Each app in the registry stores the Git commit that was last built. Fleet sets this on `fleet deploy` and on every successful boot-refresh build. Boot refresh skips `docker compose build` when HEAD already matches this value, keeping boots fast when no code has changed.
 
-### Git and GitHub
+**First boot after upgrade**
 
-Fleet can onboard apps to GitHub and manage their full Git workflow. All GitHub operations use `gh` CLI over HTTPS.
+Any app with `lastBuiltCommit` unset will trigger a full rebuild the first time it boots after upgrading to this version. Expect a longer first boot for those apps.
 
-```bash
-fleet git status [app]                      # Git state for one or all apps
-fleet git onboard <app>                     # Create GitHub repo, push, protect branches
-fleet git onboard-all                       # Onboard all registered apps
-fleet git branch <app> <name> [--from dev]  # Create and push a feature branch
-fleet git commit <app> -m "msg"             # Stage and commit changes
-fleet git push <app>                        # Push current branch
-fleet git pr create <app> --title "..."     # Create a pull request
-fleet git pr list <app>                     # List open PRs
-fleet git release <app>                     # Create develop -> main release PR
-```
+**Recovery escape hatches**
 
-The `onboard` command handles everything: initialises git if needed, creates a private GitHub repo, pushes `main` and `develop` branches, and sets up branch protection rules.
+| Situation | Action |
+|-----------|--------|
+| One app misbehaving after a build | `fleet rollback <app>` |
+| Registry corrupted | Auto-loads `.bak` on next read |
+| Broad issue with boot-start behaviour | `sudo touch /etc/fleet/no-auto-refresh` |
+| Worst case — revert all unit files | `fleet patch-systemd --rollback` |
 
-### Global flags
+## MCP Server
 
-```
---json       Output as JSON (where supported)
---dry-run    Show what would happen without making changes
--y, --yes    Skip confirmation prompts
--v           Show version
--h           Show help
-```
+Fleet exposes 36 tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for AI-assisted server management. Run `fleet mcp` to start the stdio server, or install it into Claude Code:
 
-## MCP Server
+```bash
+sudo fleet install-mcp
+```
 
-Running `fleet mcp` starts a stdio-based [Model Context Protocol](https://modelcontextprotocol.io/) server. This exposes all fleet operations as tools that Claude Code (or any MCP client) can call.
-
-### Available tools (33)
-
-| Tool | Description |
-|------|-------------|
-| `fleet_status` | Dashboard data for all apps |
-| `fleet_list` | List registered apps with config |
-| `fleet_start` | Start an app via systemctl |
-| `fleet_stop` | Stop an app via systemctl |
-| `fleet_restart` | Restart an app via systemctl |
-| `fleet_logs` | Get container logs |
-| `fleet_health` | Run health checks for one/all apps |
-| `fleet_deploy` | Build and restart an app |
-| `fleet_nginx_add` | Create nginx config for a domain |
-| `fleet_nginx_list` | List nginx site configs |
-| `fleet_register` | Register a new app in the fleet registry |
-| `fleet_secrets_status` | Vault state and counts |
-| `fleet_secrets_list` | List secrets (masked values) |
-| `fleet_secrets_unseal` | Decrypt vault to runtime |
-| `fleet_secrets_validate` | Check compose env vars vs vault |
-| `fleet_secrets_set` | Set a single secret key/value |
-| `fleet_secrets_get` | Get a single decrypted value |
-| `fleet_secrets_seal` | Seal runtime changes back to vault |
-| `fleet_secrets_drift` | Detect vault vs runtime drift |
-| `fleet_secrets_restore` | Restore vault from backup |
-| `fleet_git_status` | Git state for one/all apps |
-| `fleet_git_onboard` | GitHub setup: repo, push, protect |
-| `fleet_git_branch` | Create and push a feature branch |
-| `fleet_git_commit` | Stage and commit changes |
-| `fleet_git_push` | Push current branch |
-| `fleet_git_pr_create` | Create a pull request |
-| `fleet_git_pr_list` | List pull requests |
-| `fleet_git_release` | Create develop -> main release PR |
-| `fleet_deps_status` | Dependency health summary from cache |
-| `fleet_deps_scan` | Run a fresh dependency scan |
-| `fleet_deps_app` | Dependency findings for a specific app |
-| `fleet_deps_fix` | Create PR with dependency updates (dry-run default) |
-| `fleet_deps_ignore` | Add an ignore rule for a finding |
-| `fleet_deps_config` | Get or set dependency monitoring config |
+Tools cover the full surface area: app lifecycle, secrets, nginx, Git, health checks, and dependency monitoring. See the [MCP documentation](https://fleet.hesketh.pro/mcp/) for the complete tool list.
 
 ## fleet-bot
 
-A Go Telegram bot (`bot/`) that provides remote server management through chat. It runs Claude Code sessions, giving Claude access to fleet's MCP tools for hands-free operations.
+A Go companion bot (`bot/`) that provides remote server management through Telegram or iMessage. It runs Claude Code sessions with access to fleet's MCP tools for hands-free operations.
 
-Built and deployed separately:
+See the [bot documentation](https://fleet.hesketh.pro/bot/setup/) for setup instructions.
 
-```bash
-cd bot
-make build
-sudo cp fleet-bot /usr/local/bin/
-sudo systemctl enable --now fleet-bot
-```
+## Self-update
 
-## Project structure
+When `fleet`'s TUI launches it does a non-blocking `git fetch` against `origin/develop`. If the local repo is behind, a banner appears under the header:
 
 ```
-src/
-├── index.ts                 Entry point (detects "mcp" arg)
-├── cli.ts                   CLI router and help text
-├── commands/                CLI command implementations
-│   ├── add.ts               Register an app
-│   ├── deploy.ts            Full deploy pipeline
-│   ├── deps.ts              Dependency health monitoring
-│   ├── git.ts               Git/GitHub operations
-│   ├── health.ts            Health checks
-│   ├── init.ts              Auto-discover apps
-│   ├── install-mcp.ts       Self-install as Claude Code MCP server
-│   ├── list.ts              List apps
-│   ├── logs.ts              Container logs
-│   ├── nginx.ts             Nginx management
-│   ├── remove.ts            Deregister app
-│   ├── restart.ts           Restart service
-│   ├── secrets.ts           Secrets vault management
-│   ├── start.ts             Start service
-│   ├── status.ts            Dashboard
-│   ├── stop.ts              Stop service
-│   └── watchdog.ts          Health monitor + Telegram alerts
-├── core/                    Core logic
-│   ├── docker.ts            Docker Compose operations
-│   ├── errors.ts            Error types
-│   ├── exec.ts              Shell execution helpers
-│   ├── git.ts               Git operations
-│   ├── git-onboard.ts       GitHub onboarding logic
-│   ├── github.ts            GitHub API via gh CLI
-│   ├── health.ts            Health check logic
-│   ├── nginx.ts             Nginx file operations
-│   ├── registry.ts          App registry (data/registry.json)
-│   ├── secrets.ts           Vault primitives (age encrypt/decrypt, backup/restore)
-│   ├── secrets-ops.ts       High-level secrets operations (safe seal, drift, validation)
-│   ├── secrets-validate.ts  Compose vs vault validation
-│   ├── systemd.ts           systemctl operations
-│   └── deps/                Dependency health (collectors, reporters, actors)
-├── mcp/
-│   ├── server.ts            MCP server setup + tool registration
-│   ├── git-tools.ts         Git-related MCP tools
-│   ├── secrets-tools.ts     Secrets MCP tools (set, get, seal, drift, restore)
-│   └── deps-tools.ts        Dependency monitoring MCP tools
-├── templates/
-│   ├── gitignore.ts         .gitignore generator
-│   ├── nginx.ts             Nginx config generator
-│   ├── systemd.ts           systemd unit generator
-│   └── unseal.ts            Unseal service generator
-└── ui/
-    ├── confirm.ts           Interactive confirmation
-    └── output.ts            Coloured terminal output
-
-bot/                         fleet-bot (Go Telegram bot)
-data/                        Runtime data (registry.json)
-vault/                       Encrypted secrets (*.age files)
+↑ Update available: 3 commits ahead — feat: ... Press U to install.
+```
+
+Pressing `U` runs `git pull --ff-only` then `npm run build` (refused if the working tree is dirty). The new binary is live for the next `fleet …` invocation. Recheck happens every 30 minutes for long-running TUI sessions.
+
+## Testing
+
+```bash
+npm test                     # unit + mocked tests (1106 passing)
+FLEET_INTEGRATION=1 npm test # also runs boot-refresh integration tests (1156 passing, 0 skipped)
 ```
 
+Set `FLEET_INTEGRATION=1` to opt into integration tests that hit real systemd / docker. Skipped by default in CI.
+
 ## Development
 
 ```bash
-npm run dev                  # Run with tsx (no build needed)
-npm run build                # Compile TypeScript to dist/
-npm test                     # Run tests with vitest
+git clone https://github.com/wrxck/fleet.git
+cd fleet
+npm install
+npm test          # vitest
+npm run build     # compile TypeScript to dist/
+npm run dev       # run with tsx (no build needed)
 ```
 
 ## License
 
-MIT
+MIT

package/dist/adapters/detector/index.d.ts

@@ -0,0 +1,8 @@
+import type { StackDetector } from '../types.js';
+export declare const nodeDetector: StackDetector;
+export declare const dockerDetector: StackDetector;
+export declare const pythonDetector: StackDetector;
+export declare const rustDetector: StackDetector;
+export declare const genericDetector: StackDetector;
+export declare const BUILT_IN_DETECTORS: readonly StackDetector[];
+export declare function detectStacks(repoPath: string, detectors?: readonly StackDetector[]): StackDetector['id'][];

package/dist/adapters/detector/index.js

@@ -0,0 +1,54 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const nodeDetector = {
+    id: 'node',
+    priority: 10,
+    detect(repoPath) {
+        return existsSync(join(repoPath, 'package.json'));
+    },
+};
+export const dockerDetector = {
+    id: 'docker',
+    priority: 20,
+    detect(repoPath) {
+        return (existsSync(join(repoPath, 'docker-compose.yml'))
+            || existsSync(join(repoPath, 'docker-compose.yaml'))
+            || existsSync(join(repoPath, 'Dockerfile')));
+    },
+};
+export const pythonDetector = {
+    id: 'python',
+    priority: 10,
+    detect(repoPath) {
+        return (existsSync(join(repoPath, 'pyproject.toml'))
+            || existsSync(join(repoPath, 'requirements.txt'))
+            || existsSync(join(repoPath, 'uv.lock')));
+    },
+};
+export const rustDetector = {
+    id: 'rust',
+    priority: 10,
+    detect(repoPath) {
+        return existsSync(join(repoPath, 'Cargo.toml'));
+    },
+};
+export const genericDetector = {
+    id: 'generic',
+    priority: 1,
+    detect() {
+        return true;
+    },
+};
+export const BUILT_IN_DETECTORS = Object.freeze([
+    dockerDetector,
+    nodeDetector,
+    pythonDetector,
+    rustDetector,
+    genericDetector,
+]);
+export function detectStacks(repoPath, detectors = BUILT_IN_DETECTORS) {
+    return detectors
+        .filter(d => d.detect(repoPath))
+        .sort((a, b) => b.priority - a.priority)
+        .map(d => d.id);
+}

package/dist/adapters/notifier/index.d.ts

@@ -0,0 +1,2 @@
+export { createStdoutNotifier } from './stdout.js';
+export { createWebhookNotifier, type WebhookOptions } from './webhook.js';

package/dist/adapters/notifier/index.js

@@ -0,0 +1,2 @@
+export { createStdoutNotifier } from './stdout.js';
+export { createWebhookNotifier } from './webhook.js';

package/dist/adapters/notifier/stdout.d.ts

@@ -0,0 +1,2 @@
+import type { NotifierAdapter } from '../types.js';
+export declare function createStdoutNotifier(): NotifierAdapter;

package/dist/adapters/notifier/stdout.js

@@ -0,0 +1,8 @@
+export function createStdoutNotifier() {
+    return {
+        id: 'stdout',
+        async notify(subject, body) {
+            process.stdout.write(`\n${subject}\n${body}\n`);
+        },
+    };
+}

package/dist/adapters/notifier/webhook.d.ts

@@ -0,0 +1,9 @@
+import type { NotifierAdapter } from '../types.js';
+export interface WebhookOptions {
+    url: string;
+    secret?: string;
+    headers?: Record<string, string>;
+    fetcher?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare function createWebhookNotifier(opts: WebhookOptions): NotifierAdapter;