@matthesketh/fleet 1.1.0 → 1.6.0

package/dist/core/egress.js

@@ -0,0 +1,161 @@
+/**
+ * Egress observation: see where each app's containers are talking to.
+ *
+ * v1 = snapshot mode. Reads conntrack via `ss -tn` filtered by container IPs,
+ * resolves remote IPs to hostnames best-effort, returns the deduplicated set.
+ *
+ * v2 (Phase E) = continuous shadow daemon (eBPF-based or nftables LOG target),
+ * with persistent observed-set storage and a real `enforce` mode that drops
+ * packets to non-allowlisted destinations. Design intentionally matches v1's
+ * data shape so the upgrade is non-breaking.
+ */
+import { execSafe } from './exec.js';
+/** Container PID for entering its network namespace. Returns 0 if not running. */
+function containerPid(container) {
+    const r = execSafe('docker', ['inspect', '--format={{.State.Pid}}', container]);
+    if (!r.ok)
+        return 0;
+    return parseInt(r.stdout.trim(), 10) || 0;
+}
+/** Run `ss -tnH` inside a container's network namespace. Requires sudo (nsenter
+ * needs CAP_SYS_ADMIN). Returns empty string if the call fails. */
+function nsenterSs(pid) {
+    const r = execSafe('nsenter', ['-t', String(pid), '-n', 'ss', '-tnH']);
+    if (r.ok)
+        return r.stdout;
+    // Fall back to sudo (fleet might be running unprivileged)
+    const s = execSafe('sudo', ['-n', 'nsenter', '-t', String(pid), '-n', 'ss', '-tnH']);
+    return s.ok ? s.stdout : '';
+}
+/** Reverse-lookup an IP → hostname. Best-effort, short timeout. */
+function reverseLookup(ip) {
+    // Try `getent hosts` first (uses /etc/hosts + resolver)
+    const r = execSafe('getent', ['hosts', ip]);
+    if (r.ok && r.stdout.trim()) {
+        const parts = r.stdout.trim().split(/\s+/);
+        if (parts[1])
+            return parts[1];
+    }
+    // Fall back to `dig +short -x`
+    const dig = execSafe('dig', ['+short', '+time=1', '+tries=1', '-x', ip]);
+    if (dig.ok && dig.stdout.trim()) {
+        return dig.stdout.trim().replace(/\.$/, '').split('\n')[0];
+    }
+    return null;
+}
+const RFC1918 = [/^10\./, /^192\.168\./, /^172\.(1[6-9]|2[0-9]|3[01])\./, /^127\./, /^169\.254\./, /^::1$/, /^fe80:/];
+function isPrivate(ip) {
+    return RFC1918.some(r => r.test(ip));
+}
+/**
+ * Read all current outbound TCP/UDP flows from the host using `ss -tnp`,
+ * filter to those whose SOURCE matches one of the app's container IPs.
+ * Connections to private addresses are kept (they may indicate intra-host
+ * leaks) but flagged differently.
+ */
+export function snapshotEgress(app) {
+    const allFlows = [];
+    const allow = new Set(app.egress?.allow ?? []);
+    for (const ct of app.containers) {
+        const pid = containerPid(ct);
+        if (pid === 0)
+            continue;
+        const out = nsenterSs(pid);
+        if (!out)
+            continue;
+        for (const line of out.split('\n')) {
+            const cols = line.trim().split(/\s+/);
+            if (cols.length < 5)
+                continue;
+            const peer = cols[4];
+            const peerMatch = peer.match(/^(.+):(\d+)$/);
+            if (!peerMatch)
+                continue;
+            const remoteIp = peerMatch[1].replace(/^\[|\]$/g, '');
+            const remotePort = parseInt(peerMatch[2], 10);
+            // Skip listeners back to ourselves and intra-pod chatter
+            if (isPrivate(remoteIp) && (remoteIp === '127.0.0.1' || remoteIp === '::1'))
+                continue;
+            const host = reverseLookup(remoteIp) ?? remoteIp;
+            const remote = `${host}:${remotePort}`;
+            const allowed = allowMatches(allow, remote, host, remoteIp, remotePort);
+            allFlows.push({ app: app.name, container: ct, remote, remoteIp, remotePort, allowed });
+        }
+    }
+    if (allFlows.length === 0) {
+        return { takenAt: new Date().toISOString(), app: app.name, flows: [], uniqueRemotes: [], violations: [] };
+    }
+    const uniq = Array.from(new Set(allFlows.map(f => f.remote))).sort();
+    const violations = uniq.filter(r => {
+        const flow = allFlows.find(f => f.remote === r);
+        return flow ? !flow.allowed && !isPrivate(flow.remoteIp) : false;
+    });
+    return {
+        takenAt: new Date().toISOString(),
+        app: app.name,
+        flows: allFlows,
+        uniqueRemotes: uniq,
+        violations,
+    };
+}
+/**
+ * Match a destination against the allowlist. Supported entry forms:
+ *   exact-host:port          api.stripe.com:443
+ *   bare-host (any port)     api.stripe.com
+ *   bare-ip / ip:port        1.2.3.4 / 1.2.3.4:443
+ *   wildcard host            *.stripe.com           (also matches the bare apex)
+ *   wildcard host + port     *.stripe.com:443
+ *   bare host + glob port    api.stripe.com:*
+ *
+ * SECURITY NOTE: `host` is the result of a reverse-DNS lookup. An attacker
+ * who controls the reverse DNS for an IP they own can return whatever
+ * hostname they like. The IP-based allow forms (`ip`, `ip:port`) are the
+ * only trustworthy way to allow a destination by name; use them when the
+ * remote endpoint isn't under cloudflare/etc. Hostname-based entries are
+ * provided for ergonomics only — verify forward+reverse if you need to be
+ * adversarial about it.
+ */
+function allowMatches(allow, remote, host, ip, port) {
+    if (allow.size === 0)
+        return false;
+    // IP-based (always trustworthy):
+    if (allow.has(ip))
+        return true;
+    if (allow.has(`${ip}:${port}`))
+        return true;
+    // Hostname-based (trust depends on PTR record — see note above):
+    if (allow.has(remote))
+        return true; // exact host:port
+    if (allow.has(host))
+        return true; // bare host, any port
+    if (allow.has(`${host}:*`))
+        return true; // host with glob port
+    for (const a of allow) {
+        // Wildcard host without port: '*.stripe.com'
+        if (a.startsWith('*.') && !a.includes(':')) {
+            const suffix = a.slice(1); // '.stripe.com'
+            const apex = a.slice(2); // 'stripe.com'
+            if (host === apex || host.endsWith(suffix))
+                return true;
+        }
+        // Wildcard host WITH port: '*.stripe.com:443'
+        if (a.startsWith('*.') && a.includes(':')) {
+            const colon = a.lastIndexOf(':');
+            const wildHost = a.slice(0, colon); // '*.stripe.com'
+            const wildPort = a.slice(colon + 1);
+            if (parseInt(wildPort, 10) !== port)
+                continue;
+            const suffix = wildHost.slice(1);
+            const apex = wildHost.slice(2);
+            if (host === apex || host.endsWith(suffix))
+                return true;
+        }
+    }
+    return false;
+}
+export function addEgressAllow(app, host) {
+    const cur = new Set(app.egress?.allow ?? []);
+    cur.add(host);
+    app.egress = { ...(app.egress ?? {}), allow: Array.from(cur).sort() };
+    return app.egress.allow;
+}

