@matthesketh/fleet 1.8.0 → 1.11.0

package/README.md

@@ -28,32 +28,43 @@ graph TD
     TUI["TUI Dashboard"]
     MCP["MCP Server"]
     BOT["fleet-bot (Go)"]
+    Explorer["Backup Explorer<br/>(browser)"]
 
     CLI --> Core
     TUI --> Core
     MCP --> Core
-    BOT -->|"via MCP"| Core
+    BOT -->|"MCP + exec"| Core
+    Explorer --> BackupCore["Backup core"]
 
-    subgraph Core["Core Modules"]
+    subgraph Core["Core modules"]
         Registry["Registry"]
         Docker["Docker Compose"]
         Systemd["systemd"]
         Nginx["nginx"]
-        Secrets["Secrets Vault"]
-        Health["Health Checks"]
+        Secrets["Secrets vault"]
+        Agent["Secrets agent v2<br/>(per-app socket)"]
+        Health["Health checks"]
         Git["Git / GitHub"]
-        Deps["Dependency Monitor"]
+        Deps["Dependency monitor"]
+        Routines["Routines<br/>(scheduled tasks)"]
+        BackupCore
+        Guard["Cloudflare guard"]
+        Mobile["Mobile (TestFlight + audit)"]
     end
 
     Docker --> Containers["Containers"]
-    Systemd --> Services["systemd Services"]
-    Nginx --> Proxy["Reverse Proxy"]
+    Systemd --> Services["systemd services"]
+    Nginx --> Proxy["Reverse proxy"]
     Secrets --> Vault["vault/*.age"]
     Secrets --> Runtime["/run/fleet-secrets"]
+    Agent --> Containers
     Health --> Alerts["Telegram / iMessage"]
+    BackupCore --> Restic["restic + age<br/>(off-host)"]
 ```
 
-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.
+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 either decrypted to a tmpfs on boot (v1) or served per-app over a Unix socket by the secrets agent (v2).
+
+Operator-specific identity (GitHub org, home dir, domain, username) lives in `data/operator.json` — gitignored, instance-local. Copy `data/operator.example.json` to seed it on a fresh install.
 
 ## Install
 
@@ -77,8 +88,24 @@ Requires Node.js 20+, Docker Compose v2, systemd, nginx, and [age](https://githu
 
 **Git workflows** -- Onboard apps to GitHub, manage branches, PRs, and releases from the CLI.
 
+**Off-host backups** -- `fleet backup` runs restic against an append-only REST backend with age-encrypted dumps for databases. Includes `schedule` for systemd-timer-driven recurring backups, `verify` / `integrity` for repository checks, and `serve` for a browser-based restore explorer.
+
+**Routines** -- `fleet routines` is a TUI for signal-based scheduled tasks (each routine has a target repo, a trigger condition, and a runner — claude-cli, shell, or mcp). `fleet routine-run --id <id>` is the headless entrypoint for systemd-timer units.
+
+**Mobile pipelines** -- `fleet testflight` dispatches the macOS build workflow and publishes to TestFlight; `fleet audit` runs an App Store Review Guidelines audit via greenlight.
+
+**Cloudflare guard** -- `fleet guard` installs a watchdog layer (cf-snapshot, dns-drift-watch, cert-expiry-watch, cf-audit-monitor) that detects unauthorised dashboard changes and DNS drift on protected zones.
+
 **Interactive dashboard** -- Run bare `fleet` to launch a full-screen TUI with real-time status.
 
+**Host preflight** -- `fleet doctor` checks every external requirement the rest of the tool assumes (`age`, `docker compose v2`, `systemd ≥ 240`, `node ≥ 20`), plus the registry, vault, operator config and orphaned-app detection. Run on any fresh server.
+
+**Self-update from the CLI** -- `fleet update [--check] [--channel prerelease]` is the non-TUI counterpart to the dashboard banner. Cron-able, ssh-friendly.
+
+**Operator config** -- `fleet config show / get <field> / set <field> <value>` and the one-liner `fleet whoami` keep `data/operator.json` (username + home + domain + github org) editable from the CLI.
+
+**Shell completions** -- `fleet completions bash | zsh | fish` emits a completion script driven from the command registry, so it stays accurate as the migration finishes.
+
 See the [CLI reference](https://fleet.hesketh.pro/cli/) for the complete command list.
 
 ## Secrets Flow
@@ -102,6 +129,16 @@ graph LR
 
 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.
 
+### Per-app secrets agent (v2, opt-in)
+
+The v1 model decrypts every app's secrets to `/run/fleet-secrets/<app>/`, which means any process on the host can read the tmpfs file. v2 replaces that with a per-app systemd-templated socket service:
+
+- Each app gets its own age keypair; the vault is encrypted to (admin + per-app) recipients.
+- `fleet-secrets-agent@<app>.service` runs under `DynamicUser=yes`, loads the per-app key via `LoadCredentialEncrypted`, and serves the decrypted env over a Unix socket at `/run/fleet-secrets/<app>.sock`.
+- Consumers (the container) fetch secrets via HTTP/1.1 over the socket. The [`@matthesketh/fleet-secrets-client`](https://www.npmjs.com/package/@matthesketh/fleet-secrets-client) package wraps that protocol for Node apps.
+- `fleet secrets migrate-v2 <app>` orchestrates the move: snapshot, generate per-app keypair, re-encrypt to the new recipient set, edit the compose file + app unit, swap, and auto-rollback on any failure.
+- `fleet secrets revert-v2 <app>` rolls back from a snapshot if you need to drop back to v1.
+
 ### 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.
@@ -166,6 +203,107 @@ v1 is **observe-only** — it never blocks packets, so zero risk of breaking app
 
 `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.
 
