@soyrageagency/docker-mcp 1.1.0

package/dist/panel/service.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Panel & monitoring data service.
+ *
+ * A UI/monitoring-oriented data layer shared by the panel's REST API, the
+ * Prometheus `/metrics` endpoint and the terminal UI. It normalises Docker
+ * payloads into compact DTOs, samples live CPU/memory usage, and — crucially —
+ * supports a **demo mode** that serves realistic fabricated data (with gentle
+ * jitter so it looks alive) for previews, screenshots and client demos.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+import type { AppConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+import { DockerClient } from "../docker/client.js";
+/** Compact container row for the UI, including live usage when available. */
+export interface ContainerDTO {
+    id: string;
+    name: string;
+    image: string;
+    state: string;
+    status: string;
+    ports: string[];
+    /** Live CPU percentage (0–100·cores), if sampled. */
+    cpu?: number;
+    /** Live memory usage in bytes, if sampled. */
+    memory?: number;
+    /** Memory limit in bytes, if known. */
+    memoryLimit?: number;
+}
+/** Host/daemon summary for the header cards. */
+export interface SystemDTO {
+    engine: string;
+    os: string;
+    arch: string;
+    cpus: number;
+    memoryBytes: number;
+    containersRunning: number;
+    containersTotal: number;
+    images: number;
+    demo: boolean;
+    readOnly: boolean;
+}
+/** Image row for the images panel. */
+export interface ImageDTO {
+    id: string;
+    tag: string;
+    sizeBytes: number;
+}
+/** A full point-in-time snapshot used by monitoring & metrics. */
+export interface Snapshot {
+    system: SystemDTO;
+    containers: ContainerDTO[];
+    images: ImageDTO[];
+    /** Aggregate CPU percentage across running containers. */
+    cpuTotal: number;
+    /** Aggregate memory bytes across running containers. */
+    memoryUsed: number;
+}
+/** A single entry in a container's filesystem listing. */
+export interface FileEntry {
+    name: string;
+    type: "dir" | "file" | "link";
+    size: number;
+    /** Symlink target, when known. */
+    target?: string;
+}
+/** An alert raised by the alert engine. */
+export interface Alert {
+    /** Severity. */
+    level: "critical" | "warning" | "info";
+    /** Container the alert relates to (or "system"). */
+    source: string;
+    /** Short rule key, e.g. "container-down", "high-cpu", "log-error". */
+    rule: string;
+    /** Human-readable message. */
+    message: string;
+    /** ISO timestamp. */
+    time: string;
+}
+/** Result of running a command in the panel terminal. */
+export interface CommandResult {
+    command: string;
+    code: number;
+    output: string;
+}
+/** A recorded container snapshot/backup. */
+export interface SnapshotInfo {
+    id: string;
+    container: string;
+    type: "commit" | "export";
+    /** Image ref (commit) or file path (export). */
+    ref: string;
+    sizeBytes: number;
+    createdAt: string;
+    destination: string;
+}
+/** Scheduled backup configuration (in-memory). */
+export interface BackupSchedule {
+    enabled: boolean;
+    /** 24h time "HH:MM" (local) at which the backup runs. */
+    time: string;
+    /** Container names to back up, or ["all"]. */
+    containers: string[];
+    type: "commit" | "export";
+    /** Optional email address (delivered via the webhook payload). */
+    email: string;
+}
+/** Curated inspect summary for the details drawer. */
+export interface InspectSummary {
+    name: string;
+    image: string;
+    id: string;
+    created: string;
+    state: string;
+    health: string;
+    restartPolicy: string;
+    command: string;
+    ports: string[];
+    mounts: string[];
+    networks: string[];
+    env: string[];
+}
+/** Network row for the System tab. */
+export interface NetworkDTO {
+    name: string;
+    id: string;
+    driver: string;
+    scope: string;
+}
+/** Volume row for the System tab. */
+export interface VolumeDTO {
+    name: string;
+    driver: string;
+    mountpoint: string;
+}
+/** Actions the panel can request. */
+export type ContainerAction = "start" | "stop" | "restart";
+/** Unified data provider; delegates to Docker or fabricated demo data. */
+export declare class PanelService {
+    private readonly docker;
+    private readonly config;
+    private readonly logger;
+    private readonly demo;
+    /** Demo baselines, mutated with light jitter to feel live. */
+    private readonly demoBase;
+    /** Names with auto-restart enabled (in-memory registry). */
+    private readonly autoRestart;
+    /** Rolling event log of raised alerts (most recent last). */
+    private readonly alertLog;
+    private watchdog;
+    /** In-memory snapshot registry. */
+    private readonly snapshotLog;
+    /** Backup schedule + scheduler bookkeeping. */
+    private schedule;
+    private scheduler;
+    private lastScheduleRun;
+    /** Rolling time-series for the Trends charts (most recent last). */
+    private readonly history;
+    private sampler;
+    private static readonly HISTORY_CAP;
+    constructor(docker: DockerClient, config: AppConfig, logger: Logger);
+    get isDemo(): boolean;
+    get isReadOnly(): boolean;
+    /** Host summary. */
+    system(): Promise<SystemDTO>;
+    /** Container list WITH live usage (CPU %, memory) for running containers. */
+    containers(): Promise<ContainerDTO[]>;
+    /** Image list. */
+    images(): Promise<ImageDTO[]>;
+    /** A full snapshot for monitoring dashboards and the metrics endpoint. */
+    snapshot(): Promise<Snapshot>;
+    /** Recent logs for one container. */
+    logs(reference: string, tail?: number): Promise<string>;
+    /** Perform a lifecycle action. Rejected in read-only mode. */
+    act(reference: string, action: ContainerAction): Promise<void>;
+    /** Names with auto-restart currently enabled. */
+    autoRestartList(): string[];
+    /** Enable/disable auto-restart for a container. */
+    setAutoRestart(name: string, enabled: boolean): void;
+    /**
+     * Start the background watchdog: every `intervalMs`, any container that has
+     * auto-restart enabled but is not running is restarted (unless read-only).
+     * Each intervention is recorded as an alert.
+     */
+    startWatchdog(intervalMs?: number): void;
+    /** Stop the watchdog (used on shutdown). */
+    stopWatchdog(): void;
+    /** Recent CPU/memory samples for the Trends charts. */
+    getHistory(): Array<{
+        t: number;
+        cpu: number;
+        mem: number;
+        memBytes: number;
+    }>;
+    /** Start sampling CPU/memory into the history ring buffer. */
+    startSampler(intervalMs?: number): void;
+    private tickSampler;
+    private tickWatchdog;
+    /** Append an alert to the rolling log (bounded to the last 200). */
+    private addAlert;
+    /**
+     * Compute the current alerts: live state-based rules (down / high CPU / high
+     * memory / unhealthy) plus a scan of recent logs for error/warn lines, merged
+     * with the rolling event log (watchdog interventions, etc.).
+     */
+    alerts(): Promise<Alert[]>;
+    /** List a directory inside a container. */
+    listFiles(name: string, path?: string): Promise<{
+        path: string;
+        entries: FileEntry[];
+    }>;
+    /** Read a text file inside a container (bounded to 128 KB). */
+    readFile(name: string, path: string): Promise<{
+        path: string;
+        content: string;
+        truncated: boolean;
+    }>;
+    /**
+     * Write a text file inside a container (editor save). Blocked in read-only
+     * mode. Content is streamed to `sh -c 'cat > "$1"'` with the path passed as
+     * an argument (no shell interpolation of the path).
+     */
+    writeFile(name: string, path: string, content: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+    /** Whether the AI copilot is available (demo simulates it). */
+    get aiEnabled(): boolean;
+    /** A short human label for the active model, for the status bar. */
+    get aiLabel(): string;
+    /**
+     * AI copilot. `mode`:
+     *  - "command": natural language → a suggested docker command + explanation
+     *  - "edit":    rewrite file `context` per the `prompt` instruction
+     * Uses an OpenAI-compatible endpoint when configured; falls back to a helpful
+     * message (and a heuristic command) otherwise. Demo mode simulates it.
+     */
+    aiAssist(mode: "command" | "edit", prompt: string, context?: string): Promise<{
+        command?: string;
+        explanation?: string;
+        content?: string;
+        text?: string;
+        source: string;
+    }>;
+    /** Run a command inside a container and return its combined output. */
+    private exec;
+    /**
+     * Run a `docker …` (or `docker compose …`) command typed in the panel
+     * terminal. Commands are parsed into an argv array and spawned WITHOUT a
+     * shell (no injection). A deny-list blocks dangerous verbs; write verbs are
+     * blocked in read-only mode; read verbs are always allowed.
+     */
+    runCommand(input: string): Promise<CommandResult>;
+    private spawnDocker;
+    /** List recorded snapshots (most recent first). */
+    listSnapshots(): SnapshotInfo[];
+    /** Create a snapshot of a container (image commit or filesystem export). */
+    createSnapshot(container: string, type?: "commit" | "export"): Promise<SnapshotInfo>;
+    /** Get the current backup schedule. */
+    getSchedule(): BackupSchedule;
+    /** Update the backup schedule (fields are validated/coerced). */
+    setSchedule(next: Record<string, unknown>): BackupSchedule;
+    /** Start the once-a-minute backup scheduler (idempotent). */
+    startScheduler(): void;
+    private tickScheduler;
+    /** POST a backup notification to the configured webhook (email/cloud bridge). */
+    private notify;
+    /** Curated inspect summary for the details drawer. */
+    inspectSummary(name: string): Promise<InspectSummary>;
+    /** Networks for the System tab. */
+    networks(): Promise<NetworkDTO[]>;
+    /** Volumes for the System tab. */
+    volumes(): Promise<VolumeDTO[]>;
+    /**
+     * Restore a recorded snapshot. Non-destructive by design: a commit snapshot
+     * launches a *new* container from the image (the image's CMD/ENTRYPOINT are
+     * preserved by `commit`), and an export tar is imported as a new image you can
+     * then run. Nothing existing is overwritten.
+     */
+    restoreSnapshot(id: string): Promise<{
+        ok: boolean;
+        message: string;
+        container?: string;
+        image?: string;
+    }>;
+    /** One-off command inside a running container (`docker exec … sh -lc`). */
+    execOnce(name: string, command: string): Promise<CommandResult>;
+    /** Candidate compose files near the working directory (for the editor pickers). */
+    findComposeFiles(): string[];
+    private isComposePath;
+    /** Read a host compose file (compose-named, ≤512 KB). */
+    readComposeFile(path: string): {
+        path: string;
+        content: string;
+    };
+    /** Write a host compose file (compose-named, ≤512 KB). Blocked when read-only. */
+    writeComposeFile(path: string, content: string): {
+        path: string;
+        bytes: number;
+    };
+    /** `docker compose` lifecycle against a specific file. */
+    composeAction(path: string, action: "up" | "down" | "restart"): Promise<CommandResult>;
+    /**
+     * Attach an extra host volume to a container by recreating it from its own
+     * image with the same env / ports / network / restart policy plus the new
+     * bind. The original is stopped and kept (renamed `<name>-preattach-<ts>`) so
+     * the change is reversible.
+     */
+    attachVolume(name: string, hostPath: string, containerPath: string, readOnly?: boolean): Promise<{
+        ok: boolean;
+        message: string;
+        container: string;
+        backup?: string;
+    }>;
+    /**
+     * Render a snapshot in the Prometheus text exposition format so it can be
+     * scraped by Prometheus, Grafana Agent, Zabbix (Prometheus preprocessing or
+     * HTTP agent), VictoriaMetrics, etc.
+     */
+    prometheus(): Promise<string>;
+    /** Demo container list with gentle live jitter so usage looks real. */
+    private demoContainersLive;
+    /** Reflect a lifecycle action in the demo baseline so the UI updates. */
+    private applyDemoAction;
+}