package/dist/core/exec.d.ts

@@ -4,10 +4,16 @@ export interface ExecResult {
     exitCode: number;
     ok: boolean;
 }
-export declare function exec(cmd: string, opts?: {
+export declare function execSafe(cmd: string, args: string[], opts?: {
     timeout?: number;
     cwd?: string;
     env?: Record<string, string>;
+    input?: string;
+}): ExecResult;
+export declare function execGit(args: string[], opts: {
+    cwd: string;
+    timeout?: number;
+    env?: Record<string, string>;
 }): ExecResult;
 export declare function execLive(cmd: string, args: string[], opts?: {
     cwd?: string;

package/dist/core/exec.js

@@ -1,24 +1,32 @@
-import { execSync, spawnSync } from 'node:child_process';
-export function exec(cmd, opts = {}) {
-    try {
-        const stdout = execSync(cmd, {
-            timeout: opts.timeout ?? 30_000,
-            cwd: opts.cwd,
-            env: opts.env ? { ...process.env, ...opts.env } : undefined,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        return { stdout: stdout.trim(), stderr: '', exitCode: 0, ok: true };
-    }
-    catch (err) {
-        const e = err;
+import { spawnSync } from 'node:child_process';
+export function execSafe(cmd, args, opts = {}) {
+    const result = spawnSync(cmd, args, {
+        timeout: opts.timeout ?? 30_000,
+        cwd: opts.cwd,
+        env: opts.env ? { ...process.env, ...opts.env } : undefined,
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        input: opts.input,
+    });
+    if (result.error) {
         return {
-            stdout: (e.stdout ?? '').toString().trim(),
-            stderr: (e.stderr ?? '').toString().trim(),
-            exitCode: e.status ?? 1,
+            stdout: '',
+            stderr: result.error.message,
+            exitCode: 1,
             ok: false,
         };
     }
+    return {
+        stdout: (result.stdout ?? '').trim(),
+        stderr: (result.stderr ?? '').trim(),
+        exitCode: result.status ?? 1,
+        ok: result.status === 0,
+    };
+}
+export function execGit(args, opts) {
+    // Prepend -c safe.directory=<cwd> so git under root can operate on repos owned by other users.
+    // This is scoped to the one command — does not mutate global git config.
+    return execSafe('git', ['-c', `safe.directory=${opts.cwd}`, ...args], opts);
 }
 export function execLive(cmd, args, opts = {}) {
     const result = spawnSync(cmd, args, {

package/dist/core/git.d.ts

@@ -26,6 +26,7 @@ export declare function branchExists(cwd: string, branch: string): boolean;
 export declare function getProjectRoot(composePath: string): string;
 export declare function gitInit(cwd: string): void;
 export declare function gitAdd(cwd: string, paths?: string[]): void;
+export declare function gitAddTracked(cwd: string): void;
 export declare function gitCommit(cwd: string, message: string): void;
 export declare function gitCheckout(cwd: string, branch: string, create?: boolean): void;
 export declare function gitPush(cwd: string, branch: string, setUpstream?: boolean): void;

package/dist/core/git.js

@@ -1,17 +1,19 @@
 import { existsSync, writeFileSync, readFileSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
-import { exec } from './exec.js';
+import { execGit } from './exec.js';
 import { GitError } from './errors.js';
 import { detectProjectType, generateGitignore } from '../templates/gitignore.js';
-const SSH_AGENT_SOCK = '/tmp/fleet-ssh-agent.sock';
-if (existsSync(SSH_AGENT_SOCK)) {
+import { assertBranch, assertFilePath } from './validate.js';
+// Use SSH_AUTH_SOCK from environment, or check for fleet-specific socket
+const SSH_AGENT_SOCK = process.env.FLEET_SSH_SOCK || '/tmp/fleet-ssh-agent.sock';
+if (!process.env.SSH_AUTH_SOCK && existsSync(SSH_AGENT_SOCK)) {
     process.env.SSH_AUTH_SOCK = SSH_AGENT_SOCK;
 }
 export function isGitRepo(cwd) {
-    return exec('git rev-parse --is-inside-work-tree', { cwd }).ok;
+    return execGit(['rev-parse', '--is-inside-work-tree'], { cwd }).ok;
 }
 export function hasCommits(cwd) {
-    return exec('git rev-parse HEAD', { cwd }).ok;
+    return execGit(['rev-parse', 'HEAD'], { cwd }).ok;
 }
 export function getGitStatus(cwd) {
     if (!isGitRepo(cwd)) {
@@ -20,17 +22,17 @@ export function getGitStatus(cwd) {
             clean: true, staged: 0, modified: 0, untracked: 0, ahead: 0, behind: 0,
         };
     }
-    const branch = exec('git rev-parse --abbrev-ref HEAD', { cwd }).stdout || '';
-    const branchResult = exec('git branch --list --no-color', { cwd });
+    const branch = execGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }).stdout || '';
+    const branchResult = execGit(['branch', '--list', '--no-color'], { cwd });
     const branches = branchResult.stdout
         .split('\n')
         .map(b => b.replace(/^\*?\s+/, '').trim())
         .filter(Boolean);
-    const remoteName = exec('git remote', { cwd }).stdout.split('\n')[0] || '';
+    const remoteName = execGit(['remote'], { cwd }).stdout.split('\n')[0] || '';
     const remoteUrl = remoteName
-        ? exec(`git remote get-url ${remoteName}`, { cwd }).stdout
+        ? execGit(['remote', 'get-url', remoteName], { cwd }).stdout
         : '';
-    const porcelain = exec('git status --porcelain', { cwd }).stdout;
+    const porcelain = execGit(['status', '--porcelain'], { cwd }).stdout;
     const lines = porcelain ? porcelain.split('\n') : [];
     let staged = 0, modified = 0, untracked = 0;
     for (const line of lines) {
@@ -44,7 +46,7 @@ export function getGitStatus(cwd) {
     }
     let ahead = 0, behind = 0;
     if (remoteName && hasCommits(cwd)) {
-        const abResult = exec(`git rev-list --left-right --count HEAD...${remoteName}/${branch}`, { cwd });
+        const abResult = execGit(['rev-list', '--left-right', '--count', `HEAD...${remoteName}/${branch}`], { cwd });
         if (abResult.ok) {
             const parts = abResult.stdout.split(/\s+/);
             ahead = parseInt(parts[0], 10) || 0;
@@ -57,7 +59,7 @@ export function getGitStatus(cwd) {
     };
 }
 export function getLog(cwd, count = 10) {
-    const result = exec(`git log --oneline --format="%H|%s|%ci" -${count}`, { cwd });
+    const result = execGit(['log', '--oneline', '--format=%H|%s|%ci', `-${count}`], { cwd });
     if (!result.ok)
         return [];
     return result.stdout.split('\n').filter(Boolean).map(line => {
@@ -73,7 +75,8 @@ export function readGitignore(cwd) {
     return existsSync(p) ? readFileSync(p, 'utf-8') : '';
 }
 export function branchExists(cwd, branch) {
-    return exec(`git show-ref --verify --quiet refs/heads/${branch}`, { cwd }).ok;
+    assertBranch(branch);
+    return execGit(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd }).ok;
 }
 // walk up from composePath to find git root
 const SUBDIR_NAMES = new Set(['server', 'app', 'backend', 'frontend']);
@@ -102,44 +105,54 @@ export function getProjectRoot(composePath) {
     return dir;
 }
 export function gitInit(cwd) {
-    const r = exec('git init -b main', { cwd });
+    const r = execGit(['init', '-b', 'main'], { cwd });
     if (!r.ok)
         throw new GitError(`git init failed: ${r.stderr}`);
 }
 export function gitAdd(cwd, paths = ['.']) {
-    const r = exec(`git add ${paths.join(' ')}`, { cwd });
+    for (const p of paths)
+        if (p !== '.')
+            assertFilePath(p);
+    const r = execGit(['add', ...paths], { cwd });
     if (!r.ok)
         throw new GitError(`git add failed: ${r.stderr}`);
 }
+export function gitAddTracked(cwd) {
+    const r = execGit(['add', '-u'], { cwd });
+    if (!r.ok)
+        throw new GitError(`git add -u failed: ${r.stderr}`);
+}
 export function gitCommit(cwd, message) {
-    const r = exec(`git commit -m "${message.replace(/"/g, '\\"')}"`, { cwd });
+    const r = execGit(['commit', '-m', message], { cwd });
     if (!r.ok)
         throw new GitError(`git commit failed: ${r.stderr}`);
 }
 export function gitCheckout(cwd, branch, create = false) {
-    const flag = create ? '-b' : '';
-    const r = exec(`git checkout ${flag} ${branch}`, { cwd });
+    assertBranch(branch);
+    const args = create ? ['checkout', '-b', branch] : ['checkout', branch];
+    const r = execGit(args, { cwd });
     if (!r.ok)
         throw new GitError(`git checkout failed: ${r.stderr}`);
 }
 export function gitPush(cwd, branch, setUpstream = false) {
-    const flag = setUpstream ? '-u origin' : '';
-    const r = exec(`git push ${flag} ${branch}`, { cwd, timeout: 60_000 });
+    assertBranch(branch);
+    const args = setUpstream ? ['push', '-u', 'origin', branch] : ['push', branch];
+    const r = execGit(args, { cwd, timeout: 60_000 });
     if (!r.ok)
         throw new GitError(`git push failed: ${r.stderr}`);
 }
 export function gitPushAll(cwd) {
-    const r = exec('git push --all origin', { cwd, timeout: 60_000 });
+    const r = execGit(['push', '--all', 'origin'], { cwd, timeout: 60_000 });
     if (!r.ok)
         throw new GitError(`git push --all failed: ${r.stderr}`);
 }
 export function gitSetRemoteUrl(cwd, url) {
-    const r = exec(`git remote set-url origin ${url}`, { cwd });
+    const r = execGit(['remote', 'set-url', 'origin', url], { cwd });
     if (!r.ok)
         throw new GitError(`git remote set-url failed: ${r.stderr}`);
 }
 export function gitAddRemote(cwd, name, url) {
-    const r = exec(`git remote add ${name} ${url}`, { cwd });
+    const r = execGit(['remote', 'add', name, url], { cwd });
     if (!r.ok)
         throw new GitError(`git remote add failed: ${r.stderr}`);
 }

package/dist/core/github.js

@@ -1,11 +1,12 @@
 import { writeFileSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { exec } from './exec.js';
+import { execSafe } from './exec.js';
 import { GitError } from './errors.js';
+import { assertAppName } from './validate.js';
 export const GITHUB_ORG = 'heskethwebdesign';
 export function isGhAuthenticated() {
-    return exec('gh auth status', { timeout: 10_000 }).ok;
+    return execSafe('gh', ['auth', 'status'], { timeout: 10_000 }).ok;
 }
 export function requireGhAuth() {
     if (!isGhAuthenticated()) {
@@ -13,13 +14,15 @@ export function requireGhAuth() {
     }
 }
 export function repoExists(name) {
-    return exec(`gh repo view ${GITHUB_ORG}/${name} --json name`, { timeout: 15_000 }).ok;
+    assertAppName(name);
+    return execSafe('gh', ['repo', 'view', `${GITHUB_ORG}/${name}`, '--json', 'name'], { timeout: 15_000 }).ok;
 }
 export function createRepo(name) {
     requireGhAuth();
+    assertAppName(name);
     if (repoExists(name))
         return;
-    const r = exec(`gh repo create ${GITHUB_ORG}/${name} --private`, { timeout: 30_000 });
+    const r = execSafe('gh', ['repo', 'create', `${GITHUB_ORG}/${name}`, '--private'], { timeout: 30_000 });
     if (!r.ok)
         throw new GitError(`failed to create repo: ${r.stderr}`);
 }
@@ -28,8 +31,15 @@ export function getRepoUrl(name) {
 }
 export function createPullRequest(repo, opts) {
     requireGhAuth();
-    const bodyFlag = opts.body ? `--body "${opts.body.replace(/"/g, '\\"')}"` : '--body ""';
-    const r = exec(`gh pr create --repo ${GITHUB_ORG}/${repo} --title "${opts.title.replace(/"/g, '\\"')}" ${bodyFlag} --head ${opts.head} --base ${opts.base} --json number,title,url,headRefName,baseRefName,state`, { timeout: 30_000 });
+    const r = execSafe('gh', [
+        'pr', 'create',
+        '--repo', `${GITHUB_ORG}/${repo}`,
+        '--title', opts.title,
+        '--body', opts.body ?? '',
+        '--head', opts.head,
+        '--base', opts.base,
+        '--json', 'number,title,url,headRefName,baseRefName,state',
+    ], { timeout: 30_000 });
     if (!r.ok)
         throw new GitError(`failed to create PR: ${r.stderr}`);
     try {
@@ -51,7 +61,12 @@ export function createPullRequest(repo, opts) {
 }
 export function listPullRequests(repo, state = 'open') {
     requireGhAuth();
-    const r = exec(`gh pr list --repo ${GITHUB_ORG}/${repo} --state ${state} --json number,title,url,headRefName,baseRefName,state`, { timeout: 15_000 });
+    const r = execSafe('gh', [
+        'pr', 'list',
+        '--repo', `${GITHUB_ORG}/${repo}`,
+        '--state', state,
+        '--json', 'number,title,url,headRefName,baseRefName,state',
+    ], { timeout: 15_000 });
     if (!r.ok)
         return [];
     try {
@@ -80,7 +95,11 @@ export function protectBranch(repo, branch) {
     const tmpFile = join(tmpdir(), `fleet-protect-${repo}-${branch}.json`);
     writeFileSync(tmpFile, protection);
     try {
-        const r = exec(`gh api -X PUT repos/${GITHUB_ORG}/${repo}/branches/${branch}/protection --input ${tmpFile}`, { timeout: 15_000 });
+        const r = execSafe('gh', [
+            'api', '-X', 'PUT',
+            `repos/${GITHUB_ORG}/${repo}/branches/${branch}/protection`,
+            '--input', tmpFile,
+        ], { timeout: 15_000 });
         return r.ok;
     }
     finally {

package/dist/core/health.d.ts

@@ -12,6 +12,9 @@ export interface HealthResult {
         ok: boolean;
         status: number | null;
         error: string | null;
+        /** True iff the endpoint returned 404 — distinguishes "no healthcheck
+         * implemented for this app" from "endpoint exists but is failing". */
+        endpointMissing?: boolean;
     } | null;
     overall: 'healthy' | 'degraded' | 'down';
 }

package/dist/core/health.js

@@ -1,4 +1,5 @@
-import { exec } from './exec.js';
+import { execSafe } from './exec.js';
+import { assertHealthPath } from './validate.js';
 import { getServiceStatus, getMultipleServiceStatuses, systemdAvailable } from './systemd.js';
 import { listContainers } from './docker.js';
 export function checkHealth(app, prefetched) {
@@ -36,10 +37,21 @@ export function checkHealth(app, prefetched) {
 }
 export function checkHttp(port, healthPath) {
     const path = healthPath ?? '/health';
-    const result = exec(`curl -s -o /dev/null -w "%{http_code}" --max-time 5 http://127.0.0.1:${port}${path}`, { timeout: 10_000 });
+    assertHealthPath(path);
+    const result = execSafe('curl', [
+        '-s', '-o', '/dev/null', '-w', '%{http_code}',
+        '--max-time', '5', `http://127.0.0.1:${port}${path}`,
+    ], { timeout: 10_000 });
     const status = parseInt(result.stdout, 10);
     if (!isNaN(status) && status > 0) {
-        return { ok: status >= 200 && status < 500, status, error: null };
+        // Healthy = 2xx (success) or 3xx (redirect, e.g. /health → /health/).
+        // 4xx and 5xx are NOT healthy. 404 specifically is flagged so the TUI
+        // can show "no healthcheck endpoint" rather than a generic failure —
+        // it means the path was reachable but the route doesn't exist (the app
+        // never implemented one). The fix is to add a /health route to the app.
+        const ok = status >= 200 && status < 400;
+        const endpointMissing = status === 404;
+        return { ok, status, error: null, endpointMissing };
     }
     return { ok: false, status: null, error: result.stderr || 'Connection failed' };
 }

package/dist/core/logs-multi.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Multi-source log tailer. Spawns `docker logs -f` per selected container,
+ * splits the streams on newlines, applies filters (level / grep / since),
+ * emits structured events to a callback. Caller is responsible for rendering.
+ *
+ * Design notes:
+ *  - Each container gets its own subprocess so a stuck/dead container can't
+ *    block the others.
+ *  - Stdout + stderr are merged. Docker writes app output to stdout for
+ *    json-file driver containers; some apps log errors to stderr.
+ *  - Lines are emitted in arrival order per source. Cross-source ordering
+ *    is best-effort (no global timestamp synchronisation — we don't reorder).
+ *  - stop() kills the entire process group cleanly. Idempotent.
+ *  - Used by both the CLI (`fleet logs --all -f`) and the TUI logs view.
+ */
+import { spawn } from 'node:child_process';
+import type { AppEntry } from './registry.js';
+export interface LogSource {
+    /** Logical app name (used in the prefix). */
+    app: string;
+    /** Docker container name. */
+    container: string;
+}
+export interface LogLine {
+    /** Wall-clock receipt time (we don't trust the in-line timestamp — sources differ). */
+    ts: Date;
+    app: string;
+    container: string;
+    /** Inferred level from substring scan. 'unknown' if nothing matched. */
+    level: 'debug' | 'info' | 'warn' | 'error' | 'unknown';
+    text: string;
+}
+export interface MultiTailOpts {
+    /** Tail N lines from each source before going live. Default 50. */
+    tail?: number;
+    /** Restrict to lines newer than this (Docker's --since syntax: '15m', '1h'). */
+    since?: string;
+    /** Only emit lines at or above this level (everything if 'debug' or omitted). */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** Substring filter applied AFTER level — case sensitive. */
+    grep?: string;
+    /** When true, follow new entries forever (default). When false, just dump tail and exit. */
+    follow?: boolean;
+}
+export interface MultiTailHandle {
+    /** Kill all spawned subprocesses. Idempotent. Resolves when teardown is complete. */
+    stop: () => Promise<void>;
+    /** Number of currently-running tailers (drops as containers die). */
+    active: () => number;
+}
+/** Best-effort level inference from a line. Returns 'unknown' if nothing matches. */
+export declare function inferLevel(text: string): LogLine['level'];
+/**
+ * Glob-match a container name against a pattern. Supports * wildcards.
+ * `*-postgres` matches `glitchtip-postgres`, `shared-postgres`, etc.
+ */
+export declare function matchesContainerGlob(name: string, glob: string): boolean;
+/**
+ * Resolve a selection spec into a flat list of LogSource entries.
+ * - Empty selection → all containers across all apps
+ * - apps + containers can be combined; intersection wins
+ */
+export declare function resolveSources(apps: AppEntry[], selection?: {
+    apps?: string[];
+    containers?: string[];
+}): LogSource[];
+/**
+ * Start tailing the given sources. Calls onLine for every emitted line that
+ * passes the filter chain. Returns a handle for graceful shutdown.
+ *
+ * For test injection, pass a custom `spawnFn` that mimics Node's spawn.
+ */
+export declare function startMultiTail(sources: LogSource[], opts: MultiTailOpts, onLine: (line: LogLine) => void, onClose?: (source: LogSource, code: number | null) => void, spawnFn?: typeof spawn): MultiTailHandle;