@xfey/tutti 0.1.42 → 0.1.44

package/dist/artifacts/manifest-contract.js

@@ -0,0 +1,214 @@
+import { posix } from "node:path";
+import { Value } from "@sinclair/typebox/value";
+import { ArtifactManifestSchema } from "@tutti/shared/schemas/api";
+import { classifyViewerPath } from "@tutti/shared/utils";
+export const ARTIFACT_MANIFEST_PATH = "tutti.artifact.json";
+export const MAX_ARTIFACT_MANIFEST_BYTES = 64 * 1024;
+const HTML_ENTRY_PATTERN = /\.html?$/iu;
+const STATIC_ARTIFACT_FIELDS = new Set(["title", "kind", "root", "entry", "network"]);
+const SERVER_ARTIFACT_FIELDS = new Set(["title", "kind", "cwd", "entry", "network"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unexpectedArtifactField(artifact, allowedFields) {
+    return Object.keys(artifact).find((field) => !allowedFields.has(field)) ?? null;
+}
+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.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";
+        }
+        if (artifact.network === undefined) {
+            return "static artifact network is required";
+        }
+        if (typeof artifact.network !== "boolean") {
+            return "static artifact network must be a boolean";
+        }
+        const unexpected = unexpectedArtifactField(artifact, STATIC_ARTIFACT_FIELDS);
+        return unexpected === null ? null : `static artifact field "${unexpected}" is not allowed`;
+    }
+    if (artifact.kind === "server") {
+        if (typeof artifact.cwd !== "string" || artifact.cwd.length === 0) {
+            return "server artifact cwd is required";
+        }
+        if (typeof artifact.entry !== "string" || artifact.entry.length === 0) {
+            return "server artifact entry is required";
+        }
+        if (!artifact.entry.startsWith("/")) {
+            return "server artifact entry must start with /";
+        }
+        if (artifact.network === undefined) {
+            return "server artifact network is required";
+        }
+        if (typeof artifact.network !== "boolean") {
+            return "server artifact network must be a boolean";
+        }
+        const unexpected = unexpectedArtifactField(artifact, SERVER_ARTIFACT_FIELDS);
+        return unexpected === null ? null : `server artifact field "${unexpected}" is not allowed`;
+    }
+    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 decodeUtf8(buffer) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeRepoPath(options) {
+    const classification = classifyViewerPath(options.path);
+    if (classification.kind === "rejected") {
+        return {
+            ok: false,
+            error: { code: "invalid_path", message: `${options.label} is invalid` },
+        };
+    }
+    if (!options.allowRoot && classification.normalized_path === "") {
+        return {
+            ok: false,
+            error: { code: "invalid_path", message: `${options.label} cannot be repo root` },
+        };
+    }
+    if (classification.normalized_path.split("/").some((segment) => segment.startsWith("."))) {
+        return {
+            ok: false,
+            error: { code: "invalid_path", message: `${options.label} cannot use hidden paths` },
+        };
+    }
+    return { ok: true, path: classification.normalized_path };
+}
+function validateServerEntry(entry) {
+    if (entry.includes("\\") || entry.includes("#") || entry.startsWith("//")) {
+        return { code: "invalid_entry", message: "Server artifact entry is not a safe HTTP path" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(entry, "http://artifact.invalid");
+    }
+    catch {
+        return { code: "invalid_entry", message: "Server artifact entry is not a safe HTTP path" };
+    }
+    if (parsed.origin !== "http://artifact.invalid" || !entry.startsWith("/")) {
+        return { code: "invalid_entry", message: "Server artifact entry is not a safe HTTP path" };
+    }
+    return null;
+}
+export function parseArtifactManifestContract(buffer) {
+    if (buffer.byteLength > MAX_ARTIFACT_MANIFEST_BYTES) {
+        return { ok: false, error: { code: "too_large", message: "Artifact manifest is too large" } };
+    }
+    const text = decodeUtf8(buffer);
+    if (text === null) {
+        return {
+            ok: false,
+            error: { code: "unsupported_encoding", message: "Artifact manifest must be UTF-8 JSON" },
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : "Artifact manifest is not valid JSON";
+        return { ok: false, error: { code: "invalid_json", message: detail } };
+    }
+    if (!Value.Check(ArtifactManifestSchema, parsed)) {
+        return {
+            ok: false,
+            error: { code: "invalid_schema", message: firstSchemaError(parsed) },
+        };
+    }
+    const manifest = parsed;
+    const artifact = manifest.artifact;
+    if (artifact.kind === "static") {
+        const root = normalizeRepoPath({
+            path: artifact.root,
+            label: "Static artifact root",
+            allowRoot: true,
+        });
+        if (!root.ok) {
+            return root;
+        }
+        const entry = normalizeRepoPath({
+            path: artifact.entry,
+            label: "Static artifact entry",
+            allowRoot: false,
+        });
+        if (!entry.ok) {
+            return entry;
+        }
+        const entryRepoPath = root.path === "" ? entry.path : posix.join(root.path, entry.path);
+        if (!HTML_ENTRY_PATTERN.test(entryRepoPath)) {
+            return {
+                ok: false,
+                error: { code: "invalid_entry", message: "Static artifact entry must be an HTML file" },
+            };
+        }
+        return {
+            ok: true,
+            declaration: {
+                manifest,
+                runtime: {
+                    kind: "static",
+                    root_path: root.path,
+                    entry_path: entry.path,
+                    entry_repo_path: entryRepoPath,
+                },
+            },
+        };
+    }
+    const cwd = normalizeRepoPath({
+        path: artifact.cwd,
+        label: "Server artifact cwd",
+        allowRoot: true,
+    });
+    if (!cwd.ok) {
+        return cwd;
+    }
+    const entryError = validateServerEntry(artifact.entry);
+    if (entryError !== null) {
+        return { ok: false, error: entryError };
+    }
+    return {
+        ok: true,
+        declaration: {
+            manifest,
+            runtime: {
+                kind: "server",
+                cwd_path: cwd.path,
+                entry_path: artifact.entry,
+            },
+        },
+    };
+}
+//# sourceMappingURL=manifest-contract.js.map

package/dist/artifacts/manifest.d.ts

@@ -1,5 +1,6 @@
 import type { ArtifactManifest, ArtifactProjection, GetArtifactsResponse } from "@tutti/shared/schemas/api";
-export declare const ARTIFACT_MANIFEST_PATH: "tutti.artifact.json";
+import { type ValidatedArtifactRuntime } from "./manifest-contract.js";
+export { ARTIFACT_MANIFEST_PATH } from "./manifest-contract.js";
 export declare const ARTIFACT_PREVIEW_BASE_PATH: "/artifacts/preview";
 type ArtifactInvalidProjection = Extract<ArtifactProjection, {
     status: "invalid";
@@ -7,16 +8,7 @@ type ArtifactInvalidProjection = Extract<ArtifactProjection, {
 type ArtifactDeclaredProjection = Extract<ArtifactProjection, {
     status: "declared";
 }>;
-export type DeclaredArtifactRuntime = {
-    kind: "static";
-    root_path: string;
-    entry_path: string;
-    entry_repo_path: string;
-} | {
-    kind: "server";
-    cwd_path: string;
-    ready_path: string;
-};
+export type DeclaredArtifactRuntime = ValidatedArtifactRuntime;
 export type ArtifactDeclaration = {
     status: "not_declared";
     projection: Extract<ArtifactProjection, {
@@ -44,5 +36,4 @@ export declare function buildArtifactPreviewUrl(options: {
 }): string;
 export declare function readArtifactDeclaration(options: ReadArtifactDeclarationOptions): ArtifactDeclaration;
 export declare function readArtifactProjection(options: ReadArtifactDeclarationOptions): GetArtifactsResponse;
-export {};
 //# sourceMappingURL=manifest.d.ts.map

package/dist/artifacts/manifest.js

@@ -1,13 +1,7 @@
-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";
+import { ARTIFACT_MANIFEST_PATH, parseArtifactManifestContract, } from "./manifest-contract.js";
+export { ARTIFACT_MANIFEST_PATH } from "./manifest-contract.js";
 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",
@@ -28,105 +22,6 @@ function truncateMessage(message) {
     }
     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;
@@ -141,27 +36,14 @@ function ensureDirectory(options) {
     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);
+    const entry = lsPath(options.workspaceRoot, options.entryRepoPath);
     if (entry === null) {
-        return {
-            ok: false,
-            declaration: invalidArtifact("not_found", "Static artifact entry does not exist"),
-        };
+        return 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 invalidArtifact("invalid_entry", "Static artifact entry is not a file");
     }
-    return { ok: true, entryRepoPath };
+    return null;
 }
 function encodePreviewPath(path) {
     return path
@@ -184,9 +66,7 @@ function createDeclaredProjection(options) {
             url: buildArtifactPreviewUrl({
                 entryPath: options.runtime.entry_path,
                 manifestBlobOid: options.manifestBlobOid,
-                ...(options.previewBasePath === undefined
-                    ? {}
-                    : { basePath: options.previewBasePath }),
+                ...(options.previewBasePath === undefined ? {} : { basePath: options.previewBasePath }),
             }),
         }
         : { status: "stopped" };
@@ -197,94 +77,40 @@ function createDeclaredProjection(options) {
         artifact: {
             title: artifact.title,
             kind: artifact.kind,
-            network: artifact.network ?? false,
+            network: artifact.network,
         },
         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;
-        }
+function validateCommittedArtifact(options) {
+    const runtime = options.runtime;
+    if (runtime.kind === "static") {
         const rootError = ensureDirectory({
             workspaceRoot: options.workspaceRoot,
-            path: root.path,
+            path: runtime.root_path,
             label: "Static artifact root",
         });
         if (rootError !== null) {
             return rootError;
         }
-        const entryResult = ensureStaticEntry({
+        const entryError = ensureStaticEntry({
             workspaceRoot: options.workspaceRoot,
-            rootPath: root.path,
-            entryPath: entry.path,
+            entryRepoPath: runtime.entry_repo_path,
         });
-        if (!entryResult.ok) {
-            return entryResult.declaration;
+        if (entryError !== null) {
+            return entryError;
         }
-        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;
+        return runtime;
     }
     const cwdError = ensureDirectory({
         workspaceRoot: options.workspaceRoot,
-        path: cwd.path,
+        path: runtime.cwd_path,
         label: "Server artifact cwd",
     });
     if (cwdError !== null) {
         return cwdError;
     }
-    return {
-        kind: "server",
-        cwd_path: cwd.path,
-        ready_path: artifact.ready_path ?? "/",
-    };
+    return runtime;
 }
 export function readArtifactDeclaration(options) {
     readViewerSnapshot(options);
@@ -302,27 +128,29 @@ export function readArtifactDeclaration(options) {
         workspaceRoot: options.workspaceRoot,
         path: ARTIFACT_MANIFEST_PATH,
     });
-    const parsed = parseArtifactManifest(readBlob(options.workspaceRoot, fileEntry.oid, fileEntry.size));
-    if ("status" in parsed) {
-        return parsed;
+    const parsed = parseArtifactManifestContract(readBlob(options.workspaceRoot, fileEntry.oid, fileEntry.size));
+    if (!parsed.ok) {
+        return invalidArtifact(parsed.error.code, parsed.error.message);
     }
-    const runtime = validateArtifactManifest({
+    const runtime = validateCommittedArtifact({
         workspaceRoot: options.workspaceRoot,
-        manifest: parsed,
+        runtime: parsed.declaration.runtime,
     });
     if ("status" in runtime) {
         return runtime;
     }
     return {
         status: "declared",
-        manifest: parsed,
+        manifest: parsed.declaration.manifest,
         manifest_blob_oid: fileEntry.oid,
         runtime,
         projection: createDeclaredProjection({
-            manifest: parsed,
+            manifest: parsed.declaration.manifest,
             manifestBlobOid: fileEntry.oid,
             runtime,
-            ...(options.previewBasePath === undefined ? {} : { previewBasePath: options.previewBasePath }),
+            ...(options.previewBasePath === undefined
+                ? {}
+                : { previewBasePath: options.previewBasePath }),
         }),
     };
 }

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

@@ -1,5 +1,6 @@
-import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { ArtifactProjection, GetArtifactsResponse, HeartbeatArtifactPreviewDisposition, StartArtifactPreviewDisposition, StopArtifactPreviewDisposition } from "@tutti/shared/schemas/api";
+import { type ArtifactPreviewProcessPlan, type ArtifactProcessRuntime } from "./process-boundary.js";
 export type ArtifactPreviewCommandResult = {
     artifact: ArtifactProjection;
 };
@@ -20,42 +21,52 @@ export type ArtifactServerPreviewResponse = {
     headers: Record<string, string>;
     content: Buffer;
 };
-export type ArtifactPreviewProcessPlan = {
-    command: "npm";
-    args: ["run", "artifact:preview"];
-    cwd: string;
-    env: NodeJS.ProcessEnv;
-    port: number;
-};
+export type ArtifactPreviewHttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
 export type ArtifactPreviewManagerOptions = {
     now?: () => Date;
     baseEnv?: NodeJS.ProcessEnv;
     spawnProcess?: (plan: ArtifactPreviewProcessPlan) => ChildProcessWithoutNullStreams;
+    terminateProcess?: (child: ChildProcessWithoutNullStreams) => Promise<void>;
     fetchImpl?: typeof fetch;
-    allocatePort?: () => number;
+    allocatePort?: () => number | Promise<number>;
+    createProcessRuntime?: () => ArtifactProcessRuntime;
+    cleanupProcessRuntime?: (runtime: ArtifactProcessRuntime) => void;
     clockMs?: () => number;
     setTimeoutFn?: typeof setTimeout;
     clearTimeoutFn?: typeof clearTimeout;
     onStatusChange?: () => void;
     readyTimeoutMs?: number;
     readyProbeIntervalMs?: number;
+    readyProbeRequestTimeoutMs?: number;
     requestTimeoutMs?: number;
+    requestBodyLimitBytes?: number;
+    responseBodyLimitBytes?: number;
     idleStopTtlMs?: number;
 };
+export declare const ARTIFACT_PREVIEW_REQUEST_BODY_LIMIT_BYTES: number;
+export declare const ARTIFACT_PREVIEW_RESPONSE_BODY_LIMIT_BYTES: number;
+export declare function isArtifactPreviewHttpMethod(method: string): method is ArtifactPreviewHttpMethod;
 export declare class ArtifactPreviewManager {
     private readonly now;
     private readonly baseEnv;
     private readonly spawnProcess;
+    private readonly terminateProcess;
     private readonly fetchImpl;
     private readonly allocatePort;
+    private readonly createProcessRuntime;
+    private readonly cleanupProcessRuntime;
     private readonly clockMs;
     private readonly setTimeoutFn;
     private readonly clearTimeoutFn;
     private readonly onStatusChange;
     private readonly readyTimeoutMs;
     private readonly readyProbeIntervalMs;
+    private readonly readyProbeRequestTimeoutMs;
     private readonly requestTimeoutMs;
+    private readonly requestBodyLimitBytes;
+    private readonly responseBodyLimitBytes;
     private readonly idleStopTtlMs;
+    private readonly pendingTasks;
     private state;
     private nextInstanceSequence;
     constructor(options?: ArtifactPreviewManagerOptions);
@@ -78,20 +89,28 @@ export declare class ArtifactPreviewManager {
     fetchServerPreview(options: {
         workspaceRoot: string;
         path: string | undefined;
+        method: ArtifactPreviewHttpMethod;
         query?: string;
         headers?: Record<string, string | undefined>;
+        body?: Buffer;
     }): Promise<ArtifactServerPreviewResponse>;
     sweepIdle(): void;
-    stopAll(): void;
+    stopAll(): Promise<void>;
     private startProcess;
+    private launchProcess;
     private attachProcessListeners;
     private waitUntilReady;
+    private probeReadyEntry;
     private recordHeartbeat;
     private scheduleIdleSweep;
     private stopStaleRuntime;
     private stopCurrentProcess;
     private failState;
+    private disposeStateProcess;
+    private cleanupStateRuntime;
+    private trackTask;
     private nextInstanceId;
 }
+export type { ArtifactPreviewProcessPlan } from "./process-boundary.js";
 export declare const ARTIFACT_PREVIEW_DEFAULT_BASE_PATH: "/artifacts/preview";
 //# sourceMappingURL=preview-runtime.d.ts.map