@yadurajfleetos/cli 0.1.0

package/dist/commands/up.js

@@ -0,0 +1,110 @@
+/**
+ * fleet up — one command that takes any repo from zero to a live HTTPS URL.
+ *
+ * Chains: detect → init → apply → deploy → wait → URL.
+ *
+ * Every step re-uses the existing CLI primitives (`task`, `splash`, `request`)
+ * so the experience is consistent with the granular commands; this just removes
+ * the operator from the loop between them.
+ */
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { request, requireFleet, CliError, EXIT } from '../api.js';
+import { c } from '../render.js';
+import { task, splash, glyph } from '../ui.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const upCommand = {
+    async run(args, flags) {
+        const fleetId = await requireFleet(typeof flags.fleet === 'string' ? flags.fleet : undefined);
+        const manifestPath = 'fleet.yaml';
+        // ── Step 1: scaffold if needed ────────────────────────────────────
+        let needsApply = false;
+        try {
+            await access(manifestPath);
+        }
+        catch {
+            // No fleet.yaml — run the smart init inline.
+            const { detect, manifestTemplate } = await import('../detect.js');
+            const d = await task('detecting project framework', async () => detect());
+            const name = (typeof flags.name === 'string' ? flags.name : '') ||
+                args[0] ||
+                process.cwd().split('/').pop()?.toLowerCase().replace(/[^a-z0-9-]+/g, '-') ||
+                'app';
+            // Write Dockerfile if generated
+            if (d.dockerfile) {
+                await writeFile(join(process.cwd(), 'Dockerfile'), d.dockerfile);
+                console.log(`${glyph.ok} ${c.green('created')} Dockerfile  ${c.dim(`(${d.label}, port ${d.port})`)}`);
+            }
+            // Write manifest
+            await writeFile(manifestPath, manifestTemplate(name, d));
+            console.log(`${glyph.ok} ${c.green('created')} ${manifestPath}  ${c.dim(`(${d.label})`)}`);
+            needsApply = true;
+        }
+        // ── Step 2: read and apply the manifest ───────────────────────────
+        const manifest = await readFile(manifestPath, 'utf8');
+        const applyResult = await task(`applying ${manifestPath}`, async () => (await request('POST', `/fleets/${fleetId}/services`, { body: { manifest } })).body, {
+            done: (b) => b.created.length || b.updated.length
+                ? `applied ${b.created.length + b.updated.length} service(s)`
+                : 'no changes',
+        });
+        for (const w of applyResult.warnings) {
+            console.log(`${glyph.warn} ${c.yellow('warning')}  ${w}`);
+        }
+        // ── Step 3: pick the target service ───────────────────────────────
+        const serviceName = args[0] || applyResult.created[0] || applyResult.updated[0];
+        if (!serviceName) {
+            throw new CliError('Could not determine which service to deploy. Pass the name: fleet up <service>', EXIT.usage);
+        }
+        // Look it up
+        const { body: listBody } = await request('GET', `/fleets/${fleetId}/services`);
+        const service = listBody.services.find((s) => s.name === serviceName || s.id === serviceName);
+        if (!service) {
+            throw new CliError(`Service "${serviceName}" not found after apply. Known: ${listBody.services.map((s) => s.name).join(', ')}`, EXIT.usage);
+        }
+        // ── Step 4: deploy ────────────────────────────────────────────────
+        const gitSha = typeof flags.sha === 'string' ? flags.sha : undefined;
+        const deployResult = await splash(`deploying ${c.bold(service.name)}`, async () => (await request('POST', `/services/${service.id}/deploy`, { body: { gitSha } })).body, {
+            hints: [
+                'scoring every online node on headroom, reliability and load',
+                'building for every architecture an eligible node runs',
+                'the first multi-arch build is the slow one; layers cache after it',
+                'pushing the image to the fleet registry',
+            ],
+            done: (b) => `built and scheduled onto ${c.bold(b.placedOn.name)} ${c.dim(`score ${b.score?.toFixed(3)}`)}`,
+        });
+        for (const w of deployResult.warnings ?? []) {
+            console.log(`${glyph.warn} ${c.yellow('warning')}  ${w}`);
+        }
+        // ── Step 5: wait for healthy ──────────────────────────────────────
+        if (!flags['no-wait']) {
+            await task(`waiting for ${c.bold(service.name)} to come up`, async (s) => {
+                s.hints([
+                    'the agent picks up desired state on its next poll',
+                    "a cold image pull takes as long as the node's uplink does",
+                    'this clears once the agent reports the container running',
+                ]);
+                const deadline = Date.now() + 180_000;
+                while (Date.now() < deadline) {
+                    const { body } = await request('GET', `/fleets/${fleetId}/services`);
+                    const current = body.services.find((s) => s.id === service.id)?.current;
+                    if (current?.status === 'running')
+                        return;
+                    if (current?.status === 'failed') {
+                        throw new CliError(`"${service.name}" did not start. \`fleet deployments ${service.name}\` has the reason.`, EXIT.healthCheckFailed);
+                    }
+                    await sleep(2000);
+                }
+                throw new CliError(`"${service.name}" was scheduled but has not reported running.`, EXIT.healthCheckFailed);
+            }, { done: () => `${c.bold(service.name)} is running` });
+        }
+        // ── Step 6: print the URL ─────────────────────────────────────────
+        const url = deployResult.url ?? service.domain ?? service.hostname;
+        if (url) {
+            const fullUrl = url.startsWith('http') ? url : `https://${url}`;
+            console.log(`\n${glyph.ok} ${c.green('live')}  ${c.bold(c.cyan(fullUrl))}`);
+        }
+        console.log(c.dim(`\n  fleet open ${service.name}   open in browser`));
+        console.log(c.dim(`  fleet logs ${service.name}   follow logs`));
+        console.log(c.dim(`  fleet down ${service.name}   tear down`));
+    },
+};

