@xfey/tutti 0.1.0

package/dist/artifacts/preview-runtime.js

@@ -0,0 +1,585 @@
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { redactAndTruncateText } from "@tutti/shared/utils";
+import { WorkspaceOpsError } from "../workspace-ops/errors.js";
+import { ARTIFACT_PREVIEW_BASE_PATH, readArtifactDeclaration, } from "./manifest.js";
+import { rewriteArtifactPreviewResourceUrls } from "./static-preview.js";
+const DEFAULT_READY_TIMEOUT_MS = 20_000;
+const DEFAULT_READY_PROBE_INTERVAL_MS = 250;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const DEFAULT_IDLE_STOP_TTL_MS = 120_000;
+const MAX_DIAGNOSTIC_CHARS = 8_000;
+const MIN_DYNAMIC_PORT = 49152;
+const MAX_DYNAMIC_PORT = 65535;
+const SAFE_ENV_NAMES = new Set([
+    "PATH",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+]);
+const RESPONSE_HEADER_DENYLIST = new Set([
+    "connection",
+    "content-length",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "set-cookie",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "www-authenticate",
+]);
+function defaultAllocatePort() {
+    const range = MAX_DYNAMIC_PORT - MIN_DYNAMIC_PORT + 1;
+    return MIN_DYNAMIC_PORT + Math.floor(Math.random() * range);
+}
+function defaultSpawnProcess(plan) {
+    const child = spawn(plan.command, plan.args, {
+        cwd: plan.cwd,
+        env: plan.env,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stdin.end();
+    return child;
+}
+function createArtifactPreviewEnv(options) {
+    const env = {};
+    for (const name of SAFE_ENV_NAMES) {
+        const value = options.sourceEnv[name];
+        if (value !== undefined && value.trim() !== "") {
+            env[name] = value;
+        }
+    }
+    env.HOME = tmpdir();
+    env.TMPDIR = env.TMPDIR ?? tmpdir();
+    env.HOST = "127.0.0.1";
+    env.PORT = String(options.port);
+    env.TUTTI_ARTIFACT_PREVIEW = "1";
+    env.npm_config_update_notifier = "false";
+    env.npm_config_fund = "false";
+    env.npm_config_audit = "false";
+    return env;
+}
+function appendDiagnostic(existing, chunk) {
+    const next = `${existing}${redactAndTruncateText(chunk.toString("utf8"), MAX_DIAGNOSTIC_CHARS)}`;
+    if (next.length <= MAX_DIAGNOSTIC_CHARS) {
+        return next;
+    }
+    return next.slice(next.length - MAX_DIAGNOSTIC_CHARS);
+}
+function serverDeclarationKey(declaration) {
+    return [
+        declaration.manifest_blob_oid,
+        declaration.runtime.cwd_path,
+        declaration.runtime.ready_path,
+    ].join(":");
+}
+function buildServerPreviewUrl(options) {
+    const basePath = (options.basePath ?? ARTIFACT_PREVIEW_BASE_PATH).replace(/\/+$/u, "");
+    const normalizedReadyPath = options.readyPath === "/" ? "/" : `/${options.readyPath.replace(/^\/+/u, "")}`;
+    const separator = normalizedReadyPath.includes("?") ? "&" : "?";
+    return `${basePath}${normalizedReadyPath}${separator}v=${encodeURIComponent(options.manifestBlobOid)}&preview=${encodeURIComponent(options.instanceId)}`;
+}
+function isServerDeclaration(declaration) {
+    return declaration.status === "declared" && declaration.runtime.kind === "server";
+}
+function declarationInvalidDisposition(declaration) {
+    const disposition = {
+        kind: "invalid_manifest",
+        message: declaration.projection.error.message,
+    };
+    return {
+        start: disposition,
+        heartbeat: disposition,
+        stop: disposition,
+    };
+}
+function projectionWithServerState(options) {
+    const artifact = options.declaration.manifest.artifact;
+    const baseProjection = {
+        status: "declared",
+        manifest_path: "tutti.artifact.json",
+        manifest_blob_oid: options.declaration.manifest_blob_oid,
+        artifact: {
+            title: artifact.title,
+            kind: "server",
+            network: artifact.network ?? false,
+        },
+        preview: {
+            status: "stopped",
+        },
+    };
+    const state = options.state;
+    if (state === undefined || state.key !== serverDeclarationKey(options.declaration)) {
+        return baseProjection;
+    }
+    if (state.status === "ready") {
+        return {
+            ...baseProjection,
+            preview: {
+                status: "ready",
+                url: buildServerPreviewUrl({
+                    basePath: options.previewBasePath,
+                    readyPath: state.readyPath,
+                    manifestBlobOid: state.manifestBlobOid,
+                    instanceId: state.instanceId,
+                }),
+            },
+        };
+    }
+    return {
+        ...baseProjection,
+        preview: {
+            status: state.status,
+            ...(state.errorMessage === undefined ? {} : { error_message: state.errorMessage }),
+        },
+    };
+}
+function filteredResponseHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        const normalized = key.toLowerCase();
+        if (!RESPONSE_HEADER_DENYLIST.has(normalized)) {
+            result[normalized] = value;
+        }
+    });
+    return result;
+}
+function normalizePreviewRequestPath(path) {
+    if (path === undefined || path.trim() === "") {
+        return "/";
+    }
+    const withoutQuery = path.split("?")[0] ?? "";
+    const normalized = withoutQuery.startsWith("/") ? withoutQuery : `/${withoutQuery}`;
+    if (normalized.includes("..")) {
+        throw new WorkspaceOpsError("forbidden", "Artifact preview path is not allowed");
+    }
+    return normalized;
+}
+export class ArtifactPreviewManager {
+    now;
+    baseEnv;
+    spawnProcess;
+    fetchImpl;
+    allocatePort;
+    clockMs;
+    setTimeoutFn;
+    clearTimeoutFn;
+    onStatusChange;
+    readyTimeoutMs;
+    readyProbeIntervalMs;
+    requestTimeoutMs;
+    idleStopTtlMs;
+    state;
+    nextInstanceSequence = 0;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date());
+        this.baseEnv = options.baseEnv ?? process.env;
+        this.spawnProcess = options.spawnProcess ?? defaultSpawnProcess;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.allocatePort = options.allocatePort ?? defaultAllocatePort;
+        this.clockMs = options.clockMs ?? (() => Date.now());
+        this.setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+        this.clearTimeoutFn = options.clearTimeoutFn ?? clearTimeout;
+        this.onStatusChange = options.onStatusChange ?? (() => { });
+        this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+        this.readyProbeIntervalMs = options.readyProbeIntervalMs ?? DEFAULT_READY_PROBE_INTERVAL_MS;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.idleStopTtlMs = options.idleStopTtlMs ?? DEFAULT_IDLE_STOP_TTL_MS;
+    }
+    readProjection(options) {
+        const declaration = readArtifactDeclaration({
+            workspaceRoot: options.workspaceRoot,
+            previewBasePath: options.previewBasePath,
+            now: this.now,
+        });
+        this.stopStaleRuntime(declaration);
+        return {
+            artifact: isServerDeclaration(declaration)
+                ? projectionWithServerState({
+                    declaration,
+                    state: this.state,
+                    previewBasePath: options.previewBasePath,
+                })
+                : declaration.projection,
+        };
+    }
+    start(options) {
+        const declaration = readArtifactDeclaration({
+            workspaceRoot: options.workspaceRoot,
+            previewBasePath: options.previewBasePath,
+            now: this.now,
+        });
+        this.stopStaleRuntime(declaration);
+        if (declaration.status === "not_declared") {
+            return {
+                disposition: { kind: "not_declared" },
+                result: { artifact: declaration.projection },
+            };
+        }
+        if (declaration.status === "invalid") {
+            return {
+                disposition: declarationInvalidDisposition(declaration).start,
+                result: { artifact: declaration.projection },
+            };
+        }
+        if (!isServerDeclaration(declaration)) {
+            return {
+                disposition: { kind: "unsupported" },
+                result: { artifact: declaration.projection },
+            };
+        }
+        const key = serverDeclarationKey(declaration);
+        if (this.state?.key === key) {
+            if (this.state.status === "ready") {
+                this.recordHeartbeat(this.state);
+                return {
+                    disposition: { kind: "already_running" },
+                    result: {
+                        artifact: projectionWithServerState({
+                            declaration,
+                            state: this.state,
+                            previewBasePath: options.previewBasePath,
+                        }),
+                    },
+                };
+            }
+            if (this.state.status === "starting") {
+                this.recordHeartbeat(this.state);
+                return {
+                    disposition: { kind: "starting" },
+                    result: {
+                        artifact: projectionWithServerState({
+                            declaration,
+                            state: this.state,
+                            previewBasePath: options.previewBasePath,
+                        }),
+                    },
+                };
+            }
+            this.stopCurrentProcess();
+        }
+        this.startProcess(options.workspaceRoot, declaration);
+        return {
+            disposition: { kind: "started" },
+            result: {
+                artifact: projectionWithServerState({
+                    declaration,
+                    state: this.state,
+                    previewBasePath: options.previewBasePath,
+                }),
+            },
+        };
+    }
+    heartbeat(options) {
+        const declaration = readArtifactDeclaration({
+            workspaceRoot: options.workspaceRoot,
+            previewBasePath: options.previewBasePath,
+            now: this.now,
+        });
+        this.stopStaleRuntime(declaration);
+        if (declaration.status === "not_declared") {
+            return {
+                disposition: { kind: "not_declared" },
+                result: { artifact: declaration.projection },
+            };
+        }
+        if (declaration.status === "invalid") {
+            return {
+                disposition: declarationInvalidDisposition(declaration).heartbeat,
+                result: { artifact: declaration.projection },
+            };
+        }
+        if (!isServerDeclaration(declaration) || this.state?.key !== serverDeclarationKey(declaration)) {
+            return {
+                disposition: { kind: "not_running" },
+                result: {
+                    artifact: isServerDeclaration(declaration)
+                        ? projectionWithServerState({
+                            declaration,
+                            state: this.state,
+                            previewBasePath: options.previewBasePath,
+                        })
+                        : declaration.projection,
+                },
+            };
+        }
+        if (this.state.status !== "starting" && this.state.status !== "ready") {
+            return {
+                disposition: { kind: "not_running" },
+                result: {
+                    artifact: projectionWithServerState({
+                        declaration,
+                        state: this.state,
+                        previewBasePath: options.previewBasePath,
+                    }),
+                },
+            };
+        }
+        this.recordHeartbeat(this.state);
+        return {
+            disposition: { kind: "recorded" },
+            result: {
+                artifact: projectionWithServerState({
+                    declaration,
+                    state: this.state,
+                    previewBasePath: options.previewBasePath,
+                }),
+            },
+        };
+    }
+    stop(options) {
+        const declaration = readArtifactDeclaration({
+            workspaceRoot: options.workspaceRoot,
+            previewBasePath: options.previewBasePath,
+            now: this.now,
+        });
+        if (declaration.status === "not_declared") {
+            this.stopCurrentProcess();
+            return {
+                disposition: { kind: "not_declared" },
+                result: { artifact: declaration.projection },
+            };
+        }
+        if (declaration.status === "invalid") {
+            this.stopCurrentProcess();
+            return {
+                disposition: declarationInvalidDisposition(declaration).stop,
+                result: { artifact: declaration.projection },
+            };
+        }
+        if (!isServerDeclaration(declaration) || this.state?.key !== serverDeclarationKey(declaration)) {
+            return {
+                disposition: { kind: "not_running" },
+                result: { artifact: declaration.projection },
+            };
+        }
+        const wasRunning = this.state.status === "starting" || this.state.status === "ready";
+        this.stopCurrentProcess();
+        return {
+            disposition: wasRunning ? { kind: "stopped" } : { kind: "not_running" },
+            result: {
+                artifact: projectionWithServerState({
+                    declaration,
+                    state: this.state,
+                    previewBasePath: options.previewBasePath,
+                }),
+            },
+        };
+    }
+    async fetchServerPreview(options) {
+        const declaration = readArtifactDeclaration({
+            workspaceRoot: options.workspaceRoot,
+            now: this.now,
+        });
+        this.stopStaleRuntime(declaration);
+        if (!isServerDeclaration(declaration) || this.state?.key !== serverDeclarationKey(declaration)) {
+            throw new WorkspaceOpsError("not_found", "Artifact preview is not running");
+        }
+        if (this.state.status !== "ready") {
+            throw new WorkspaceOpsError("validation_failed", "Artifact preview is not ready");
+        }
+        const requestPath = normalizePreviewRequestPath(options.path);
+        const localUrl = new URL(`http://127.0.0.1:${this.state.port}${requestPath}`);
+        const query = options.query?.replace(/^\?/u, "");
+        if (query !== undefined && query.length > 0) {
+            localUrl.search = query;
+            localUrl.searchParams.delete("v");
+        }
+        const controller = new AbortController();
+        const timeout = this.setTimeoutFn(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const response = await this.fetchImpl(localUrl, {
+                method: "GET",
+                headers: {
+                    ...(options.headers?.accept === undefined ? {} : { accept: options.headers.accept }),
+                    ...(options.headers?.["accept-language"] === undefined
+                        ? {}
+                        : { "accept-language": options.headers["accept-language"] }),
+                },
+                redirect: "manual",
+                signal: controller.signal,
+            });
+            const headers = filteredResponseHeaders(response.headers);
+            const content = rewriteArtifactPreviewResourceUrls({
+                mediaType: headers["content-type"],
+                resourcePath: requestPath,
+                content: Buffer.from(await response.arrayBuffer()),
+            });
+            return {
+                status_code: response.status,
+                headers,
+                content,
+            };
+        }
+        finally {
+            this.clearTimeoutFn(timeout);
+        }
+    }
+    sweepIdle() {
+        if (this.state === undefined || this.state.status === "stopped") {
+            return;
+        }
+        if (this.clockMs() - this.state.lastHeartbeatAtMs < this.idleStopTtlMs) {
+            this.scheduleIdleSweep(this.state);
+            return;
+        }
+        this.stopCurrentProcess();
+    }
+    stopAll() {
+        this.stopCurrentProcess();
+    }
+    startProcess(workspaceRoot, declaration) {
+        const port = this.allocatePort();
+        const cwd = resolve(workspaceRoot, declaration.runtime.cwd_path);
+        const plan = {
+            command: "npm",
+            args: ["run", "artifact:preview"],
+            cwd,
+            env: createArtifactPreviewEnv({
+                sourceEnv: this.baseEnv,
+                port,
+            }),
+            port,
+        };
+        const child = this.spawnProcess(plan);
+        const state = {
+            key: serverDeclarationKey(declaration),
+            manifestBlobOid: declaration.manifest_blob_oid,
+            readyPath: declaration.runtime.ready_path,
+            port,
+            status: "starting",
+            child,
+            instanceId: this.nextInstanceId(),
+            lastHeartbeatAtMs: this.clockMs(),
+            errorMessage: undefined,
+            diagnostics: "",
+            idleTimer: undefined,
+        };
+        this.state = state;
+        this.scheduleIdleSweep(state);
+        this.attachProcessListeners(state, child);
+        this.onStatusChange();
+        void this.waitUntilReady(state);
+    }
+    attachProcessListeners(state, child) {
+        child.stdout.on("data", (chunk) => {
+            state.diagnostics = appendDiagnostic(state.diagnostics, chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            state.diagnostics = appendDiagnostic(state.diagnostics, chunk);
+        });
+        child.on("error", (error) => {
+            this.failState(state, redactAndTruncateText(error.message, 220));
+        });
+        child.on("close", (code, signal) => {
+            if (this.state !== state || state.status === "stopped") {
+                return;
+            }
+            const reason = code === null ? `signal ${signal ?? "unknown"}` : `exit code ${code}`;
+            this.failState(state, `Preview process exited (${reason})`);
+        });
+    }
+    async waitUntilReady(state) {
+        const deadline = this.clockMs() + this.readyTimeoutMs;
+        const readyUrl = new URL(`http://127.0.0.1:${state.port}${state.readyPath}`);
+        while (this.state === state && state.status === "starting" && this.clockMs() < deadline) {
+            try {
+                const controller = new AbortController();
+                const timeout = this.setTimeoutFn(() => controller.abort(), this.readyProbeIntervalMs);
+                try {
+                    const response = await this.fetchImpl(readyUrl, {
+                        method: "GET",
+                        signal: controller.signal,
+                    });
+                    if (response.status >= 200 && response.status < 500) {
+                        state.status = "ready";
+                        state.errorMessage = undefined;
+                        this.onStatusChange();
+                        return;
+                    }
+                }
+                finally {
+                    this.clearTimeoutFn(timeout);
+                }
+            }
+            catch {
+                // Keep probing until timeout or process exit.
+            }
+            await new Promise((resolveDelay) => {
+                this.setTimeoutFn(resolveDelay, this.readyProbeIntervalMs);
+            });
+        }
+        if (this.state === state && state.status === "starting") {
+            this.failState(state, "Preview did not become ready in time");
+        }
+    }
+    recordHeartbeat(state) {
+        state.lastHeartbeatAtMs = this.clockMs();
+        this.scheduleIdleSweep(state);
+    }
+    scheduleIdleSweep(state) {
+        if (state.idleTimer !== undefined) {
+            this.clearTimeoutFn(state.idleTimer);
+        }
+        state.idleTimer = this.setTimeoutFn(() => this.sweepIdle(), this.idleStopTtlMs);
+    }
+    stopStaleRuntime(declaration) {
+        if (this.state === undefined) {
+            return;
+        }
+        if (!isServerDeclaration(declaration) || this.state.key !== serverDeclarationKey(declaration)) {
+            this.stopCurrentProcess();
+            this.state = undefined;
+        }
+    }
+    stopCurrentProcess() {
+        const state = this.state;
+        if (state === undefined) {
+            return;
+        }
+        if (state.idleTimer !== undefined) {
+            this.clearTimeoutFn(state.idleTimer);
+            state.idleTimer = undefined;
+        }
+        if (state.child !== undefined &&
+            state.child.exitCode === null &&
+            state.child.signalCode === null) {
+            state.child.kill("SIGTERM");
+        }
+        state.child = undefined;
+        state.status = "stopped";
+        state.errorMessage = undefined;
+        this.onStatusChange();
+    }
+    failState(state, message) {
+        if (this.state !== state || state.status === "stopped") {
+            return;
+        }
+        state.status = "failed";
+        state.errorMessage = message;
+        if (state.child !== undefined &&
+            state.child.exitCode === null &&
+            state.child.signalCode === null) {
+            state.child.kill("SIGTERM");
+        }
+        state.child = undefined;
+        if (state.idleTimer !== undefined) {
+            this.clearTimeoutFn(state.idleTimer);
+            state.idleTimer = undefined;
+        }
+        this.onStatusChange();
+    }
+    nextInstanceId() {
+        this.nextInstanceSequence += 1;
+        return `artifact_preview_${this.nextInstanceSequence}`;
+    }
+}
+export const ARTIFACT_PREVIEW_DEFAULT_BASE_PATH = ARTIFACT_PREVIEW_BASE_PATH;
+//# sourceMappingURL=preview-runtime.js.map

package/dist/artifacts/static-preview.d.ts

@@ -0,0 +1,17 @@
+export declare const ARTIFACT_PREVIEW_CSP: string;
+export type ArtifactStaticPreviewFile = {
+    media_type: string;
+    content: Buffer;
+};
+export type ReadArtifactStaticPreviewOptions = {
+    workspaceRoot: string;
+    path: string | undefined;
+    now?: () => Date;
+};
+export declare function rewriteArtifactPreviewResourceUrls(options: {
+    mediaType: string | undefined;
+    content: Buffer;
+    resourcePath?: string;
+}): Buffer;
+export declare function readArtifactStaticPreview(options: ReadArtifactStaticPreviewOptions): ArtifactStaticPreviewFile;
+//# sourceMappingURL=static-preview.d.ts.map