@plainconceptsplatform/loop-task 2.6.0

package/dist/core/loop/run-executor.js

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import { executeCommand } from "../command/command-runner.js";
+import { rotateLogIfNeeded } from "../logging/log-rotator.js";
+import { mergeCommandOutput } from "../context/context-parser.js";
+import { formatContextLog } from "../context/log-context.js";
+import { interpolate } from "../context/template.js";
+import { resolveEffectiveCwd } from "../command/resolve-cwd.js";
+export async function executeRunImpl(ctrl, signal) {
+    ctrl._status = "running";
+    ctrl._forceRun = false;
+    ctrl.runCount++;
+    ctrl.lastRunAt = new Date().toISOString();
+    if (ctrl.sessionStartedAt === null) {
+        ctrl.sessionStartedAt = ctrl.lastRunAt;
+    }
+    ctrl.nextRunAt = null;
+    ctrl.emit("run:start", ctrl.runCount);
+    ctrl.logStream = rotateLogIfNeeded(ctrl.logPath, ctrl.logStream);
+    ctrl.currentRunStartOffset = fs.existsSync(ctrl.logPath) ? fs.statSync(ctrl.logPath).size : 0;
+    ctrl.runHistory.push({
+        runNumber: ctrl.runCount,
+        startedAt: ctrl.lastRunAt,
+        exitCode: -1,
+        duration: 0,
+        logSize: 0,
+        status: "running",
+        logOffset: ctrl.currentRunStartOffset,
+    });
+    ctrl.runAbortController = new AbortController();
+    const task = ctrl.options.taskId ? ctrl.taskResolver(ctrl.options.taskId) : null;
+    const cwd = resolveEffectiveCwd(ctrl.options.cwd, ctrl.projectDirectory);
+    const chainContext = { ...(task?.context ?? {}), ...(ctrl.options.context ?? {}) };
+    const hasChainTasks = !!(task?.onSuccessTaskId || task?.onFailureTaskId);
+    const singleCommandFallback = {
+        command: task?.command ?? ctrl.options.command,
+        commandArgs: task?.commandArgs ?? ctrl.options.commandArgs,
+        commandRaw: task?.commandRaw ?? ctrl.options.commandRaw,
+    };
+    const taskSteps = task?.steps?.length
+        ? task.steps
+        : [{ commands: [singleCommandFallback] }];
+    const shouldCaptureStdout = hasChainTasks || taskSteps.length > 1 || taskSteps[0].commands.length > 1;
+    // Telemetry: create loop run span
+    const telemetry = ctrl.telemetryManager?.getAdapter();
+    const runId = `${ctrl.id}-${ctrl.runCount}`;
+    const loopSpan = telemetry?.startLoop({
+        loopId: ctrl.id,
+        loopName: ctrl.options.description || ctrl.id,
+        runId,
+        projectId: ctrl.options.projectId,
+    });
+    // Telemetry: create task span
+    const taskSpan = (task && telemetry)
+        ? telemetry.startTask({
+            taskId: task.id,
+            taskName: task.name,
+            runId,
+            loopId: ctrl.id,
+            loopName: ctrl.options.description || ctrl.id,
+            projectId: ctrl.options.projectId,
+        }, loopSpan)
+        : undefined;
+    // Build telemetry context for commands
+    const telemetryCtx = telemetry
+        ? {
+            telemetry,
+            loopSpan,
+            taskSpan,
+            runId,
+            loopId: ctrl.id,
+            loopName: ctrl.options.description || ctrl.id,
+            taskId: task?.id,
+            taskName: task?.name,
+            projectId: ctrl.options.projectId,
+            telemetryConfig: task?.telemetry,
+        }
+        : undefined;
+    let exitCode = 0;
+    let totalDuration = 0;
+    try {
+        ctrl.logStream?.write(formatContextLog(chainContext));
+        for (const step of taskSteps) {
+            if (signal.aborted || ctrl.runAbortController?.signal.aborted)
+                break;
+            const stepResults = await Promise.allSettled(step.commands.map((cmd) => executeCommand(interpolate(cmd.command, chainContext), cmd.commandArgs.map(a => interpolate(a, chainContext)), cwd, ctrl.logStream, AbortSignal.any([signal, ctrl.runAbortController.signal]), ctrl.runCount, shouldCaptureStdout, false, telemetryCtx)));
+            if (signal.aborted || ctrl.runAbortController?.signal.aborted)
+                break;
+            ctrl.checkLogRotation();
+            let stepStdout = "";
+            let stepStderr = "";
+            for (const r of stepResults) {
+                if (r.status === "fulfilled") {
+                    totalDuration += r.value.duration;
+                    if (r.value.stdout)
+                        stepStdout += (stepStdout ? "\n" : "") + r.value.stdout;
+                    if (r.value.stderr)
+                        stepStderr += (stepStderr ? "\n" : "") + r.value.stderr;
+                }
+            }
+            if (shouldCaptureStdout && (stepStdout || stepStderr)) {
+                mergeCommandOutput(chainContext, stepStdout, stepStderr);
+            }
+            const stepFailure = stepResults.some((r) => r.status === "rejected" || (r.status === "fulfilled" && r.value.exitCode !== 0));
+            if (stepFailure) {
+                const failed = stepResults.find((r) => r.status === "fulfilled" && r.value.exitCode !== 0);
+                exitCode = failed ? failed.value.exitCode : 1;
+                break;
+            }
+        }
+    }
+    finally {
+        // End telemetry spans
+        if (taskSpan) {
+            taskSpan.end(exitCode === 0 ? "ok" : "error");
+        }
+        if (loopSpan) {
+            loopSpan.end(exitCode === 0 ? "ok" : "error");
+        }
+    }
+    ctrl.runAbortController = null;
+    ctrl.lastExitCode = exitCode;
+    ctrl.lastDuration = totalDuration;
+    ctrl.checkLogRotation();
+    const logSize = fs.existsSync(ctrl.logPath) ? fs.statSync(ctrl.logPath).size - ctrl.currentRunStartOffset : 0;
+    const runningRecord = ctrl.runHistory.find((r) => r.runNumber === ctrl.runCount);
+    if (runningRecord) {
+        runningRecord.exitCode = exitCode;
+        runningRecord.duration = totalDuration;
+        runningRecord.logSize = Math.max(0, logSize);
+        runningRecord.status = "completed";
+    }
+    else {
+        ctrl.runHistory.push({
+            runNumber: ctrl.runCount,
+            startedAt: ctrl.lastRunAt,
+            exitCode,
+            duration: totalDuration,
+            logSize: Math.max(0, logSize),
+            status: "completed",
+            logOffset: ctrl.currentRunStartOffset,
+        });
+    }
+    return { exitCode, totalDuration, chainContext, runId, loopSpan };
+}