package/dist/config.js

@@ -0,0 +1,35 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const configPath = () => process.env.FLEET_CONFIG ?? join(homedir(), '.config', 'fleet-os', 'config.json');
+export async function loadProfile() {
+    const fromEnv = {
+        api: process.env.FLEET_API ?? '',
+        accessToken: process.env.FLEET_TOKEN,
+        fleetId: process.env.FLEET_ID,
+    };
+    try {
+        const stored = JSON.parse(await readFile(configPath(), 'utf8'));
+        // Environment wins, so CI can override a developer's saved login.
+        return {
+            ...stored,
+            ...Object.fromEntries(Object.entries(fromEnv).filter(([, v]) => v)),
+            // Older builds could save an empty api field. Keep it empty so the
+            // caller can give a precise configuration error rather than constructing
+            // an invalid relative URL such as /auth/login.
+            api: fromEnv.api || stored.api || '',
+        };
+    }
+    catch {
+        // The public control plane is the useful default for a first-time install.
+        // Self-hosters and CI can always override it with FLEET_API or --api.
+        return { api: fromEnv.api || 'https://fleetapi.plastikworld.xyz', ...fromEnv };
+    }
+}
+export async function saveProfile(profile) {
+    const path = configPath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    // Contains a bearer token; 0600 or it is readable by anything on the box.
+    await writeFile(path, JSON.stringify(profile, null, 2), { mode: 0o600 });
+}
+export const configLocation = configPath;

package/dist/detect.js

