@xfey/tutti 0.1.0

package/dist/artifacts/manifest.js

@@ -0,0 +1,334 @@
+import { posix } from "node:path";
+import { Value } from "@sinclair/typebox/value";
+import { ArtifactManifestSchema } from "@tutti/shared/schemas/api";
+import { WorkspaceOpsError } from "../workspace-ops/errors.js";
+import { entryKind, lsPath, readBlob, readViewerSnapshot, requireFileEntry, } from "../workspace-ops/viewer-git.js";
+import { requireNormalizedViewerPath } from "../workspace-ops/viewer-paths.js";
+export const ARTIFACT_MANIFEST_PATH = "tutti.artifact.json";
+export const ARTIFACT_PREVIEW_BASE_PATH = "/artifacts/preview";
+const MAX_ARTIFACT_MANIFEST_BYTES = 64 * 1024;
+const HTML_ENTRY_PATTERN = /\.html?$/iu;
+function invalidArtifact(code, message) {
+    return {
+        status: "invalid",
+        projection: {
+            status: "invalid",
+            manifest_path: ARTIFACT_MANIFEST_PATH,
+            error: {
+                code,
+                message: truncateMessage(message),
+            },
+        },
+    };
+}
+function truncateMessage(message) {
+    const normalized = message.replace(/\s+/gu, " ").trim();
+    if (normalized.length <= 220) {
+        return normalized;
+    }
+    return `${normalized.slice(0, 217)}...`;
+}
+function decodeUtf8(buffer) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    }
+    catch {
+        return null;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function artifactSchemaHint(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const artifact = value.artifact;
+    if (!isRecord(artifact)) {
+        return null;
+    }
+    const title = artifact.title;
+    if (typeof title !== "string" || title.trim().length === 0) {
+        return "artifact.title is required";
+    }
+    if (title.length > 120) {
+        return "artifact.title must be 120 characters or less";
+    }
+    if (artifact.network !== undefined && typeof artifact.network !== "boolean") {
+        return "artifact.network must be a boolean";
+    }
+    const kind = artifact.kind;
+    if (kind === "static") {
+        if (typeof artifact.root !== "string" || artifact.root.length === 0) {
+            return "static artifact root is required";
+        }
+        if (typeof artifact.entry !== "string" || artifact.entry.length === 0) {
+            return "static artifact entry is required";
+        }
+        return null;
+    }
+    if (kind === "server") {
+        if (typeof artifact.cwd !== "string" || artifact.cwd.length === 0) {
+            return "server artifact cwd is required";
+        }
+        if (artifact.script !== "artifact:preview") {
+            return 'server artifact script must be "artifact:preview"';
+        }
+        if (artifact.ready_path !== undefined &&
+            (typeof artifact.ready_path !== "string" ||
+                artifact.ready_path.length === 0 ||
+                artifact.ready_path.length > 256 ||
+                !artifact.ready_path.startsWith("/"))) {
+            return "server artifact ready_path must start with /";
+        }
+        return null;
+    }
+    return 'artifact.kind must be "static" or "server"';
+}
+function firstSchemaError(value) {
+    const hint = artifactSchemaHint(value);
+    if (hint !== null) {
+        return hint;
+    }
+    const first = [...Value.Errors(ArtifactManifestSchema, value)][0];
+    if (first === undefined) {
+        return "Artifact manifest does not match schema";
+    }
+    const path = first.path.length > 0 ? `${first.path}: ` : "";
+    return `${path}${first.message}`;
+}
+function normalizeArtifactPath(options) {
+    try {
+        const normalized = requireNormalizedViewerPath(options.path);
+        if (!options.allowRoot && normalized === "") {
+            return {
+                ok: false,
+                declaration: invalidArtifact("invalid_path", `${options.label} cannot be repo root`),
+            };
+        }
+        if (hasHiddenSegment(normalized)) {
+            return {
+                ok: false,
+                declaration: invalidArtifact("invalid_path", `${options.label} cannot use hidden paths`),
+            };
+        }
+        return { ok: true, path: normalized };
+    }
+    catch (error) {
+        if (error instanceof WorkspaceOpsError) {
+            return {
+                ok: false,
+                declaration: invalidArtifact("invalid_path", `${options.label} is invalid`),
+            };
+        }
+        throw error;
+    }
+}
+function hasHiddenSegment(path) {
+    return path.split("/").some((segment) => segment.startsWith("."));
+}
+function ensureDirectory(options) {
+    if (options.path === "") {
+        return null;
+    }
+    const entry = lsPath(options.workspaceRoot, options.path);
+    if (entry === null) {
+        return invalidArtifact("not_found", `${options.label} does not exist`);
+    }
+    if (entryKind(entry) !== "directory") {
+        return invalidArtifact("invalid_path", `${options.label} is not a directory`);
+    }
+    return null;
+}
+function ensureStaticEntry(options) {
+    const entryRepoPath = options.rootPath === "" ? options.entryPath : posix.join(options.rootPath, options.entryPath);
+    if (entryRepoPath === "" || !HTML_ENTRY_PATTERN.test(entryRepoPath)) {
+        return {
+            ok: false,
+            declaration: invalidArtifact("invalid_entry", "Static artifact entry must be an HTML file"),
+        };
+    }
+    const entry = lsPath(options.workspaceRoot, entryRepoPath);
+    if (entry === null) {
+        return {
+            ok: false,
+            declaration: invalidArtifact("not_found", "Static artifact entry does not exist"),
+        };
+    }
+    if (entryKind(entry) !== "file") {
+        return {
+            ok: false,
+            declaration: invalidArtifact("invalid_entry", "Static artifact entry is not a file"),
+        };
+    }
+    return { ok: true, entryRepoPath };
+}
+function encodePreviewPath(path) {
+    return path
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+export function buildArtifactPreviewUrl(options) {
+    const basePath = (options.basePath ?? ARTIFACT_PREVIEW_BASE_PATH).replace(/\/+$/u, "");
+    const encodedEntryPath = encodePreviewPath(options.entryPath);
+    const path = encodedEntryPath.length === 0 ? basePath : `${basePath}/${encodedEntryPath}`;
+    return `${path}?v=${encodeURIComponent(options.manifestBlobOid)}`;
+}
+function createDeclaredProjection(options) {
+    const artifact = options.manifest.artifact;
+    const preview = artifact.kind === "static" && options.runtime.kind === "static"
+        ? {
+            status: "ready",
+            url: buildArtifactPreviewUrl({
+                entryPath: options.runtime.entry_path,
+                manifestBlobOid: options.manifestBlobOid,
+                ...(options.previewBasePath === undefined
+                    ? {}
+                    : { basePath: options.previewBasePath }),
+            }),
+        }
+        : { status: "stopped" };
+    return {
+        status: "declared",
+        manifest_path: ARTIFACT_MANIFEST_PATH,
+        manifest_blob_oid: options.manifestBlobOid,
+        artifact: {
+            title: artifact.title,
+            kind: artifact.kind,
+            network: artifact.network ?? false,
+        },
+        preview,
+    };
+}
+function parseArtifactManifest(buffer) {
+    if (buffer.byteLength > MAX_ARTIFACT_MANIFEST_BYTES) {
+        return invalidArtifact("too_large", "Artifact manifest is too large");
+    }
+    const text = decodeUtf8(buffer);
+    if (text === null) {
+        return invalidArtifact("unsupported_encoding", "Artifact manifest must be UTF-8 JSON");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return invalidArtifact("invalid_json", "Artifact manifest is not valid JSON");
+    }
+    if (!Value.Check(ArtifactManifestSchema, parsed)) {
+        return invalidArtifact("invalid_schema", firstSchemaError(parsed));
+    }
+    return parsed;
+}
+function validateArtifactManifest(options) {
+    const artifact = options.manifest.artifact;
+    if (artifact.kind === "static") {
+        const root = normalizeArtifactPath({
+            path: artifact.root,
+            label: "Static artifact root",
+            allowRoot: true,
+        });
+        if (!root.ok) {
+            return root.declaration;
+        }
+        const entry = normalizeArtifactPath({
+            path: artifact.entry,
+            label: "Static artifact entry",
+            allowRoot: false,
+        });
+        if (!entry.ok) {
+            return entry.declaration;
+        }
+        const rootError = ensureDirectory({
+            workspaceRoot: options.workspaceRoot,
+            path: root.path,
+            label: "Static artifact root",
+        });
+        if (rootError !== null) {
+            return rootError;
+        }
+        const entryResult = ensureStaticEntry({
+            workspaceRoot: options.workspaceRoot,
+            rootPath: root.path,
+            entryPath: entry.path,
+        });
+        if (!entryResult.ok) {
+            return entryResult.declaration;
+        }
+        return {
+            kind: "static",
+            root_path: root.path,
+            entry_path: entry.path,
+            entry_repo_path: entryResult.entryRepoPath,
+        };
+    }
+    const cwd = normalizeArtifactPath({
+        path: artifact.cwd,
+        label: "Server artifact cwd",
+        allowRoot: true,
+    });
+    if (!cwd.ok) {
+        return cwd.declaration;
+    }
+    const cwdError = ensureDirectory({
+        workspaceRoot: options.workspaceRoot,
+        path: cwd.path,
+        label: "Server artifact cwd",
+    });
+    if (cwdError !== null) {
+        return cwdError;
+    }
+    return {
+        kind: "server",
+        cwd_path: cwd.path,
+        ready_path: artifact.ready_path ?? "/",
+    };
+}
+export function readArtifactDeclaration(options) {
+    readViewerSnapshot(options);
+    const manifestEntry = lsPath(options.workspaceRoot, ARTIFACT_MANIFEST_PATH);
+    if (manifestEntry === null) {
+        return {
+            status: "not_declared",
+            projection: { status: "not_declared" },
+        };
+    }
+    if (entryKind(manifestEntry) !== "file") {
+        return invalidArtifact("invalid_manifest", "Artifact manifest path is not a file");
+    }
+    const fileEntry = requireFileEntry({
+        workspaceRoot: options.workspaceRoot,
+        path: ARTIFACT_MANIFEST_PATH,
+    });
+    const parsed = parseArtifactManifest(readBlob(options.workspaceRoot, fileEntry.oid, fileEntry.size));
+    if ("status" in parsed) {
+        return parsed;
+    }
+    const runtime = validateArtifactManifest({
+        workspaceRoot: options.workspaceRoot,
+        manifest: parsed,
+    });
+    if ("status" in runtime) {
+        return runtime;
+    }
+    return {
+        status: "declared",
+        manifest: parsed,
+        manifest_blob_oid: fileEntry.oid,
+        runtime,
+        projection: createDeclaredProjection({
+            manifest: parsed,
+            manifestBlobOid: fileEntry.oid,
+            runtime,
+            ...(options.previewBasePath === undefined ? {} : { previewBasePath: options.previewBasePath }),
+        }),
+    };
+}
+export function readArtifactProjection(options) {
+    return {
+        artifact: readArtifactDeclaration(options).projection,
+    };
+}
+//# sourceMappingURL=manifest.js.map

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

@@ -0,0 +1,97 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ArtifactProjection, GetArtifactsResponse, HeartbeatArtifactPreviewDisposition, StartArtifactPreviewDisposition, StopArtifactPreviewDisposition } from "@tutti/shared/schemas/api";
+export type ArtifactPreviewCommandResult = {
+    artifact: ArtifactProjection;
+};
+export type ArtifactPreviewStartResult = {
+    disposition: StartArtifactPreviewDisposition;
+    result: ArtifactPreviewCommandResult;
+};
+export type ArtifactPreviewHeartbeatResult = {
+    disposition: HeartbeatArtifactPreviewDisposition;
+    result: ArtifactPreviewCommandResult;
+};
+export type ArtifactPreviewStopResult = {
+    disposition: StopArtifactPreviewDisposition;
+    result: ArtifactPreviewCommandResult;
+};
+export type ArtifactServerPreviewResponse = {
+    status_code: number;
+    headers: Record<string, string>;
+    content: Buffer;
+};
+export type ArtifactPreviewProcessPlan = {
+    command: "npm";
+    args: ["run", "artifact:preview"];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    port: number;
+};
+export type ArtifactPreviewManagerOptions = {
+    now?: () => Date;
+    baseEnv?: NodeJS.ProcessEnv;
+    spawnProcess?: (plan: ArtifactPreviewProcessPlan) => ChildProcessWithoutNullStreams;
+    fetchImpl?: typeof fetch;
+    allocatePort?: () => number;
+    clockMs?: () => number;
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+    onStatusChange?: () => void;
+    readyTimeoutMs?: number;
+    readyProbeIntervalMs?: number;
+    requestTimeoutMs?: number;
+    idleStopTtlMs?: number;
+};
+export declare class ArtifactPreviewManager {
+    private readonly now;
+    private readonly baseEnv;
+    private readonly spawnProcess;
+    private readonly fetchImpl;
+    private readonly allocatePort;
+    private readonly clockMs;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly onStatusChange;
+    private readonly readyTimeoutMs;
+    private readonly readyProbeIntervalMs;
+    private readonly requestTimeoutMs;
+    private readonly idleStopTtlMs;
+    private state;
+    private nextInstanceSequence;
+    constructor(options?: ArtifactPreviewManagerOptions);
+    readProjection(options: {
+        workspaceRoot: string;
+        previewBasePath?: string;
+    }): GetArtifactsResponse;
+    start(options: {
+        workspaceRoot: string;
+        previewBasePath?: string;
+    }): ArtifactPreviewStartResult;
+    heartbeat(options: {
+        workspaceRoot: string;
+        previewBasePath?: string;
+    }): ArtifactPreviewHeartbeatResult;
+    stop(options: {
+        workspaceRoot: string;
+        previewBasePath?: string;
+    }): ArtifactPreviewStopResult;
+    fetchServerPreview(options: {
+        workspaceRoot: string;
+        path: string | undefined;
+        query?: string;
+        headers?: Record<string, string | undefined>;
+    }): Promise<ArtifactServerPreviewResponse>;
+    sweepIdle(): void;
+    stopAll(): void;
+    private startProcess;
+    private attachProcessListeners;
+    private waitUntilReady;
+    private recordHeartbeat;
+    private scheduleIdleSweep;
+    private stopStaleRuntime;
+    private stopCurrentProcess;
+    private failState;
+    private nextInstanceId;
+}
+export declare const ARTIFACT_PREVIEW_DEFAULT_BASE_PATH: "/artifacts/preview";
+//# sourceMappingURL=preview-runtime.d.ts.map