n8n-guard 0.1.0

package/dist/checks/retention.js

@@ -0,0 +1,58 @@
+import { humanBytes } from "./dbHealth.js";
+/**
+ * Turns raw execution counts into "what does deleting old runs actually buy me".
+ * Byte figures are estimates: they assume execution rows cost the same on
+ * average, which is what the row-count-to-size ratio can support.
+ */
+export function analyzeRetention(stats, keepDays = 30, now = Date.now()) {
+    const oldest = stats.oldestExecutionAt ? Date.parse(stats.oldestExecutionAt) : NaN;
+    const newest = stats.newestExecutionAt ? Date.parse(stats.newestExecutionAt) : NaN;
+    const spanDays = Number.isNaN(oldest) || Number.isNaN(newest) ? null : Math.max((newest - oldest) / 86_400_000, 1 / 24);
+    const executionsPerDay = spanDays === null ? null : stats.executionCount / spanDays;
+    // Only execution-shaped tables shrink when executions are pruned.
+    const executionTables = stats.tables.filter((t) => t.table.startsWith("execution_"));
+    const executionBytes = executionTables.every((t) => t.bytes === null)
+        ? stats.totalBytes || null
+        : executionTables.reduce((sum, t) => sum + (t.bytes ?? 0), 0);
+    const bytesPerRow = stats.executionCount > 0 && executionBytes ? executionBytes / stats.executionCount : null;
+    const buckets = Object.entries(stats.executionsOlderThanDays)
+        .map(([days, rows]) => ({
+        olderThanDays: Number(days),
+        rows,
+        share: stats.executionCount > 0 ? rows / stats.executionCount : 0,
+        estimatedBytes: bytesPerRow === null ? null : Math.round(rows * bytesPerRow),
+    }))
+        .sort((a, b) => a.olderThanDays - b.olderThanDays);
+    const chosen = buckets.find((b) => b.olderThanDays === keepDays) ?? null;
+    const recommendation = chosen
+        ? {
+            keepDays,
+            prunableRows: chosen.rows,
+            estimatedBytesFreed: chosen.estimatedBytes,
+            estimatedHumanFreed: chosen.estimatedBytes === null ? null : humanBytes(chosen.estimatedBytes),
+        }
+        : null;
+    const findings = [];
+    findings.push(`${stats.executionCount} execution records` +
+        (spanDays !== null ? ` spanning ${spanDays.toFixed(1)} days (${executionsPerDay.toFixed(1)}/day)` : ""));
+    if (recommendation && recommendation.prunableRows > 0) {
+        findings.push(`keeping ${keepDays} days would drop ${recommendation.prunableRows} rows` +
+            (recommendation.estimatedHumanFreed ? `, roughly ${recommendation.estimatedHumanFreed}` : ""));
+    }
+    else if (stats.executionCount > 0) {
+        findings.push(`nothing older than ${keepDays} days, retention is already tight`);
+    }
+    return {
+        executionCount: stats.executionCount,
+        oldestExecutionAt: stats.oldestExecutionAt,
+        newestExecutionAt: stats.newestExecutionAt,
+        spanDays: spanDays === null ? null : Number(spanDays.toFixed(2)),
+        executionsPerDay: executionsPerDay === null ? null : Number(executionsPerDay.toFixed(2)),
+        buckets,
+        recommendation,
+        findings,
+        hint: "n8n-guard never deletes. To act on this, set EXECUTIONS_DATA_PRUNE=true and " +
+            `EXECUTIONS_DATA_MAX_AGE=${keepDays * 24} (hours) on the n8n instance, then restart it.`,
+    };
+}
+//# sourceMappingURL=retention.js.map

package/dist/checks/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/checks/retention.ts"],"names":[],"mappings":"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"}

package/dist/checks/stuckExecutions.d.ts