package/dist/core/loop/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/scheduling/index.js

@@ -0,0 +1,16 @@
+export function computePhase(loopId, intervalMs) {
+    if (intervalMs <= 0)
+        return 0;
+    let hash = 0;
+    for (let i = 0; i < loopId.length; i++) {
+        hash = ((hash << 5) - hash + loopId.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash) % intervalMs;
+}
+export function alignToPhase(now, intervalMs, phaseMs) {
+    if (intervalMs <= 0)
+        return 0;
+    const elapsed = now % intervalMs;
+    const delay = (phaseMs - elapsed + intervalMs) % intervalMs;
+    return delay;
+}

package/dist/daemon/daemon-log.js

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+import { getDataDir, getDaemonLogFile } from "../shared/config/paths.js";
+export function daemonLog(message) {
+    try {
+        fs.mkdirSync(getDataDir(), { recursive: true });
+        fs.appendFileSync(getDaemonLogFile(), `${new Date().toISOString()} ${message}\n`);
+    }
+    catch {
+        // operational logging is best effort
+    }
+}

package/dist/daemon/diagnostics.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+let activePidsGetter = null;
+export function setActivePidsGetter(getter) {
+    activePidsGetter = getter;
+}
+export function collectDiagnostics(loopManager, extended = false) {
+    const usage = process.memoryUsage();
+    const loops = loopManager.list();
+    let running = 0;
+    let paused = 0;
+    let idle = 0;
+    let totalRunHistory = 0;
+    for (const loop of loops) {
+        switch (loop.status) {
+            case "running":
+            case "waiting":
+                running++;
+                break;
+            case "paused":
+                paused++;
+                break;
+            default:
+                idle++;
+                break;
+        }
+        totalRunHistory += loop.runHistory.length;
+    }
+    const result = {
+        process: {
+            rss: usage.rss,
+            heapUsed: usage.heapUsed,
+            heapTotal: usage.heapTotal,
+            external: usage.external,
+            arrayBuffers: usage.arrayBuffers,
+        },
+        loops: {
+            total: loops.length,
+            running,
+            paused,
+            idle,
+            totalRunHistory,
+        },
+        activeExecutions: running,
+        timestamp: new Date().toISOString(),
+    };
+    if (extended) {
+        const eventListenerCounts = {};
+        try {
+            const counts = process._getActiveRequests;
+            if (typeof counts === "function") {
+                eventListenerCounts.activeRequests = counts().length;
+            }
+        }
+        catch { /* not available */ }
+        try {
+            const handles = process._getActiveHandles;
+            if (typeof handles === "function") {
+                eventListenerCounts.activeHandles = handles().length;
+            }
+        }
+        catch { /* not available */ }
+        let activeFileDescriptors = null;
+        try {
+            activeFileDescriptors = fs.readdirSync("/proc/self/fd").length;
+        }
+        catch { /* not available on non-Linux */ }
+        let activeChildPids = [];
+        try {
+            if (activePidsGetter) {
+                activeChildPids = [...activePidsGetter()];
+            }
+        }
+        catch { /* not available */ }
+        result.extended = {
+            eventListenerCounts,
+            activeFileDescriptors,
+            activeChildPids,
+        };
+    }
+    return result;
+}
+const DIAGNOSTICS_ENV_VAR = "LOOP_TASK_DIAGNOSTICS";
+export function isDiagnosticsEnabled() {
+    return process.env[DIAGNOSTICS_ENV_VAR] === "1" || process.env[DIAGNOSTICS_ENV_VAR] === "true";
+}

package/dist/daemon/http/helpers.js

@@ -0,0 +1,81 @@
+// --- Response helpers ---
+export function sendJson(res, status, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+export function sendOk(res, data, status = 200) {
+    sendJson(res, status, { ok: true, data: data ?? null });
+}
+export function sendError(res, status, message) {
+    sendJson(res, status, { ok: false, error: { message } });
+}
+export function sendNotFound(res, id) {
+    sendError(res, 404, `Not found: ${id}`);
+}
+export function matchRoute(routes, method, pathSegments) {
+    for (const route of routes) {
+        if (route.method !== method)
+            continue;
+        if (route.segments.length !== pathSegments.length)
+            continue;
+        const params = {};
+        let matched = true;
+        for (let i = 0; i < route.segments.length; i++) {
+            const routeSeg = route.segments[i];
+            const pathSeg = pathSegments[i];
+            if (routeSeg.startsWith(":")) {
+                params[routeSeg.slice(1)] = decodeURIComponent(pathSeg);
+            }
+            else if (routeSeg !== pathSeg) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched) {
+            return { params, handler: route.handler };
+        }
+    }
+    return null;
+}
+// --- Request parsing ---
+export function parsePath(url) {
+    if (!url)
+        return [];
+    const pathname = url.split("?")[0] ?? "";
+    return pathname.split("/").filter((s) => s.length > 0);
+}
+export function parseQuery(url) {
+    if (!url)
+        return new URLSearchParams();
+    const qs = url.split("?")[1] ?? "";
+    return new URLSearchParams(qs);
+}
+export async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+            if (body.length > 1024 * 1024) {
+                reject(new Error("Body too large"));
+                req.destroy();
+            }
+        });
+        req.on("end", () => {
+            if (!body.trim()) {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(body));
+            }
+            catch {
+                reject(new Error("Invalid JSON body"));
+            }
+        });
+        req.on("error", reject);
+    });
+}