@@ -0,0 +1,277 @@
+/**
+ * Framework detection engine.
+ *
+ * Inspects the current working directory for well-known project signals and
+ * returns everything `fleet init` needs to scaffold both a Dockerfile and a
+ * fleet.yaml. Detection is deliberately shallow — fast, no child_process, no
+ * network. A wrong guess is corrected with a one-line edit rather than a
+ * five-minute hang.
+ */
+import { readFile, access } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+const exists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const readJson = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+const readText = async (path) => {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Extract EXPOSE port from an existing Dockerfile. */
+function parseExpose(dockerfile) {
+    const match = dockerfile.match(/^EXPOSE\s+(\d+)/m);
+    return match ? parseInt(match[1], 10) : null;
+}
+const hasDep = (pkg, name) => {
+    const deps = pkg.dependencies;
+    const devDeps = pkg.devDependencies;
+    return Boolean(deps?.[name] || devDeps?.[name]);
+};
+// ── Dockerfile templates ────────────────────────────────────────────────
+const NEXTJS_DOCKERFILE = `# --- Build ---
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# --- Run ---
+FROM node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+EXPOSE 3000
+CMD ["node", "server.js"]
+`;
+const VITE_DOCKERFILE = `# --- Build ---
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# --- Serve ---
+FROM nginx:1.27-alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`;
+const NODE_DOCKERFILE = `FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+EXPOSE 3000
+CMD ["node", "src/index.js"]
+`;
+const PYTHON_DOCKERFILE = (entry, usesPoetry) => `FROM python:3.12-slim
+WORKDIR /app
+${usesPoetry
+    ? `COPY pyproject.toml poetry.lock* ./
+RUN pip install --no-cache-dir poetry && poetry config virtualenvs.create false && poetry install --no-interaction --no-ansi --no-dev`
+    : `COPY requirements*.txt ./
+RUN pip install --no-cache-dir -r requirements.txt`}
+COPY . .
+EXPOSE 8000
+CMD ["python", "-m", "${entry}"]
+`;
+const GO_DOCKERFILE = (module) => `# --- Build ---
+FROM golang:1.24-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum* ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o /server .
+
+# --- Run ---
+FROM alpine:3.21
+COPY --from=builder /server /server
+EXPOSE 8080
+CMD ["/server"]
+`;
+const RUST_DOCKERFILE = `# --- Build ---
+FROM rust:1.87-slim AS builder
+WORKDIR /app
+COPY Cargo.toml Cargo.lock* ./
+RUN mkdir src && echo 'fn main(){}' > src/main.rs && cargo build --release && rm -rf src
+COPY . .
+RUN cargo build --release
+
+# --- Run ---
+FROM debian:bookworm-slim
+COPY --from=builder /app/target/release/* /usr/local/bin/app
+EXPOSE 8080
+CMD ["app"]
+`;
+// ── Detection logic ─────────────────────────────────────────────────────
+export async function detect(cwd = process.cwd()) {
+    const hasDockerfile = await exists(join(cwd, 'Dockerfile'));
+    // When a Dockerfile already exists, read its EXPOSE and skip auto-generation.
+    if (hasDockerfile) {
+        const df = await readText(join(cwd, 'Dockerfile'));
+        const port = (df && parseExpose(df)) || 3000;
+        return {
+            framework: 'unknown',
+            label: 'existing Dockerfile',
+            port,
+            healthPath: '/',
+            dockerfile: null,
+            hasDockerfile: true,
+        };
+    }
+    // ── Node-based frameworks ──
+    const pkg = await readJson(join(cwd, 'package.json'));
+    if (pkg) {
+        // Next.js
+        if (hasDep(pkg, 'next')) {
+            return {
+                framework: 'nextjs',
+                label: 'Next.js',
+                port: 3000,
+                healthPath: '/',
+                dockerfile: NEXTJS_DOCKERFILE,
+                hasDockerfile: false,
+            };
+        }
+        // Vite / React / Vue / Svelte / SvelteKit
+        if (hasDep(pkg, 'vite') || hasDep(pkg, '@vitejs/plugin-react') || hasDep(pkg, '@sveltejs/vite-plugin-svelte')) {
+            return {
+                framework: 'vite',
+                label: 'Vite',
+                port: 80,
+                healthPath: '/',
+                dockerfile: VITE_DOCKERFILE,
+                hasDockerfile: false,
+            };
+        }
+        // Node API servers
+        if (hasDep(pkg, 'express') ||
+            hasDep(pkg, 'fastify') ||
+            hasDep(pkg, '@nestjs/core') ||
+            hasDep(pkg, 'hono') ||
+            hasDep(pkg, 'koa')) {
+            return {
+                framework: 'node',
+                label: 'Node.js API',
+                port: 3000,
+                healthPath: '/health',
+                dockerfile: NODE_DOCKERFILE,
+                hasDockerfile: false,
+            };
+        }
+    }
+    // ── Python ──
+    const hasRequirements = await exists(join(cwd, 'requirements.txt'));
+    const hasPyproject = await exists(join(cwd, 'pyproject.toml'));
+    if (hasRequirements || hasPyproject) {
+        // Try to guess the ASGI/WSGI framework
+        const reqText = (await readText(join(cwd, 'requirements.txt'))) ??
+            (await readText(join(cwd, 'pyproject.toml'))) ??
+            '';
+        const isFastapi = /fastapi/i.test(reqText);
+        const isFlask = /flask/i.test(reqText);
+        const isDjango = /django/i.test(reqText);
+        const entry = isDjango
+            ? `django`
+            : isFastapi
+                ? `uvicorn main:app --host 0.0.0.0 --port 8000`.split(' ')[0]
+                : isFlask
+                    ? `flask`
+                    : 'app';
+        // For FastAPI, override CMD to use uvicorn properly
+        const pythonDF = isFastapi
+            ? PYTHON_DOCKERFILE(entry, hasPyproject && !hasRequirements).replace(`CMD ["python", "-m", "${entry}"]`, `CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]`)
+            : isDjango
+                ? PYTHON_DOCKERFILE(entry, hasPyproject && !hasRequirements).replace(`CMD ["python", "-m", "${entry}"]`, `CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]`)
+                : PYTHON_DOCKERFILE(entry, hasPyproject && !hasRequirements);
+        return {
+            framework: 'python',
+            label: isFastapi ? 'Python (FastAPI)' : isDjango ? 'Python (Django)' : isFlask ? 'Python (Flask)' : 'Python',
+            port: 8000,
+            healthPath: '/health',
+            dockerfile: pythonDF,
+            hasDockerfile: false,
+        };
+    }
+    // ── Go ──
+    const goMod = await readText(join(cwd, 'go.mod'));
+    if (goMod) {
+        const moduleMatch = goMod.match(/^module\s+(.+)$/m);
+        const moduleName = moduleMatch?.[1] ?? basename(cwd);
+        return {
+            framework: 'go',
+            label: 'Go',
+            port: 8080,
+            healthPath: '/healthz',
+            dockerfile: GO_DOCKERFILE(moduleName),
+            hasDockerfile: false,
+        };
+    }
+    // ── Rust ──
+    if (await exists(join(cwd, 'Cargo.toml'))) {
+        return {
+            framework: 'rust',
+            label: 'Rust',
+            port: 8080,
+            healthPath: '/healthz',
+            dockerfile: RUST_DOCKERFILE,
+            hasDockerfile: false,
+        };
+    }
+    // ── Static / unknown ──
+    // If there's an index.html, it's probably a static site
+    if (await exists(join(cwd, 'index.html'))) {
+        return {
+            framework: 'static',
+            label: 'Static site',
+            port: 80,
+            healthPath: '/',
+            dockerfile: null,
+            hasDockerfile: false,
+        };
+    }
+    return {
+        framework: 'unknown',
+        label: 'unknown project',
+        port: 3000,
+        healthPath: '/',
+        dockerfile: null,
+        hasDockerfile: false,
+    };
+}
+// ── Manifest template ───────────────────────────────────────────────────
+export function manifestTemplate(name, d) {
+    const build = d.hasDockerfile || d.dockerfile ? 'build: .' : `image: nginx:1.27`;
+    const portLine = d.port !== 80 ? `\n    container_port: ${d.port}` : '';
+    return `fleet: homelab
+
+services:
+  ${name}:
+    ${build}
+    placement: flexible
+    resources: { ram: 512Mi, cpu: 0.5 }
+    health: { path: ${d.healthPath} }${portLine}
+    # domain: ${name}.yourdomain.dev
+`;
+}

package/dist/index.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { CliError, EXIT } from './api.js';
+import { c } from './render.js';
+import { banner } from './mark.js';
+import { commands } from './commands/index.js';
+import { parseArgs } from './args.js';
+export { parseArgs };
+/**
+ * Grouped by the order an operator meets them, not alphabetically: the first
+ * group is a first session with the tool, read top to bottom.
+ */
+const GROUPS = [
+    [
+        'getting started',
+        [
+            ['up [service]', 'Detect, scaffold, apply, and deploy in one command'],
+            ['init', 'Scaffold a fleet.yaml and Dockerfile from this repository'],
+            ['config show', 'Show the saved control plane and selected fleet'],
+            ['use <fleet>', 'Select the default fleet for later commands'],
+            ['auth login', 'Sign in and save a secure local session'],
+            ['nodes pair', 'Mint a pairing token for a new machine'],
+            ['doctor', 'Check the control plane, nodes, services, ingress, and GitHub'],
+            ['apply [file]', 'Apply a fleet.yaml to the fleet'],
+            ['deploy <service>', 'Build, schedule, and roll out'],
+        ],
+    ],
+    [
+        'looking around',
+        [
+            ['open [service]', 'Open the live service in your default browser'],
+            ['status', 'One-screen view of the whole fleet'],
+            ['services', 'List services and where they are running'],
+            ['nodes', 'List nodes'],
+            ['where <service>', 'Explain where a service would be placed, and why'],
+            ['deployments <service>', 'Deployment history'],
+            ['logs <service> --follow', 'Follow the latest agent-reported container tail'],
+            ['events', 'Unified event timeline'],
+        ],
+    ],
+    [
+        'operating',
+        [
+            ['down <service>', 'Stop and tear down a service deployment'],
+            ['validate [file]', 'Check a fleet.yaml without applying it'],
+            ['reschedule <service>', 'Force a service to move'],
+            ['restart <service>', 'Replace the current release on its node'],
+            ['rollback <service> [release]', 'Restore the previous or selected release'],
+            ['nodes cordon <name>', 'Stop scheduling new work onto a node'],
+            ['nodes uncordon <name>', 'Allow scheduling again'],
+            ['nodes rm <name>', 'Revoke and remove a node'],
+            ['alerts', 'List, add, and test alert rules'],
+            ['auth login|logout|whoami', 'Sign in to a control plane'],
+        ],
+    ],
+];
+const OPTIONS = [
+    ['--fleet <id>', 'Operate on a specific fleet'],
+    ['--api <url>', 'Control plane URL (default: saved profile)'],
+    ['--json', 'Machine-readable output on stdout'],
+    ['--plan, --dry-run', 'Show the deploy placement plan without changing anything'],
+    ['--yes', 'Skip the interactive deploy confirmation'],
+    ['--no-wait', 'Return once scheduled, without following the rollout'],
+    ['-h, --help', 'Show help'],
+];
+// One column width across every group, so the glosses form a single edge down
+// the page rather than stepping in and out per section.
+const TERM_WIDTH = Math.max(...GROUPS.flatMap(([, rows]) => rows.map(([term]) => term.length)), ...OPTIONS.map(([term]) => term.length));
+const definitions = (rows) => rows.map(([term, gloss]) => `  ${term.padEnd(TERM_WIDTH)}   ${c.dim(gloss)}`).join('\n');
+const usage = () => [
+    banner('deploy to hardware you own'),
+    '',
+    `${c.dim('usage')}  fleet <command> [options]`,
+    ...GROUPS.flatMap(([title, rows]) => ['', c.bold(title), definitions(rows)]),
+    '',
+    c.bold('options'),
+    definitions(OPTIONS),
+    '',
+    c.dim('exit codes  0 ok · 1 failure · 2 usage · 3 no eligible node · 4 health check failed'),
+    '',
+].join('\n');
+async function version() {
+    const { readFile } = await import('node:fs/promises');
+    const path = new URL('../package.json', import.meta.url);
+    const pkg = JSON.parse(await readFile(path, 'utf8'));
+    return pkg.version ?? '0.0.0';
+}
+async function main() {
+    const { positional, flags } = parseArgs(process.argv.slice(2));
+    const [name, ...rest] = positional;
+    if (flags.version || flags.v) {
+        console.log(await version());
+        process.exit(EXIT.ok);
+    }
+    if (!name || flags.help || flags.h) {
+        console.log(usage());
+        // A bare `fleet` is someone asking what this is, not a malformed command.
+        process.exit(EXIT.ok);
+    }
+    const command = commands[name];
+    if (!command) {
+        const near = Object.keys(commands).filter((k) => k.startsWith(name[0] ?? ''));
+        console.error(`${c.red('unknown command')} "${name}"` + (near.length ? `\n  did you mean: ${near.join(', ')}?` : ''));
+        process.exit(EXIT.usage);
+    }
+    await command.run(rest, flags);
+}
+/**
+ * Only run when invoked as a command. Importing the entrypoint — from a test,
+ * or another tool — must not execute it.
+ */
+const invokedDirectly = process.argv[1] !== undefined &&
+    // npm link exposes the bin as a symlink. ESM resolves this module to its
+    // real path, whereas argv retains the symlink, so compare canonical paths.
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+if (invokedDirectly) {
+    main().catch(onError);
+}
+function onError(err) {
+    if (err instanceof CliError) {
+        console.error(`${c.red('error')}  ${err.message}`);
+        if (err.detail) {
+            const lines = Array.isArray(err.detail) ? err.detail : [err.detail];
+            for (const line of lines) {
+                console.error('  ' +
+                    (typeof line === 'string'
+                        ? line
+                        : `${line.path ?? ''} ${line.message ?? JSON.stringify(line)}`));
+            }
+        }
+        process.exit(err.exitCode);
+    }
+    console.error(`${c.red('error')}  ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(EXIT.failure);
+}

package/dist/mark.js

@@ -0,0 +1,102 @@
+/**
+ * The Fleet mark, drawn in the terminal: eight peers around one live hub — the
+ * same topology as the mesh on the marketing site, so the CLI and the browser
+ * are recognisably the same product.
+ *
+ * The mark is a fixed character grid rather than a string per state, because
+ * the loading animation lights individual spokes and needs to address cells.
+ */
+import { c, colourDepth, rgb } from './render.js';
+const GRID = [
+    '  ○     ○     ○  ',
+    '   ╲    │    ╱   ',
+    '○───────◉───────○',
+    '   ╱    │    ╲   ',
+    '  ○     ○     ○  ',
+];
+export const MARK_WIDTH = 17;
+export const MARK_HEIGHT = GRID.length;
+/** Where the hub sits. Always lit — a fleet with no control plane is not a fleet. */
+const HUB = [2, 8];
+/** Each peer owns its node glyph and the spoke connecting it to the hub. */
+const PEERS = [
+    [[0, 2], [1, 3]],
+    [[0, 8], [1, 8]],
+    [[0, 14], [1, 13]],
+    [[2, 0], [2, 1], [2, 2], [2, 3], [2, 4], [2, 5], [2, 6], [2, 7]],
+    [[2, 16], [2, 15], [2, 14], [2, 13], [2, 12], [2, 11], [2, 10], [2, 9]],
+    [[4, 2], [3, 3]],
+    [[4, 8], [3, 8]],
+    [[4, 14], [3, 13]],
+];
+export const PEER_COUNT = PEERS.length;
+const key = ([row, col]) => `${row}:${col}`;
+/**
+ * Brightness 1 is fully lit, 0 is the resting state. Intermediate values only
+ * read as a gradient on truecolour terminals; elsewhere anything lit at all
+ * takes the accent, which keeps the animation legible rather than uniform.
+ */
+function shade(glyph, brightness) {
+    if (brightness <= 0.02)
+        return c.grey(glyph);
+    if (colourDepth < 2)
+        return brightness > 0.45 ? c.signal(glyph) : c.grey(glyph);
+    // Resting slate → signal green, so a spoke appears to charge rather than blink.
+    const t = Math.min(1, brightness);
+    const r = Math.round(0x4b + (0x3f - 0x4b) * t);
+    const g = Math.round(0x52 + (0xe0 - 0x52) * t);
+    const b = Math.round(0x5d + (0x8b - 0x5d) * t);
+    return rgb(r, g, b)(glyph);
+}
+/**
+ * Render the mark with a travelling pulse. `phase` advances continuously; peers
+ * light in sequence and decay behind the head, so the mark reads as traffic
+ * moving through a mesh rather than as a spinner wearing a costume.
+ */
+export function markFrame(phase) {
+    const brightness = new Map();
+    // A negative phase is the resting mark: hub live, peers quiet.
+    const resting = !(phase >= 0);
+    for (let i = 0; resting === false && i < PEERS.length; i++) {
+        // Distance from the pulse head, wrapped, so the trail crosses the seam.
+        const raw = (phase - i + PEERS.length) % PEERS.length;
+        const distance = Math.min(raw, PEERS.length - raw);
+        const level = Math.max(0, 1 - distance / 2.4);
+        for (const [index, cell] of PEERS[i].entries()) {
+            // Along a spoke the outer end burns brightest, so the glow reads as
+            // arriving at the peer rather than washing the whole edge at once.
+            const along = PEERS[i].length > 2 ? 1 - index / PEERS[i].length : 1;
+            brightness.set(key(cell), Math.max(brightness.get(key(cell)) ?? 0, level * along));
+        }
+    }
+    return GRID.map((line, row) => [...line]
+        .map((glyph, col) => {
+        if (glyph === ' ')
+            return glyph;
+        if (row === HUB[0] && col === HUB[1])
+            return c.bold(c.signal(glyph));
+        return shade(glyph, brightness.get(`${row}:${col}`) ?? 0);
+    })
+        .join(''));
+}
+/** The resting mark: hub live, peers quiet. */
+export const mark = () => markFrame(-1);
+const WORDMARK = ['█▀▀ █   █▀▀ █▀▀ ▀█▀', '█▀  █   █▀  █▀   █ ', '▀   ▀▀▀ ▀▀▀ ▀▀▀  ▀ '];
+/**
+ * Mark and wordmark side by side, with the tagline tucked under the wordmark so
+ * the block stays rectangular. Falls back to a single line when the terminal is
+ * too narrow to hold both without wrapping — a wrapped logo looks broken.
+ */
+export function banner(subtitle) {
+    // `columns` is 0, not undefined, on some pseudo-terminals — `??` would miss it.
+    const columns = process.stdout.columns || 80;
+    if (columns < 46)
+        return `${c.signal('◉')} ${c.bold('fleet')}${subtitle ? c.dim(`  ${subtitle}`) : ''}`;
+    // The wordmark sits against the middle three rows of the mark; the tagline
+    // takes the last. Every mark row is exactly MARK_WIDTH visible columns, so a
+    // fixed gutter aligns them without measuring around the colour codes.
+    const right = ['', ...WORDMARK.map(c.bold), subtitle ? c.dim(subtitle) : ''];
+    return mark()
+        .map((line, i) => `  ${line}${right[i] ? `    ${right[i]}` : ''}`.trimEnd())
+        .join('\n');
+}