+## Backups (off-host)
+
+```
+fleet backup init                          # initialise the restic repository
+fleet backup register <app> [--paths …]    # tell fleet which paths and dbs to capture
+fleet backup register-all                  # bulk-register every known app
+fleet backup snapshot <app> [--tag …]      # take an on-demand snapshot
+fleet backup snapshot-all                  # one snapshot per registered app
+fleet backup list [<app>]                  # list snapshots, latest first
+fleet backup restore <app> --snap <id> --target <dir>
+fleet backup prune                         # apply retention policy
+fleet backup verify                        # restic check (data integrity)
+fleet backup integrity                     # repository integrity report
+fleet backup schedule <app> --cron "..."   # install a fleet-backup@<app>.timer unit
+fleet backup schedule-all                  # bulk-install timers from registered apps
+fleet backup unschedule <app>              # remove the timer
+fleet backup status [<app>]                # last-snapshot age, sizes, append-only state
+fleet backup serve --port <n>              # browser-based restore explorer (see below)
+fleet backup test                          # end-to-end snapshot+restore smoke
+```
+
+Snapshots go to a restic backend mounted with `append-only` mode so a compromised host can't delete history. Database dumps stream straight into the snapshot via `dumpFileSpawn`, never landing on disk in plaintext. Backups are encrypted twice — restic at rest, plus per-app age encryption inside the snapshot for anything classified as sensitive.
+
+### Restore explorer
+
+`fleet backup serve --port 7300` starts a localhost-bound HTTP service designed to live behind nginx. It serves:
+
+- a read-only status dashboard at `/backups` showing the latest snapshot per app and any retention lag
+- a tree explorer at `/backups/explore` for browsing snapshot contents
+- a per-file streaming endpoint that pipes `restic dump` straight to the browser
+- a one-click restore into a fresh timestamped staging dir under `/var/restore`
+
+Authentication is **TOTP only** — paste the secret into your authenticator app on setup (`fleet backup setup-totp`). Sessions are signed cookies (`fleet_backup_session`), `Secure; HttpOnly; SameSite=Strict; Path=/backups`. Sensitive paths (`.env`, age keys, private SSH keys) are classified server-side and refuse view/download regardless of who's logged in.
+
+CSRF posture: every `/api/*` request must carry `x-fleet-backup: 1` (a custom header browsers can't set cross-origin without preflight), and write methods (POST / DELETE) must additionally carry an `Origin` header whose host matches the deployment domain exactly. Read methods tolerate a missing `Origin` so curl probes still work.
+
+## Routines
+
+`fleet routines` is a TUI for signal-based scheduled tasks. Each routine has:
+
+- a **target repo** the routine operates against
+- a **trigger condition** (signals: open issues count, failing checks, branch ahead of remote, custom git-clean signal, scheduled, manual)
+- a **runner**: `claude-cli` (drives a Claude Code session), `shell` (just runs a script), or `mcp-call` (invokes one MCP tool)
+- a **schema** that validates inputs before the runner sees them
+
+Routines run from a systemd-timer-driven service called `fleet-routine@<id>.timer` — fleet ships the templates and `fleet routine-run --id <id>` is the headless entrypoint that timer fires. The TUI shows a signals grid (which routines are gated on what), a routine list, and per-routine run history.
+
+```
+fleet routines                                   # interactive TUI
+fleet routine-run --id <id> [--target <repo>] [--trigger scheduled] [--json]
+```
+
+The claude-cli runner serialises through a `proper-lockfile` mutex so two routines targeting the same repo can't race each other, and respects an abort signal so a `systemctl stop` cleans up mid-run rather than orphaning a child process.
+
+## Mobile pipelines
+
+For iOS/macOS apps, fleet drives both the build pipeline and the App Store compliance check.
+
+### TestFlight publishing
+
+```
+fleet testflight publish <app>              # dispatch the macOS build workflow to TestFlight
+fleet testflight builds <app>               # list TestFlight builds for the app
+fleet testflight update <app> --build <id> --whats-new "..."
+fleet testflight delete <app> --build <id>  # expire a TestFlight build
+fleet testflight doctor <app>               # check gh + App Store Connect credentials
+```
+
+The publish flow goes through a GitHub Actions macOS runner — fleet dispatches the workflow with the app's bundle ID and version, then polls until the build appears in App Store Connect. Auth uses an API key (issuer + key ID + p8) loaded via a fleet-managed secret.
+
+### App Store compliance audit
+
+```
+fleet audit [target]                        # run greenlight against a mobile project
+fleet audit guidelines                      # browse App Store Review Guidelines (list/show/search)
+fleet audit doctor                          # check the greenlight binary is installed
+fleet audit ignore "<title>" --reason "..." # suppress a greenlight false positive
+fleet audit ignores                         # list audit ignore rules
+```
+
+Greenlight runs a corpus of App Store Review Guideline checks against the project source. Findings classified as "confirmed false positive" are suppressed via the ignore list so the next run is noise-free; everything else fails the audit. Useful as a pre-flight before each TestFlight publish.
+
+## Cloudflare guard
+
+`fleet guard` installs a watchdog layer that detects unauthorised dashboard changes and DNS drift on protected Cloudflare zones.
+
+```
+sudo fleet guard install                    # install scripts + cron + log rotation
+fleet guard status                          # show what's protected and the last check time
+fleet guard approve <change-id>             # acknowledge a flagged change as intentional
+fleet guard reject <change-id>              # treat a flagged change as compromise
+```
+
+Components installed under `/usr/local/sbin`:
+
+- **`cf-snapshot`** — periodic snapshot of the Cloudflare zone configuration (DNS, page rules, WAF settings) to `/var/lib/cf-snapshots/`
+- **`cf-audit-monitor`** — diffs the latest snapshot against the previous and surfaces unauthorised changes for operator approval
+- **`dns-drift-watch`** — detects when DNS records drift from the snapshot (cron, alerts via the same channels as `fleet watchdog`)
+- **`cert-expiry-watch`** — flags certs approaching expiry across all protected hosts
+- **`fleet-guard` / `fleet-guard-execute`** — the orchestrator + executor pair, run as the `fleet-guard` system user with no shell
+
 ## Deployment Flow
 
 ```mermaid
@@ -224,7 +362,7 @@ Any app with `lastBuiltCommit` unset will trigger a full rebuild the first time
 
 ## MCP Server
 
-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:
+Fleet exposes 50+ tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for AI-assisted server management — the static surface (server.ts + git / secrets / deps / audit / testflight tool families) plus every migrated registry command exposed through the registry bridge. Run `fleet mcp` to start the stdio server, or install it into Claude Code:
 
 ```bash
 sudo fleet install-mcp
@@ -240,19 +378,48 @@ See the [bot documentation](https://fleet.hesketh.pro/bot/setup/) for setup inst
 
 ## Self-update
 
-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:
+When `fleet`'s TUI launches it does a non-blocking `git fetch` against the configured update channel and compares HEAD to that remote branch. If the local repo is behind, a banner appears under the header:
 
 ```
 ↑ 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.
+Pressing `U` runs `git pull --ff-only origin <channel-branch>` 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.
+
+**Channels**
+
+| channel | tracks | who it's for |
+|---|---|---|
+| `stable` (default) | `origin/main` — tagged releases only | everyone |
+| `prerelease` | `origin/develop` — work in flight, may break | operators willing to canary |
+
+Opt into prerelease for the current process:
+
+```bash
+FLEET_UPDATE_CHANNEL=prerelease fleet
+```
+
+Or persist it (e.g. in `~/.bashrc` or the systemd unit's `Environment=`):
+
+```bash
+export FLEET_UPDATE_CHANNEL=prerelease
+```
+
+When the banner is on the prerelease channel it labels itself `↑ Update available (prerelease): …` so you can tell at a glance.
+
+**Escape hatch — track an arbitrary branch**
+
+For forks or release branches, `FLEET_UPDATE_BRANCH=<name>` overrides the channel entirely:
+
+```bash
+FLEET_UPDATE_BRANCH=release/2026.q3 fleet
+```
 
 ## Testing
 
 ```bash
-npm test                     # unit + mocked tests (1106 passing)
-FLEET_INTEGRATION=1 npm test # also runs boot-refresh integration tests (1156 passing, 0 skipped)
+npm test                     # unit + mocked tests (~1720 passing)
+FLEET_INTEGRATION=1 npm test # also runs boot-refresh + secrets-v2 integration tests
 ```
 
 Set `FLEET_INTEGRATION=1` to opt into integration tests that hit real systemd / docker. Skipped by default in CI.
@@ -263,11 +430,14 @@ Set `FLEET_INTEGRATION=1` to opt into integration tests that hit real systemd /
 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)
+npm test                 # vitest
+npm run build            # compile TypeScript to dist/
+npm run dev              # run with tsx (no build needed)
+npm run changelog        # regenerate CHANGELOG.md from git tags
 ```
 
+See [CHANGELOG.md](./CHANGELOG.md) for the release history (auto-generated from tags; the GitHub releases page has extra context). The `npm run changelog` script regenerates it after a tag bump.
+
 ## License
 
 MIT

package/dist/bin/fleet-agent.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/fleet-agent.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../core/secrets-v2.js';
+main(process.argv.slice(2)).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[fleet-agent] fatal: ${message}\n`);
+    process.exit(1);
+});

package/dist/cli.d.ts

@@ -1 +1,6 @@
+/**
+ * resolves a command from the registry and runs it. returns true when handled,
+ * false when the name is unknown (so run() falls through to the legacy switch).
+ */
+export declare function dispatchRegistryCommand(command: string, rest: string[], write?: (s: string) => void): Promise<boolean>;
 export declare function run(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -1,29 +1,23 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { statusCommand } from './commands/status.js';
-import { listCommand } from './commands/list.js';
-import { startCommand } from './commands/start.js';
-import { stopCommand } from './commands/stop.js';
-import { restartCommand } from './commands/restart.js';
+import { loadRegistry } from './registry/index.js';
+import { getCommand } from './registry/registry.js';
+import { parseArgs } from './registry/parse-args.js';
+import { renderToText } from './registry/render.js';
+import { makeCliContext } from './registry/context.js';
 import { logsCommand } from './commands/logs.js';
 import { egressCommand } from './commands/egress.js';
-import { healthCommand } from './commands/health.js';
-import { addCommand } from './commands/add.js';
-import { removeCommand } from './commands/remove.js';
 import { deployCommand } from './commands/deploy.js';
 import { nginxCommand } from './commands/nginx.js';
 import { secretsCommand } from './commands/secrets.js';
 import { gitCommand } from './commands/git.js';
-import { initCommand } from './commands/init.js';
 import { depsCommand } from './commands/deps.js';
+import { auditCommand } from './commands/audit.js';
+import { testflightCommand } from './commands/testflight.js';
 import { watchdogCommand } from './commands/watchdog.js';
-import { installMcpCommand } from './commands/install-mcp.js';
-import { patchSystemdCommand } from './commands/patch-systemd.js';
-import { freezeCommand, unfreezeCommand } from './commands/freeze.js';
 import { guardCommand } from './commands/guard.js';
-import { bootStartCommand } from './commands/boot-start.js';
-import { rollbackCommand } from './commands/rollback.js';
+import { backupCommand } from './commands/backup.js';
 import { routineRunCommand } from './commands/routine-run.js';
 import { routinesCommand } from './commands/routines.js';
 import { startMcpServer } from './mcp/server.js';
@@ -50,6 +44,16 @@ Commands:
   deps config         Show/set configuration
   deps ignore <pkg>   Suppress a finding
   deps init           Install cron + MOTD for automated scanning
+  audit [target]      App Store compliance audit of a mobile project (greenlight)
+  audit guidelines    Browse Apple App Store Review Guidelines (list|show|search)
+  audit doctor        Check the greenlight binary is installed
+  audit ignore "<title>" --reason "..."  Suppress a greenlight false positive
+  audit ignores       List audit ignore rules
+  testflight publish <app>     Dispatch the macOS build workflow to TestFlight
+  testflight builds <app>      List TestFlight builds
+  testflight update <app> --build <id> --whats-new "..."  Set test notes
+  testflight delete <app> --build <id>   Expire a TestFlight build
+  testflight doctor <app>      Check gh + App Store Connect credentials
   add <app-dir>       Register existing app
   remove <app>        Stop, disable, deregister
   nginx add <domain> --port <port> [--type proxy|spa|nextjs]
@@ -91,6 +95,14 @@ Commands:
   rollback <app>      Roll back app to previous image
   unfreeze <app>      Unfreeze and restart a frozen service
   guard <subcommand>  Cloudflare protection layer (install/status/approve/reject/...)
+  backup <subcommand> Encrypted off-host backups via restic + age (init/snapshot/list/restore/...)
+  update [--check] [--channel stable|prerelease] [--branch <name>]
+                      Self-update fleet (check / apply, channel selectable)
+  doctor              Preflight: host requirements, registry, vault, operator config, orphans
+  config [show|get|set] [<field>] [<value>]
+                      Show or update the operator identity (data/operator.json)
+  whoami              Print operator identity in one line
+  completions <shell> Emit shell completion script (bash | zsh | fish)
 
 Global flags:
   --json              Output as JSON
@@ -99,6 +111,45 @@ Global flags:
   -v, --version       Show version
   -h, --help          Show this help
 `;
+/**
+ * resolves a command from the registry and runs it. returns true when handled,
+ * false when the name is unknown (so run() falls through to the legacy switch).
+ */
+export async function dispatchRegistryCommand(command, rest, write = s => process.stdout.write(s)) {
+    loadRegistry();
+    const def = getCommand(command);
+    if (!def)
+        return false;
+    // --json is an output flag for the registry dispatch path — handled here,
+    // not a per-command argument, so it is stripped before the schema parse
+    // would reject it as unknown. legacy (non-registry) commands that still
+    // live in the switch below parse --json themselves.
+    const jsonMode = rest.includes('--json');
+    const cmdArgs = rest.filter(arg => arg !== '--json');
+    const parsed = parseArgs(def.args, cmdArgs);
+    if (parsed.help) {
+        // minimal help for now — one-line summary; richer per-command help is future work.
+        write(`${def.name} — ${def.summary}\n`);
+        return true;
+    }
+    if (!parsed.ok) {
+        process.stderr.write(`error: ${parsed.error}\n`);
+        process.exitCode = 1;
+        return true;
+    }
+    const result = await def.run(parsed.values, makeCliContext());
+    if (jsonMode) {
+        write(JSON.stringify(result.data, null, 2) + '\n');
+    }
+    else {
+        if (result.render)
+            write(renderToText(result.render) + '\n');
+        write(result.summary + '\n');
+    }
+    if (!result.ok)
+        process.exitCode = 1;
+    return true;
+}
 export async function run(argv) {
     const args = argv.slice(2);
     const command = args[0];
@@ -115,40 +166,31 @@ export async function run(argv) {
         const { launchTui } = await import('./tui/app.js');
         return launchTui();
     }
-    // Commands that require root privileges
+    // commands that require root privileges
     const ROOT_COMMANDS = new Set([
         'start', 'stop', 'restart', 'deploy', 'freeze', 'unfreeze',
-        'nginx', 'secrets', 'patch-systemd', 'init', 'watchdog',
+        'nginx', 'secrets', 'patch-systemd', 'init', 'watchdog', 'backup',
+        'testflight',
     ]);
     if (ROOT_COMMANDS.has(command) && process.getuid && process.getuid() !== 0) {
         error(`'fleet ${command}' requires root privileges. Run with sudo.`);
         process.exit(1);
     }
+    if (await dispatchRegistryCommand(command, rest))
+        return;
     switch (command) {
-        case 'status': return statusCommand(rest);
-        case 'list': return listCommand(rest);
-        case 'start': return startCommand(rest);
-        case 'stop': return stopCommand(rest);
-        case 'restart': return restartCommand(rest);
         case 'logs': return logsCommand(rest);
         case 'egress': return egressCommand(rest);
-        case 'health': return healthCommand(rest);
         case 'deps': return depsCommand(rest);
-        case 'add': return addCommand(rest);
-        case 'remove': return removeCommand(rest);
+        case 'audit': return auditCommand(rest);
+        case 'testflight': return testflightCommand(rest);
         case 'deploy': return deployCommand(rest);
         case 'nginx': return nginxCommand(rest);
         case 'secrets': return secretsCommand(rest);
         case 'git': return gitCommand(rest);
-        case 'init': return initCommand(rest);
         case 'watchdog': return watchdogCommand(rest);
-        case 'install-mcp': return installMcpCommand(rest);
-        case 'patch-systemd': return patchSystemdCommand(rest);
-        case 'boot-start': return bootStartCommand(rest);
-        case 'freeze': return freezeCommand(rest);
-        case 'rollback': return rollbackCommand(rest);
-        case 'unfreeze': return unfreezeCommand(rest);
         case 'guard': return guardCommand(rest);
+        case 'backup': return backupCommand(rest);
         case 'mcp': return startMcpServer();
         case 'tui':
         case 'dashboard': {

package/dist/commands/add.d.ts

@@ -1 +1,2 @@
-export declare function addCommand(args: string[]): Promise<void>;
+import type { AppEntry } from '../core/registry.js';
+export declare const addCommand: import("../registry/types.js").CommandDef<AppEntry | null>;

package/dist/commands/add.js

@@ -1,53 +1,53 @@
 import { existsSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
-import { load, save, addApp } from '../core/registry.js';
+import { z } from 'zod';
+import { addApp, withRegistry } from '../core/registry.js';
 import { getContainersByCompose } from '../core/docker.js';
 import { installServiceFile, readServiceFile, enableService } from '../core/systemd.js';
 import { generateServiceFile } from '../templates/systemd.js';
-import { FleetError } from '../core/errors.js';
-import { success, info, error, warn } from '../ui/output.js';
-import { confirm } from '../ui/confirm.js';
-export async function addCommand(args) {
-    const dryRun = args.includes('--dry-run');
-    const yes = args.includes('-y') || args.includes('--yes');
-    const appDir = args.find(a => !a.startsWith('-'));
-    if (!appDir) {
-        error('Usage: fleet add <app-dir>');
-        process.exit(1);
-    }
-    const fullPath = resolve(appDir);
-    if (!existsSync(fullPath)) {
-        throw new FleetError(`Directory not found: ${fullPath}`);
-    }
-    const composePath = findComposePath(fullPath);
-    if (!composePath.path) {
-        throw new FleetError(`No docker-compose.yml found in ${fullPath} or ${fullPath}/server`);
-    }
-    const name = basename(fullPath).toLowerCase().replace(/[^a-z0-9-]/g, '-');
-    const existingService = readServiceFile(name);
-    const hasService = existingService !== null;
-    info(`Registering ${name} from ${fullPath}`);
-    info(`Compose path: ${composePath.path}`);
-    info(`Compose file: ${composePath.file ?? 'default'}`);
-    const containers = getContainersByCompose(composePath.path, composePath.file);
-    info(`Found containers: ${containers.join(', ') || 'none running'}`);
-    const app = {
-        name,
-        displayName: name,
-        composePath: composePath.path,
-        composeFile: composePath.file,
-        serviceName: name,
-        domains: [],
-        port: null,
-        usesSharedDb: false,
-        type: 'service',
-        containers: containers.length > 0 ? containers : [name],
-        dependsOnDatabases: false,
-        registeredAt: new Date().toISOString(),
-    };
-    if (!hasService) {
-        info('No systemd service file found');
-        if (!dryRun && (yes || await confirm('Create systemd service file?'))) {
+import { assertComposeFile } from '../core/validate.js';
+import { defineCommand } from '../registry/registry.js';
+export const addCommand = defineCommand({
+    name: 'add',
+    summary: 'Register an existing app',
+    args: z.object({
+        dir: z.string(),
+        'dry-run': z.boolean().default(false),
+        yes: z.boolean().default(false),
+    }),
+    async run(args, ctx) {
+        const fullPath = resolve(args.dir);
+        if (!existsSync(fullPath)) {
+            return { ok: false, summary: `directory not found: ${fullPath}`, data: null };
+        }
+        const composePath = findComposePath(fullPath);
+        if (!composePath.path) {
+            return { ok: false, summary: `no docker-compose.yml found in ${fullPath} or ${fullPath}/server`, data: null };
+        }
+        const name = basename(fullPath).toLowerCase().replace(/[^a-z0-9-]/g, '-');
+        const hasService = readServiceFile(name) !== null;
+        ctx.log({ level: 'info', message: `registering ${name} from ${fullPath}` });
+        const containers = getContainersByCompose(composePath.path, composePath.file);
+        const app = {
+            name,
+            displayName: name,
+            composePath: composePath.path,
+            composeFile: composePath.file,
+            serviceName: name,
+            domains: [],
+            port: null,
+            usesSharedDb: false,
+            type: 'service',
+            containers: containers.length > 0 ? containers : [name],
+            dependsOnDatabases: false,
+            registeredAt: new Date().toISOString(),
+        };
+        const dryRun = args['dry-run'];
+        if (!hasService && !dryRun && (args.yes || (await ctx.confirm('Create systemd service file?')))) {
+            // defence-in-depth: validate the compose filename before interpolating
+            // it into the generated systemd unit.
+            if (composePath.file)
+                assertComposeFile(composePath.file);
             const content = generateServiceFile({
                 serviceName: name,
                 description: `${name} Docker Service`,
@@ -57,21 +57,28 @@ export async function addCommand(args) {
             });
             installServiceFile(name, content);
             enableService(name);
-            success(`Created and enabled ${name}.service`);
+            ctx.log({ level: 'info', message: `created and enabled ${name}.service` });
         }
-    }
-    else {
-        info('Existing systemd service file found');
-    }
-    if (dryRun) {
-        warn('Dry run - no changes saved');
-        process.stdout.write(JSON.stringify(app, null, 2) + '\n');
-        return;
-    }
-    const reg = load();
-    save(addApp(reg, app));
-    success(`Registered ${name}`);
-}
+        if (dryRun) {
+            return {
+                ok: true,
+                summary: `dry run — ${name} not registered`,
+                data: app,
+                render: {
+                    kind: 'keyValue',
+                    pairs: [
+                        ['name', app.name],
+                        ['composePath', app.composePath],
+                        ['composeFile', app.composeFile ?? '(default)'],
+                        ['containers', app.containers.join(', ')],
+                    ],
+                },
+            };
+        }
+        await withRegistry(reg => addApp(reg, app));
+        return { ok: true, summary: `registered ${name}`, data: app };
+    },
+});
 function findComposePath(dir) {
     if (existsSync(`${dir}/docker-compose.yml`)) {
         return { path: dir, file: null };

package/dist/commands/audit.d.ts

@@ -0,0 +1 @@
+export declare function auditCommand(args: string[]): Promise<void>;