@@ -0,0 +1,28 @@
+import type { N8nExecution } from "../n8n/api.js";
+import type { Severity } from "./dbHealth.js";
+export interface StuckExecution {
+    id: string;
+    workflowId: string | null;
+    startedAt: string | null;
+    runningForMinutes: number;
+    /** How many times the workflow's own median runtime this run has already taken. */
+    timesBaseline: number | null;
+    severity: Severity;
+    reason: string;
+}
+export interface StuckReport {
+    thresholdMinutes: number;
+    runningCount: number;
+    stuck: StuckExecution[];
+    /** Median runtime in seconds per workflow, derived from finished executions. */
+    baselineSecondsByWorkflow: Record<string, number>;
+    overallBaselineSeconds: number | null;
+    findings: string[];
+}
+export declare function median(values: number[]): number | null;
+/**
+ * Every other n8n MCP server lists executions by status. Listing is not
+ * detection: a run stuck in `running` looks exactly like a healthy long job
+ * until you compare it against what that workflow normally takes.
+ */
+export declare function findStuckExecutions(running: N8nExecution[], finished: N8nExecution[], thresholdMinutes: number, now?: number): StuckReport;

package/dist/checks/stuckExecutions.js

@@ -0,0 +1,95 @@
+function durationSeconds(execution) {
+    if (!execution.startedAt || !execution.stoppedAt)
+        return null;
+    const start = Date.parse(execution.startedAt);
+    const stop = Date.parse(execution.stoppedAt);
+    if (Number.isNaN(start) || Number.isNaN(stop) || stop < start)
+        return null;
+    return (stop - start) / 1000;
+}
+export function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? ((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
+}
+/**
+ * Every other n8n MCP server lists executions by status. Listing is not
+ * detection: a run stuck in `running` looks exactly like a healthy long job
+ * until you compare it against what that workflow normally takes.
+ */
+export function findStuckExecutions(running, finished, thresholdMinutes, now = Date.now()) {
+    const durationsByWorkflow = new Map();
+    const allDurations = [];
+    for (const execution of finished) {
+        const seconds = durationSeconds(execution);
+        if (seconds === null)
+            continue;
+        allDurations.push(seconds);
+        const key = String(execution.workflowId ?? "");
+        if (!key)
+            continue;
+        const bucket = durationsByWorkflow.get(key) ?? [];
+        bucket.push(seconds);
+        durationsByWorkflow.set(key, bucket);
+    }
+    const baselineSecondsByWorkflow = {};
+    for (const [workflowId, values] of durationsByWorkflow) {
+        const value = median(values);
+        if (value !== null)
+            baselineSecondsByWorkflow[workflowId] = value;
+    }
+    const overallBaselineSeconds = median(allDurations);
+    const stuck = [];
+    for (const execution of running) {
+        if (!execution.startedAt)
+            continue;
+        const started = Date.parse(execution.startedAt);
+        if (Number.isNaN(started))
+            continue;
+        const runningForMinutes = (now - started) / 60_000;
+        if (runningForMinutes < 0)
+            continue;
+        const workflowId = execution.workflowId ? String(execution.workflowId) : null;
+        const baseline = workflowId ? baselineSecondsByWorkflow[workflowId] ?? null : null;
+        const effectiveBaseline = baseline ?? overallBaselineSeconds;
+        const timesBaseline = effectiveBaseline && effectiveBaseline > 0 ? (runningForMinutes * 60) / effectiveBaseline : null;
+        const overThreshold = runningForMinutes >= thresholdMinutes;
+        // A run 20x its own median is suspicious even below the absolute threshold,
+        // but only once it is past a minute -- sub-second jobs make the ratio noisy.
+        const overBaseline = timesBaseline !== null && timesBaseline >= 20 && runningForMinutes >= 1;
+        if (!overThreshold && !overBaseline)
+            continue;
+        const reasons = [];
+        if (overThreshold)
+            reasons.push(`running ${runningForMinutes.toFixed(1)} min, threshold is ${thresholdMinutes} min`);
+        if (overBaseline)
+            reasons.push(`${timesBaseline.toFixed(0)}x the ${effectiveBaseline.toFixed(1)}s baseline for this workflow`);
+        stuck.push({
+            id: String(execution.id),
+            workflowId,
+            startedAt: execution.startedAt,
+            runningForMinutes: Number(runningForMinutes.toFixed(2)),
+            timesBaseline: timesBaseline === null ? null : Number(timesBaseline.toFixed(1)),
+            severity: overThreshold && runningForMinutes >= thresholdMinutes * 4 ? "critical" : "warning",
+            reason: reasons.join("; "),
+        });
+    }
+    stuck.sort((a, b) => b.runningForMinutes - a.runningForMinutes);
+    const findings = stuck.length === 0
+        ? [`no stuck executions among ${running.length} running`]
+        : [
+            `${stuck.length} of ${running.length} running executions are stuck`,
+            ...stuck.slice(0, 5).map((s) => `execution ${s.id} (workflow ${s.workflowId ?? "unknown"}): ${s.reason}`),
+        ];
+    return {
+        thresholdMinutes,
+        runningCount: running.length,
+        stuck,
+        baselineSecondsByWorkflow,
+        overallBaselineSeconds,
+        findings,
+    };
+}
+//# sourceMappingURL=stuckExecutions.js.map

package/dist/checks/stuckExecutions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuckExecutions.js","sourceRoot":"","sources":["../../src/checks/stuckExecutions.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Every setting comes from the environment. n8n-guard never assumes a host,
+ * container name, file path or account: it runs against whatever self-hosted
+ * instance the operator points it at.
+ */
+export interface GuardConfig {
+    /** Base URL of the n8n instance, e.g. http://localhost:5678 */
+    n8nUrl: string;
+    /** Public API key (Settings -> n8n API). Optional: without it API checks degrade. */
+    n8nApiKey: string | undefined;
+    /** Absolute path to database.sqlite when n8n runs on SQLite. */
+    sqlitePath: string | undefined;
+    /** Postgres connection string when n8n runs on Postgres. */
+    postgresUrl: string | undefined;
+    /** Path to a git checkout holding exported workflow JSON. */
+    gitRepoPath: string | undefined;
+    /** An execution running longer than this is reported as stuck. */
+    stuckThresholdMinutes: number;
+    /** Warn when the n8n datastore grows past this size. */
+    dbWarnBytes: number;
+    /** Treat the datastore as critical past this size. */
+    dbCriticalBytes: number;
+    /** Per-request timeout for the n8n API, in milliseconds. */
+    requestTimeoutMs: number;
+}
+export declare class ConfigError extends Error {
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): GuardConfig;

package/dist/config.js

@@ -0,0 +1,36 @@
+export class ConfigError extends Error {
+}
+function num(raw, fallback, name) {
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new ConfigError(`${name} must be a positive number, got ${JSON.stringify(raw)}`);
+    }
+    return parsed;
+}
+function trimmed(raw) {
+    const value = raw?.trim();
+    return value ? value : undefined;
+}
+export function loadConfig(env = process.env) {
+    const n8nUrl = trimmed(env.N8N_URL) ?? "http://localhost:5678";
+    try {
+        new URL(n8nUrl);
+    }
+    catch {
+        throw new ConfigError(`N8N_URL is not a valid URL: ${JSON.stringify(n8nUrl)}`);
+    }
+    return {
+        n8nUrl: n8nUrl.replace(/\/+$/, ""),
+        n8nApiKey: trimmed(env.N8N_API_KEY),
+        sqlitePath: trimmed(env.N8N_SQLITE_PATH),
+        postgresUrl: trimmed(env.N8N_POSTGRES_URL),
+        gitRepoPath: trimmed(env.N8N_GIT_REPO_PATH),
+        stuckThresholdMinutes: num(env.N8N_GUARD_STUCK_MINUTES, 15, "N8N_GUARD_STUCK_MINUTES"),
+        dbWarnBytes: num(env.N8N_GUARD_DB_WARN_BYTES, 1024 ** 3, "N8N_GUARD_DB_WARN_BYTES"),
+        dbCriticalBytes: num(env.N8N_GUARD_DB_CRITICAL_BYTES, 4 * 1024 ** 3, "N8N_GUARD_DB_CRITICAL_BYTES"),
+        requestTimeoutMs: num(env.N8N_GUARD_TIMEOUT_MS, 15_000, "N8N_GUARD_TIMEOUT_MS"),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AA0BA,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAEzC,SAAS,GAAG,CAAC,GAAuB,EAAE,QAAgB,EAAE,IAAY;IAClE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,WAAW,CAAC,GAAG,IAAI,mCAAmC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,OAAO,CAAC,GAAuB;IACtC,MAAM,KAAK,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC;IAC1B,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,uBAAuB,CAAC;IAC/D,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAClC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;QACnC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QACxC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAC1C,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC3C,qBAAqB,EAAE,GAAG,CAAC,GAAG,CAAC,uBAAuB,EAAE,EAAE,EAAE,yBAAyB,CAAC;QACtF,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,IAAI,CAAC,EAAE,yBAAyB,CAAC;QACnF,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,2BAA2B,EAAE,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,6BAA6B,CAAC;QACnG,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,oBAAoB,EAAE,MAAM,EAAE,sBAAsB,CAAC;KAChF,CAAC;AACJ,CAAC"}

package/dist/guard/runner.d.ts

@@ -0,0 +1,49 @@
+export type StepStatus = "ok" | "failed" | "skipped";
+export interface Step<T = unknown> {
+    name: string;
+    /** Human-readable purpose, surfaced in the report so a partial run still explains itself. */
+    description: string;
+    run: () => Promise<T>;
+    /** Extra attempts after the first one. Transient failures are the norm here. */
+    retries?: number;
+    /** Names of steps whose results this one needs. A failed dependency skips it. */
+    dependsOn?: string[];
+}
+export interface StepResult {
+    name: string;
+    description: string;
+    status: StepStatus;
+    attempts: number;
+    durationMs: number;
+    result?: unknown;
+    error?: string;
+    /** Set when the step was skipped: which dependency was not available. */
+    skippedBecause?: string;
+}
+export interface GuardRunReport {
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    /** true when at least one step failed but the run still produced results. */
+    degraded: boolean;
+    summary: {
+        ok: number;
+        failed: number;
+        skipped: number;
+    };
+    steps: StepResult[];
+    findings: string[];
+}
+export interface RunOptions {
+    /** Delay between retries; injectable so tests do not sleep. */
+    backoff?: (attempt: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * The recovery core. A monitoring run that aborts on the first unreachable
+ * dependency is worthless precisely when it matters: the API being down is the
+ * incident, not a reason to stop looking at the disk. Every step is isolated,
+ * retried, and its failure is reported as a finding rather than thrown.
+ */
+export declare function runSteps(steps: Step[], options?: RunOptions): Promise<GuardRunReport>;
+export declare function errorMessage(error: unknown): string;

package/dist/guard/runner.js

@@ -0,0 +1,95 @@
+const defaultBackoff = (attempt) => new Promise((resolve) => setTimeout(resolve, Math.min(250 * 2 ** (attempt - 1), 4000)));
+/**
+ * The recovery core. A monitoring run that aborts on the first unreachable
+ * dependency is worthless precisely when it matters: the API being down is the
+ * incident, not a reason to stop looking at the disk. Every step is isolated,
+ * retried, and its failure is reported as a finding rather than thrown.
+ */
+export async function runSteps(steps, options = {}) {
+    const backoff = options.backoff ?? defaultBackoff;
+    const now = options.now ?? Date.now;
+    const startedAtMs = now();
+    const results = [];
+    const byName = new Map();
+    for (const step of steps) {
+        const failedDependency = (step.dependsOn ?? []).find((dep) => byName.get(dep)?.status !== "ok");
+        if (failedDependency) {
+            const record = {
+                name: step.name,
+                description: step.description,
+                status: "skipped",
+                attempts: 0,
+                durationMs: 0,
+                skippedBecause: byName.has(failedDependency)
+                    ? `depends on ${failedDependency}, which ${byName.get(failedDependency).status}`
+                    : `depends on ${failedDependency}, which did not run`,
+            };
+            results.push(record);
+            byName.set(step.name, record);
+            continue;
+        }
+        const stepStart = now();
+        const maxAttempts = 1 + Math.max(0, step.retries ?? 0);
+        let attempts = 0;
+        let lastError;
+        let value;
+        let ok = false;
+        while (attempts < maxAttempts) {
+            attempts += 1;
+            try {
+                value = await step.run();
+                ok = true;
+                break;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempts < maxAttempts)
+                    await backoff(attempts);
+            }
+        }
+        const record = ok
+            ? { name: step.name, description: step.description, status: "ok", attempts, durationMs: now() - stepStart, result: value }
+            : {
+                name: step.name,
+                description: step.description,
+                status: "failed",
+                attempts,
+                durationMs: now() - stepStart,
+                error: errorMessage(lastError),
+            };
+        results.push(record);
+        byName.set(step.name, record);
+    }
+    const summary = {
+        ok: results.filter((r) => r.status === "ok").length,
+        failed: results.filter((r) => r.status === "failed").length,
+        skipped: results.filter((r) => r.status === "skipped").length,
+    };
+    const findings = [];
+    for (const record of results) {
+        if (record.status === "failed")
+            findings.push(`${record.name} failed after ${record.attempts} attempt(s): ${record.error}`);
+        if (record.status === "skipped")
+            findings.push(`${record.name} skipped: ${record.skippedBecause}`);
+    }
+    if (summary.failed === 0 && summary.skipped === 0)
+        findings.push(`all ${summary.ok} checks completed`);
+    else
+        findings.push(`${summary.ok} of ${results.length} checks completed despite the failures above`);
+    const finishedAtMs = now();
+    return {
+        startedAt: new Date(startedAtMs).toISOString(),
+        finishedAt: new Date(finishedAtMs).toISOString(),
+        durationMs: finishedAtMs - startedAtMs,
+        degraded: summary.failed > 0 || summary.skipped > 0,
+        summary,
+        steps: results,
+        findings,
+    };
+}
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+//# sourceMappingURL=runner.js.map

package/dist/guard/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/guard/runner.ts"],"names":[],"mappings":"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"}

package/dist/guard/service.d.ts

@@ -0,0 +1,42 @@
+import type { GuardConfig } from "../config.js";
+import { N8nApi } from "../n8n/api.js";
+import { type DatastoreStats } from "../n8n/datastore.js";
+import { type DbHealthReport } from "../checks/dbHealth.js";
+import { type StuckReport } from "../checks/stuckExecutions.js";
+import { type RetentionReport } from "../checks/retention.js";
+import { type GitDriftReport } from "../checks/gitDrift.js";
+import { type GuardRunReport, type RunOptions } from "./runner.js";
+export interface InstanceInfo {
+    url: string;
+    reachable: boolean;
+    detail: string;
+    apiKeyConfigured: boolean;
+    datastore: string;
+    gitRepoConfigured: boolean;
+    workflowCount: number | null;
+    activeWorkflowCount: number | null;
+}
+/**
+ * One place that knows how to read the instance. The MCP tool layer above it
+ * only formats; the check modules below it stay pure and testable.
+ */
+export declare class GuardService {
+    readonly config: GuardConfig;
+    readonly api: N8nApi;
+    constructor(config: GuardConfig);
+    instanceInfo(): Promise<InstanceInfo>;
+    datastoreStats(): Promise<DatastoreStats>;
+    dbHealth(stats?: DatastoreStats): Promise<DbHealthReport>;
+    stuckExecutions(thresholdMinutes?: number): Promise<StuckReport>;
+    retention(keepDays?: number, stats?: DatastoreStats): Promise<RetentionReport>;
+    gitDrift(): Promise<GitDriftReport>;
+    /**
+     * The background sweep for the `render` track: it survives a partial outage.
+     * A dead API still leaves disk and retention answerable; a missing git repo
+     * still leaves the API answerable. Failures become findings, not an abort.
+     */
+    fullRun(options?: {
+        keepDays?: number;
+        runOptions?: RunOptions;
+    }): Promise<GuardRunReport>;
+}

package/dist/guard/service.js

@@ -0,0 +1,128 @@
+import { N8nApi } from "../n8n/api.js";
+import { readDatastoreStats, resolveDatastoreKind } from "../n8n/datastore.js";
+import { assessDatabaseHealth, humanBytes } from "../checks/dbHealth.js";
+import { findStuckExecutions } from "../checks/stuckExecutions.js";
+import { analyzeRetention } from "../checks/retention.js";
+import { diffWorkflows, loadExportedWorkflows } from "../checks/gitDrift.js";
+import { runSteps } from "./runner.js";
+/**
+ * One place that knows how to read the instance. The MCP tool layer above it
+ * only formats; the check modules below it stay pure and testable.
+ */
+export class GuardService {
+    config;
+    api;
+    constructor(config) {
+        this.config = config;
+        this.api = new N8nApi(config);
+    }
+    async instanceInfo() {
+        const health = await this.api.health();
+        let workflows = null;
+        if (this.config.n8nApiKey) {
+            workflows = await this.api.listWorkflows().catch(() => null);
+        }
+        let datastore;
+        try {
+            datastore = resolveDatastoreKind(this.config);
+        }
+        catch {
+            datastore = "not configured";
+        }
+        return {
+            url: this.config.n8nUrl,
+            reachable: health.reachable,
+            detail: health.detail,
+            apiKeyConfigured: Boolean(this.config.n8nApiKey),
+            datastore,
+            gitRepoConfigured: Boolean(this.config.gitRepoPath),
+            workflowCount: workflows?.length ?? null,
+            activeWorkflowCount: workflows?.filter((w) => w.active).length ?? null,
+        };
+    }
+    datastoreStats() {
+        return readDatastoreStats(this.config);
+    }
+    async dbHealth(stats) {
+        const resolved = stats ?? (await this.datastoreStats());
+        return assessDatabaseHealth(resolved, {
+            warnBytes: this.config.dbWarnBytes,
+            criticalBytes: this.config.dbCriticalBytes,
+        });
+    }
+    async stuckExecutions(thresholdMinutes = this.config.stuckThresholdMinutes) {
+        const [running, success, failed] = await Promise.all([
+            this.api.listExecutions("running", 500),
+            this.api.listExecutions("success", 500),
+            this.api.listExecutions("error", 200),
+        ]);
+        const finished = [...success, ...failed];
+        return findStuckExecutions(running, finished, thresholdMinutes);
+    }
+    async retention(keepDays = 30, stats) {
+        const resolved = stats ?? (await this.datastoreStats());
+        return analyzeRetention(resolved, keepDays);
+    }
+    async gitDrift() {
+        if (!this.config.gitRepoPath) {
+            throw new Error("N8N_GIT_REPO_PATH is not set, so there is nothing to diff the instance against");
+        }
+        const [live, exported] = await Promise.all([
+            this.api.listWorkflows().then((list) => Promise.all(list.map((w) => this.api.getWorkflow(String(w.id))))),
+            loadExportedWorkflows(this.config.gitRepoPath),
+        ]);
+        return diffWorkflows(live, exported);
+    }
+    /**
+     * The background sweep for the `render` track: it survives a partial outage.
+     * A dead API still leaves disk and retention answerable; a missing git repo
+     * still leaves the API answerable. Failures become findings, not an abort.
+     */
+    async fullRun(options = {}) {
+        const keepDays = options.keepDays ?? 30;
+        let stats;
+        const steps = [
+            {
+                name: "instance",
+                description: "reach the n8n instance and read its workflow inventory",
+                retries: 2,
+                run: () => this.instanceInfo(),
+            },
+            {
+                name: "datastore",
+                description: "read size and row counts from the n8n datastore",
+                retries: 1,
+                run: async () => {
+                    stats = await this.datastoreStats();
+                    return { kind: stats.kind, totalBytes: stats.totalBytes, totalHuman: humanBytes(stats.totalBytes) };
+                },
+            },
+            {
+                name: "db_health",
+                description: "judge datastore size and growth against the configured thresholds",
+                dependsOn: ["datastore"],
+                run: () => this.dbHealth(stats),
+            },
+            {
+                name: "retention",
+                description: "estimate what pruning old executions would free",
+                dependsOn: ["datastore"],
+                run: () => this.retention(keepDays, stats),
+            },
+            {
+                name: "stuck_executions",
+                description: "detect executions stuck in running against their own baseline",
+                retries: 2,
+                run: () => this.stuckExecutions(),
+            },
+            {
+                name: "git_drift",
+                description: "compare live workflows against the exports in the git repository",
+                retries: 1,
+                run: () => this.gitDrift(),
+            },
+        ];
+        return runSteps(steps, options.runOptions);
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/guard/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/guard/service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAuC,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAuB,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAuB,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAoB,MAAM,8BAA8B,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAwB,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAuB,MAAM,uBAAuB,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAmD,MAAM,aAAa,CAAC;AAaxF;;;GAGG;AACH,MAAM,OAAO,YAAY;IAGF;IAFZ,GAAG,CAAS;IAErB,YAAqB,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;QACtC,IAAI,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QACvC,IAAI,SAAS,GAAyB,IAAI,CAAC;QAC3C,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAC1B,SAAS,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,SAAiB,CAAC;QACtB,IAAI,CAAC;YACH,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,GAAG,gBAAgB,CAAC;QAC/B,CAAC;QACD,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YACvB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,gBAAgB,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YAChD,SAAS;YACT,iBAAiB,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;YACnD,aAAa,EAAE,SAAS,EAAE,MAAM,IAAI,IAAI;YACxC,mBAAmB,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,IAAI;SACvE,CAAC;IACJ,CAAC;IAED,cAAc;QACZ,OAAO,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,KAAsB;QACnC,MAAM,QAAQ,GAAG,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QACxD,OAAO,oBAAoB,CAAC,QAAQ,EAAE;YACpC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YAClC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe;SAC3C,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB;QACxE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACnD,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE,GAAG,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,SAAS,EAAE,GAAG,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC;SACtC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAmB,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC;QACzD,OAAO,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAQ,GAAG,EAAE,EAAE,KAAsB;QACnD,MAAM,QAAQ,GAAG,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QACxD,OAAO,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;QACpG,CAAC;QACD,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACzC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACzG,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;SAC/C,CAAC,CAAC;QACH,OAAO,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,UAA0D,EAAE;QACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QACxC,IAAI,KAAiC,CAAC;QAEtC,MAAM,KAAK,GAAW;YACpB;gBACE,IAAI,EAAE,UAAU;gBAChB,WAAW,EAAE,wDAAwD;gBACrE,OAAO,EAAE,CAAC;gBACV,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE;aAC/B;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,iDAAiD;gBAC9D,OAAO,EAAE,CAAC;gBACV,GAAG,EAAE,KAAK,IAAI,EAAE;oBACd,KAAK,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;oBACpC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;gBACtG,CAAC;aACF;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,mEAAmE;gBAChF,SAAS,EAAE,CAAC,WAAW,CAAC;gBACxB,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;aAChC;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,iDAAiD;gBAC9D,SAAS,EAAE,CAAC,WAAW,CAAC;gBACxB,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC;aAC3C;YACD;gBACE,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EAAE,+DAA+D;gBAC5E,OAAO,EAAE,CAAC;gBACV,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE;aAClC;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,kEAAkE;gBAC/E,OAAO,EAAE,CAAC;gBACV,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE;aAC3B;SACF,CAAC;QAEF,OAAO,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+async function main() {
+    const config = loadConfig();
+    const server = createServer(config);
+    // stdout carries the protocol, so every human-facing line goes to stderr.
+    console.error(`${SERVER_NAME} ${SERVER_VERSION} watching ${config.n8nUrl}`);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    console.error(`${SERVER_NAME} failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,0EAA0E;IAC1E,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,IAAI,cAAc,aAAa,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,qBAAqB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3G,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}