package/dist/daemon/http/openapi.js

@@ -0,0 +1,119 @@
+import { HTTP_API_HOST, HTTP_API_PORT } from "../../shared/config/constants.js";
+export function buildOpenApiSpec() {
+    return {
+        openapi: "3.0.3",
+        info: {
+            title: "loop-task HTTP API",
+            version: "1.0.0",
+            description: "REST + SSE API for managing loops, tasks, projects, and logs. Binds to all interfaces (0.0.0.0) by default so it is reachable remotely; the bind host is configurable via `loop-task http-host`. The API is unauthenticated, secure access at the network layer (SSH/Tailscale/firewall), or restrict the bind to 127.0.0.1.",
+        },
+        servers: [
+            { url: `http://${HTTP_API_HOST}:${HTTP_API_PORT}`, description: "Local daemon" },
+        ],
+        tags: [
+            { name: "Loops", description: "Loop management" },
+            { name: "Tasks", description: "Task management" },
+            { name: "Task Chains", description: "Create chained tasks" },
+            { name: "Projects", description: "Project management" },
+            { name: "Logs", description: "Log retrieval" },
+            { name: "Events", description: "Server-sent events" },
+            { name: "Settings", description: "Daemon settings" },
+            { name: "MCP", description: "Model Context Protocol server" },
+            { name: "Docs", description: "API documentation" },
+        ],
+        paths: {
+            "/api/loops": {
+                get: { summary: "List all loops", tags: ["Loops"], responses: { "200": { description: "Array of loops", content: { "application/json": { schema: { type: "array" } } } } } },
+                post: { summary: "Create a new loop", tags: ["Loops"], requestBody: { content: { "application/json": { schema: { type: "object", properties: { command: { type: "string" }, commandArgs: { type: "array", items: { type: "string" } }, intervalHuman: { type: "string", example: "5m", description: "Interval like 30s, 5m, 1h, or 'manual' for trigger-only loops" }, cwd: { type: "string" }, description: { type: "string" }, taskId: { type: "string" }, now: { type: "boolean" }, maxRuns: { type: "integer" }, verbose: { type: "boolean" }, projectId: { type: "string" }, offset: { type: "integer" }, context: { type: "object", additionalProperties: true, description: "Initial context for chain interpolation" } } } } } }, responses: { "201": { description: "Loop created", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" } } } } } }, "400": { description: "Validation error" } } },
+            },
+            "/api/loops/{id}": {
+                get: { summary: "Get loop status", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Loop details" }, "404": { description: "Not found" } } },
+                patch: { summary: "Update a loop", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], requestBody: { content: { "application/json": { schema: { type: "object" } } } }, responses: { "200": { description: "Updated" }, "400": { description: "Validation error" }, "404": { description: "Not found" } } },
+                delete: { summary: "Delete a loop", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Deleted" }, "404": { description: "Not found" } } },
+            },
+            "/api/loops/{id}/pause": { post: { summary: "Pause a loop", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Paused" }, "404": { description: "Not found" } } } },
+            "/api/loops/{id}/resume": { post: { summary: "Resume a loop", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Resumed" }, "404": { description: "Not found" } } } },
+            "/api/loops/{id}/play": { post: { summary: "Play (start) a loop", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Playing", content: { "application/json": { schema: { type: "object" } } } }, "404": { description: "Not found" }, "409": { description: "Already running or max runs blocked" } } } },
+            "/api/loops/{id}/trigger": { post: { summary: "Trigger a loop now", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Triggered" }, "404": { description: "Not found" }, "400": { description: "Max runs reached" }, "409": { description: "Already running" } } } },
+            "/api/loops/{id}/stop": { post: { summary: "Stop a loop", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Stopped" }, "404": { description: "Not found" } } } },
+            "/api/loops/stop-all": { post: { summary: "Stop all loops", tags: ["Loops"], responses: { "200": { description: "All stopped", content: { "application/json": { schema: { type: "object", properties: { count: { type: "integer" } } } } } } } } },
+            "/api/loops/{id}/runs": { get: { summary: "List run history", tags: ["Loops"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }, { name: "from", in: "query", schema: { type: "string", description: "ISO 8601 date" } }, { name: "to", in: "query", schema: { type: "string", description: "ISO 8601 date" } }], responses: { "200": { description: "Run records", content: { "application/json": { schema: { type: "array" } } } }, "404": { description: "Not found" } } } },
+            "/api/loops/{id}/logs/date": { get: { summary: "Date-filtered logs", tags: ["Logs"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }, { name: "from", in: "query", required: true, schema: { type: "string", description: "ISO 8601 start date" } }, { name: "to", in: "query", required: true, schema: { type: "string", description: "ISO 8601 end date" } }], responses: { "200": { description: "Filtered log content" }, "404": { description: "Not found" }, "400": { description: "Missing or invalid date params" } } } },
+            "/api/loops/{id}/logs": { get: { summary: "Fetch loop logs", tags: ["Logs"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }, { name: "tail", in: "query", schema: { type: "integer", default: 50 } }], responses: { "200": { description: "Log content" }, "404": { description: "Not found" } } } },
+            "/api/loops/{id}/logs/stream": { get: { summary: "Stream logs via SSE", tags: ["Logs"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }, { name: "tail", in: "query", schema: { type: "integer" } }], responses: { "200": { description: "SSE stream" }, "404": { description: "Not found" } } } },
+            "/api/loops/{id}/runs/{num}": { get: { summary: "Get run-specific log", tags: ["Logs"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }, { name: "num", in: "path", required: true, schema: { type: "integer" } }], responses: { "200": { description: "Run log content" } } } },
+            "/api/tasks": {
+                get: { summary: "List all tasks", tags: ["Tasks"], responses: { "200": { description: "Array of tasks" } } },
+                post: { summary: "Create a task", tags: ["Tasks"], requestBody: { content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, name: { type: "string" }, command: { type: "string" }, commandArgs: { type: "array", items: { type: "string" } }, onSuccessTaskId: { type: "string" }, onFailureTaskId: { type: "string" }, maxRuns: { type: "integer" }, context: { type: "object", additionalProperties: true, description: "Initial context for chain interpolation" } } } } } }, responses: { "201": { description: "Task created" }, "400": { description: "Validation error" } } },
+            },
+            "/api/tasks/{id}": {
+                get: { summary: "Get a task", tags: ["Tasks"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Task details" }, "404": { description: "Not found" } } },
+                patch: { summary: "Update a task", tags: ["Tasks"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], requestBody: { content: { "application/json": { schema: { type: "object" } } } }, responses: { "200": { description: "Updated" }, "404": { description: "Not found" } } },
+                delete: { summary: "Delete a task", tags: ["Tasks"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Deleted" }, "404": { description: "Not found" } } },
+            },
+            "/api/task-chains": { post: { summary: "Create a chain of tasks", tags: ["Task Chains"], requestBody: { content: { "application/json": { schema: { type: "object", required: ["tasks"], properties: { tasks: { type: "array", items: { type: "object", properties: { id: { type: "string" }, name: { type: "string" }, command: { type: "string" }, commandArgs: { type: "array", items: { type: "string" } }, onSuccessTaskId: { type: "string" }, onFailureTaskId: { type: "string" }, maxRuns: { type: "integer" } } } }, chain: { type: "string", enum: ["sequential-success", "sequential-failure", "none"], description: "How to wire tasks together" } } } } } }, responses: { "201": { description: "Chain created", content: { "application/json": { schema: { type: "object", properties: { taskIds: { type: "array", items: { type: "string" } } } } } } }, "400": { description: "Validation error or rollback" } } } },
+            "/api/projects": {
+                get: { summary: "List all projects", tags: ["Projects"], responses: { "200": { description: "Array of projects" } } },
+                post: { summary: "Create a project", tags: ["Projects"], requestBody: { content: { "application/json": { schema: { type: "object", properties: { name: { type: "string" }, color: { type: "string" }, directory: { type: "string", description: "Optional local working directory for loops" }, githubSource: { type: "string", description: "Optional GitHub repository in owner/repo format (e.g. CKGrafico/loop-task)" } } } } } }, responses: { "201": { description: "Project created" }, "400": { description: "Validation error" } } },
+            },
+            "/api/projects/{id}": {
+                patch: { summary: "Update a project", tags: ["Projects"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], requestBody: { content: { "application/json": { schema: { type: "object", properties: { name: { type: "string" }, color: { type: "string" }, directory: { type: "string", description: "Optional local working directory for loops" }, githubSource: { type: "string", description: "Optional GitHub repository in owner/repo format (e.g. CKGrafico/loop-task)" } } } } } }, responses: { "200": { description: "Updated" }, "404": { description: "Not found" }, "400": { description: "Validation error" } } },
+                delete: { summary: "Delete a project", tags: ["Projects"], parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "Deleted" }, "400": { description: "Cannot delete system project" } } },
+            },
+            "/api/settings": { get: { summary: "Get daemon settings", tags: ["Settings"], responses: { "200": { description: "Current settings", content: { "application/json": { schema: { type: "object", properties: { httpApiEnabled: { type: "boolean" }, mcpApiEnabled: { type: "boolean" } } } } } } } }, patch: { summary: "Update daemon settings", tags: ["Settings"], requestBody: { content: { "application/json": { schema: { type: "object", properties: { httpApiEnabled: { type: "boolean" }, mcpApiEnabled: { type: "boolean" } } } } } }, responses: { "200": { description: "Updated settings", content: { "application/json": { schema: { type: "object", properties: { httpApiEnabled: { type: "boolean" }, mcpApiEnabled: { type: "boolean" } } } } } }, "400": { description: "Validation error" } } } },
+            "/api/events": { get: { summary: "Subscribe to daemon events via SSE", tags: ["Events"], responses: { "200": { description: "SSE event stream" } } } },
+            "/api/openapi.json": { get: { summary: "OpenAPI 3.0 spec", tags: ["Docs"], responses: { "200": { description: "OpenAPI JSON spec" } } } },
+            "/api/docs": { get: { summary: "Swagger UI", tags: ["Docs"], responses: { "200": { description: "HTML page" } } } },
+        },
+        components: {
+            schemas: {
+                DaemonSettings: {
+                    type: "object",
+                    properties: {
+                        httpApiEnabled: { type: "boolean", description: "Whether the HTTP API server is enabled" },
+                        mcpApiEnabled: { type: "boolean", description: "Whether the MCP server is enabled" },
+                    },
+                },
+            },
+        },
+    };
+}
+export function buildSwaggerHtml() {
+    const specUrl = "/api/openapi.json";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>loop-task API</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+  <style>
+    body { margin: 0; }
+    .swagger-ui { max-width: 1200px; margin: 0 auto; }
+    .header { background: #0d1117; color: #58a6ff; padding: 12px 24px; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; font-size: 14px; }
+    .header a { color: #58a6ff; text-decoration: none; }
+    .header a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <strong>loop-task HTTP API</strong> &mdash;
+    <a href="/api/openapi.json">OpenAPI JSON</a> &mdash;
+    <a href="/api/docs">Swagger UI</a>
+  </div>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    window.onload = function() {
+      window.ui = SwaggerUIBundle({
+        url: "${specUrl}",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        presets: [SwaggerUIBundle.presets.apis],
+        layout: "BaseLayout",
+      });
+    };
+  </script>
+</body>
+</html>`;
+}