@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/utils/project-icon.js

@@ -0,0 +1,445 @@
+import { readdir, readFile, stat } from "fs/promises";
+import { extname, join } from "path";
+/**
+ * Icon file patterns to search for, in priority order.
+ * Patterns starting with '*' are glob patterns (e.g., icon-*.png).
+ *
+ * SVG and PNG outrank ICO across all known names: every client renders them
+ * and they scale better. ICO is the final fallback because native clients
+ * cannot decode containers whose frames use the legacy bitmap format.
+ */
+export const ICON_PATTERNS = [
+    "favicon.svg",
+    "favicon.png",
+    "favicon-*.svg",
+    "favicon-*.png",
+    "favico.svg",
+    "favico.png",
+    "icon.svg",
+    "icon.png",
+    "app-icon.svg",
+    "app-icon.png",
+    "apple-touch-icon.png",
+    "apple-touch-icon-*.png",
+    "icon-*.png",
+    "android-chrome-*.png",
+    "safari-pinned-tab.svg",
+    "mstile-*.png",
+    "logo.svg",
+    "logo.png",
+    "favicon.ico",
+    "favico.ico",
+];
+/**
+ * Directories or directory paths to search first (in priority order).
+ */
+export const PRIORITY_DIRS = ["public", "static", "priv/static", "assets", "images", "img"];
+/**
+ * Monorepo package directory patterns to scan (e.g., packages/app, apps/web).
+ */
+export const MONOREPO_PACKAGE_DIRS = ["packages", "apps"];
+/**
+ * Directories to ignore during search.
+ */
+export const IGNORED_DIRS = [
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".output",
+    "coverage",
+    ".cache",
+    "vendor",
+    "src",
+    "lib",
+    "test",
+    "tests",
+    "__tests__",
+];
+const MAX_ICON_SIZE = 32 * 1024; // 32KB max
+function getPngDimensions(buffer) {
+    // PNG header: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer.length < 24)
+        return null;
+    if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {
+        return null;
+    }
+    // Width and height are at bytes 16-19 and 20-23 (big endian)
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    return { width, height };
+}
+function getJpegDimensions(buffer) {
+    // JPEG starts with FF D8 FF
+    if (buffer.length < 4)
+        return null;
+    if (buffer[0] !== 0xff || buffer[1] !== 0xd8)
+        return null;
+    let offset = 2;
+    while (offset < buffer.length - 8) {
+        if (buffer[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        const marker = buffer[offset + 1];
+        // SOF0-SOF2 markers contain dimensions
+        if (marker >= 0xc0 && marker <= 0xc2) {
+            const height = buffer.readUInt16BE(offset + 5);
+            const width = buffer.readUInt16BE(offset + 7);
+            return { width, height };
+        }
+        // Skip to next marker
+        const length = buffer.readUInt16BE(offset + 2);
+        offset += 2 + length;
+    }
+    return null;
+}
+function getGifDimensions(buffer) {
+    // GIF header: GIF87a or GIF89a
+    if (buffer.length < 10)
+        return null;
+    if (buffer[0] !== 0x47 || buffer[1] !== 0x49 || buffer[2] !== 0x46)
+        return null;
+    // Width and height at bytes 6-7 and 8-9 (little endian)
+    const width = buffer.readUInt16LE(6);
+    const height = buffer.readUInt16LE(8);
+    return { width, height };
+}
+function getWebpDimensions(buffer) {
+    // WEBP: RIFF....WEBP
+    if (buffer.length < 30)
+        return null;
+    if (buffer.toString("ascii", 0, 4) !== "RIFF")
+        return null;
+    if (buffer.toString("ascii", 8, 12) !== "WEBP")
+        return null;
+    const chunkType = buffer.toString("ascii", 12, 16);
+    if (chunkType === "VP8 ") {
+        // Lossy format - dimensions at offset 26-27 and 28-29
+        const width = buffer.readUInt16LE(26) & 0x3fff;
+        const height = buffer.readUInt16LE(28) & 0x3fff;
+        return { width, height };
+    }
+    else if (chunkType === "VP8L") {
+        // Lossless format
+        const bits = buffer.readUInt32LE(21);
+        const width = (bits & 0x3fff) + 1;
+        const height = ((bits >> 14) & 0x3fff) + 1;
+        return { width, height };
+    }
+    return null;
+}
+export function getImageDimensions(buffer, mimeType) {
+    switch (mimeType) {
+        case "image/png":
+            return getPngDimensions(buffer);
+        case "image/jpeg":
+            return getJpegDimensions(buffer);
+        case "image/gif":
+            return getGifDimensions(buffer);
+        case "image/webp":
+            return getWebpDimensions(buffer);
+        case "image/x-icon":
+            // ICO files are typically square, trust them
+            return { width: 1, height: 1 };
+        case "image/svg+xml":
+            // SVG can be any aspect ratio but icons are typically square, trust them
+            return { width: 1, height: 1 };
+        default:
+            return null;
+    }
+}
+function isSquareImage(buffer, mimeType) {
+    const dimensions = getImageDimensions(buffer, mimeType);
+    if (!dimensions)
+        return false;
+    return dimensions.width === dimensions.height;
+}
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * Detect the mime type from the file's magic bytes. Extensions lie: a large
+ * share of real-world favicon.ico files are PNG data renamed, which browsers
+ * render regardless — but native clients key off the reported mime type, so
+ * mislabelling them image/x-icon needlessly drops the icon there.
+ */
+function sniffMimeType(buffer) {
+    if (buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        return "image/png";
+    }
+    if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (buffer.length >= 6 && buffer.toString("ascii", 0, 3) === "GIF") {
+        return "image/gif";
+    }
+    if (buffer.length >= 12 &&
+        buffer.toString("ascii", 0, 4) === "RIFF" &&
+        buffer.toString("ascii", 8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    if (buffer.length >= 6 &&
+        buffer.readUInt16LE(0) === 0 &&
+        buffer.readUInt16LE(2) === 1 &&
+        buffer.readUInt16LE(4) > 0) {
+        return "image/x-icon";
+    }
+    return null;
+}
+/**
+ * ICO is a container; modern favicons usually carry a PNG-encoded frame for the
+ * larger sizes. Native <Image> can't decode ICO but decodes PNG fine, so when a
+ * PNG frame exists, serve the largest one as image/png instead of the container.
+ */
+export function extractIcoPngFrame(buffer) {
+    if (buffer.length < 6 || buffer.readUInt16LE(0) !== 0 || buffer.readUInt16LE(2) !== 1) {
+        return null;
+    }
+    const frameCount = buffer.readUInt16LE(4);
+    let best = null;
+    let bestWidth = -1;
+    for (let index = 0; index < frameCount; index += 1) {
+        const entryOffset = 6 + index * 16;
+        if (entryOffset + 16 > buffer.length) {
+            break;
+        }
+        // Directory entry: width(1) height(1) colors(1) reserved(1) planes(2)
+        // bpp(2) dataSize(4 LE) dataOffset(4 LE). Width byte 0 means 256.
+        const width = buffer[entryOffset] === 0 ? 256 : (buffer[entryOffset] ?? 0);
+        const dataSize = buffer.readUInt32LE(entryOffset + 8);
+        const dataOffset = buffer.readUInt32LE(entryOffset + 12);
+        if (dataOffset + dataSize > buffer.length) {
+            continue;
+        }
+        const frame = buffer.subarray(dataOffset, dataOffset + dataSize);
+        if (frame.length >= 8 && frame.subarray(0, 8).equals(PNG_SIGNATURE) && width > bestWidth) {
+            best = frame;
+            bestWidth = width;
+        }
+    }
+    return best;
+}
+function getMimeType(filename) {
+    const ext = extname(filename).toLowerCase();
+    switch (ext) {
+        case ".ico":
+            return "image/x-icon";
+        case ".png":
+            return "image/png";
+        case ".svg":
+            return "image/svg+xml";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".webp":
+            return "image/webp";
+        default:
+            return "application/octet-stream";
+    }
+}
+function matchesPattern(filename, pattern) {
+    if (pattern.includes("*")) {
+        // Convert glob pattern to regex
+        const regexPattern = pattern.replace(/\./g, "\\.").replace(/\*/g, ".*");
+        return new RegExp(`^${regexPattern}$`).test(filename);
+    }
+    return filename === pattern;
+}
+async function isExistingFile(fullPath) {
+    try {
+        const stats = await stat(fullPath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isExistingDirectory(fullPath) {
+    try {
+        const stats = await stat(fullPath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function findIconInDir(dir, patterns) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    // Collect candidate paths in priority order (pattern, then entry)
+    const candidatePaths = [];
+    for (const pattern of patterns) {
+        for (const entry of entries) {
+            if (matchesPattern(entry, pattern)) {
+                candidatePaths.push(join(dir, entry));
+            }
+        }
+    }
+    const existsResults = await Promise.all(candidatePaths.map((p) => isExistingFile(p)));
+    const foundIndex = existsResults.findIndex((exists) => exists);
+    return foundIndex === -1 ? null : (candidatePaths[foundIndex] ?? null);
+}
+async function searchPriorityDirs(basePath, ignoredDirsSet, remainingDepth) {
+    const priorityPaths = PRIORITY_DIRS.map((priorityDir) => join(basePath, priorityDir));
+    const existenceResults = await Promise.all(priorityPaths.map((priorityPath) => isExistingDirectory(priorityPath)));
+    const searchResults = await Promise.all(priorityPaths.map((priorityPath, index) => existenceResults[index]
+        ? searchDirRecursively(priorityPath, ICON_PATTERNS, ignoredDirsSet, remainingDepth)
+        : Promise.resolve(null)));
+    return searchResults.find((result) => result !== null) ?? null;
+}
+async function searchDirRecursively(dir, patterns, ignoredDirs, maxDepth, currentDepth = 0) {
+    if (currentDepth > maxDepth) {
+        return null;
+    }
+    // First check this directory for icons
+    const found = await findIconInDir(dir, patterns);
+    if (found) {
+        return found;
+    }
+    // Then recurse into subdirectories
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    const candidatePaths = entries
+        .filter((entry) => !ignoredDirs.has(entry))
+        .map((entry) => join(dir, entry));
+    const isDirResults = await Promise.all(candidatePaths.map((fullPath) => isExistingDirectory(fullPath)));
+    const recursionResults = await Promise.all(candidatePaths.map((fullPath, index) => isDirResults[index]
+        ? searchDirRecursively(fullPath, patterns, ignoredDirs, maxDepth, currentDepth + 1)
+        : Promise.resolve(null)));
+    return recursionResults.find((result) => result !== null) ?? null;
+}
+/**
+ * Find a project icon/favicon in the given directory.
+ * Searches priority directories first, then falls back to scanning the root.
+ *
+ * @param projectDir - The root directory of the project to search
+ * @param maxDepth - Maximum depth to search (default: 3)
+ * @returns The absolute path to the found icon, or null if not found
+ */
+export async function findProjectIcon(projectDir, maxDepth = 3) {
+    const ignoredDirsSet = new Set(IGNORED_DIRS);
+    // First search priority directories
+    const priorityResult = await searchPriorityDirs(projectDir, ignoredDirsSet, maxDepth - 1);
+    if (priorityResult) {
+        return priorityResult;
+    }
+    // Then search monorepo package directories (packages/*, apps/*)
+    const monoPaths = MONOREPO_PACKAGE_DIRS.map((monoDir) => join(projectDir, monoDir));
+    const monoEntries = await Promise.all(monoPaths.map(async (monoPath) => {
+        try {
+            return await readdir(monoPath);
+        }
+        catch {
+            return null;
+        }
+    }));
+    const monoResults = await Promise.all(monoPaths.map(async (monoPath, monoIdx) => {
+        const packageEntries = monoEntries[monoIdx];
+        if (!packageEntries)
+            return null;
+        const packagePaths = packageEntries.map((packageName) => join(monoPath, packageName));
+        const isDirResults = await Promise.all(packagePaths.map((packagePath) => isExistingDirectory(packagePath)));
+        const packageResults = await Promise.all(packagePaths.map(async (packagePath, idx) => {
+            if (!isDirResults[idx])
+                return null;
+            const packagePriorityResult = await searchPriorityDirs(packagePath, ignoredDirsSet, maxDepth - 1);
+            if (packagePriorityResult)
+                return packagePriorityResult;
+            return await findIconInDir(packagePath, ICON_PATTERNS);
+        }));
+        return packageResults.find((result) => result !== null) ?? null;
+    }));
+    const monoMatch = monoResults.find((result) => result !== null);
+    if (monoMatch) {
+        return monoMatch;
+    }
+    // Then search root and any other non-priority directories
+    const found = await findDirRecursively(projectDir);
+    if (found) {
+        return found;
+    }
+    return null;
+}
+async function findDirRecursively(dir, maxDepth = 2, currentDepth = 0) {
+    const ignoredDirsSet = new Set(IGNORED_DIRS);
+    const priorityDirsSet = new Set(PRIORITY_DIRS);
+    if (currentDepth > maxDepth) {
+        return null;
+    }
+    // Check root for icons
+    const found = await findIconInDir(dir, ICON_PATTERNS);
+    if (found) {
+        return found;
+    }
+    // Don't recurse further from root - we already searched priority dirs
+    if (currentDepth === 0) {
+        return null;
+    }
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    const candidatePaths = entries
+        .filter((entry) => !ignoredDirsSet.has(entry) && !priorityDirsSet.has(entry))
+        .map((entry) => join(dir, entry));
+    const isDirResults = await Promise.all(candidatePaths.map((fullPath) => isExistingDirectory(fullPath)));
+    const recursionResults = await Promise.all(candidatePaths.map((fullPath, index) => isDirResults[index]
+        ? findDirRecursively(fullPath, maxDepth, currentDepth + 1)
+        : Promise.resolve(null)));
+    return recursionResults.find((result) => result !== null) ?? null;
+}
+/**
+ * Find and read a project icon/favicon, returning it as base64.
+ * Only returns square icons smaller than MAX_ICON_SIZE (32KB).
+ *
+ * @param projectDir - The root directory of the project to search
+ * @returns The icon data with mime type, or null if not found
+ */
+export async function getProjectIcon(projectDir) {
+    const iconPath = await findProjectIcon(projectDir);
+    if (!iconPath) {
+        return null;
+    }
+    try {
+        const stats = await stat(iconPath);
+        if (stats.size > MAX_ICON_SIZE) {
+            return null;
+        }
+        const fileBuffer = await readFile(iconPath);
+        let mimeType = sniffMimeType(fileBuffer) ?? getMimeType(iconPath);
+        let buffer = fileBuffer;
+        if (mimeType === "image/x-icon") {
+            const pngFrame = extractIcoPngFrame(fileBuffer);
+            if (pngFrame) {
+                buffer = pngFrame;
+                mimeType = "image/png";
+            }
+        }
+        // Only return square images
+        if (!isSquareImage(buffer, mimeType)) {
+            return null;
+        }
+        const data = buffer.toString("base64");
+        return { data, mimeType };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=project-icon.js.map

package/dist/server/utils/promise-timeout.d.ts

@@ -0,0 +1,9 @@
+interface TimeoutOptions<T> {
+    promise: Promise<T>;
+    timeoutMs: number;
+    label: string;
+}
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T>;
+export declare function withTimeout<T>(options: TimeoutOptions<T>): Promise<T>;
+export {};
+//# sourceMappingURL=promise-timeout.d.ts.map

package/dist/server/utils/promise-timeout.js

@@ -0,0 +1,25 @@
+export function withTimeout(promiseOrOptions, timeoutMs, message) {
+    const options = typeof timeoutMs === "number"
+        ? { promise: promiseOrOptions, timeoutMs, message }
+        : resolveTimeoutOptions(promiseOrOptions);
+    if (typeof options.timeoutMs !== "number" || !options.message) {
+        return Promise.reject(new Error("Timeout duration and message are required"));
+    }
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new Error(options.message)), options.timeoutMs);
+    });
+    return Promise.race([options.promise, timeoutPromise]).finally(() => {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    });
+}
+function resolveTimeoutOptions(options) {
+    return {
+        promise: options.promise,
+        timeoutMs: options.timeoutMs,
+        message: `Timed out after ${options.timeoutMs}ms (${options.label})`,
+    };
+}
+//# sourceMappingURL=promise-timeout.js.map

package/dist/server/utils/run-git-command.d.ts

@@ -0,0 +1,59 @@
+import type { Logger } from "pino";
+import type { ProcessEnvRecord } from "../server/paseo-env.js";
+import { type GitCommandRuntimeMetricsSnapshot } from "./git-command-runtime-metrics.js";
+import { type GitProcessPriority, type GitProcessPolicy } from "./git-process-scheduler.js";
+export declare function runWithGitCommandPriority<T>(priority: GitProcessPriority, operation: () => T): T;
+export declare function configureGitProcessPolicy(policy: GitProcessPolicy): void;
+export interface GitCommandOptions {
+    cwd: string;
+    env?: ProcessEnvRecord;
+    envOverlay?: ProcessEnvRecord;
+    logger?: Pick<Logger, "trace">;
+    timeout?: number;
+    maxOutputBytes?: number;
+    acceptExitCodes?: number[];
+}
+export interface GitCommandResult {
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+}
+export type RunGitCommand = (args: string[], options: GitCommandOptions) => Promise<GitCommandResult>;
+export declare function createRunGitCommand(provenance: string): RunGitCommand;
+export interface GitCommandMetric {
+    args: string[];
+    cwd: string;
+    startedAtMs: number;
+    durationMs: number;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    success: boolean;
+}
+export interface GitCommandMetricsSnapshot {
+    commands: GitCommandMetric[];
+    submissions: GitCommandSubmissionMetric[];
+    submitted: number;
+    started: number;
+    completed: number;
+    active: number;
+    pending: number;
+    total: number;
+    failed: number;
+    maxConcurrent: number;
+}
+export interface GitCommandSubmissionMetric {
+    args: string[];
+    cwd: string;
+}
+export declare function startGitCommandMetrics(): void;
+export declare function stopGitCommandMetrics(): GitCommandMetricsSnapshot;
+export declare function getGitCommandMetrics(): GitCommandMetricsSnapshot;
+export declare function waitForGitCommandMetricsIdle(options: {
+    quietMs: number;
+    timeoutMs: number;
+}): Promise<void>;
+export declare function snapshotGitCommandRuntimeMetrics(): GitCommandRuntimeMetricsSnapshot;
+export declare const runGitCommand: RunGitCommand;
+//# sourceMappingURL=run-git-command.d.ts.map