@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/utils/path.js

@@ -0,0 +1,156 @@
+import os from "node:os";
+import { realpathSync } from "node:fs";
+import nodePath from "node:path";
+/**
+ * Expand tilde in path to home directory
+ */
+export function expandTilde(path) {
+    if (path.startsWith("~/")) {
+        const homeDir = process.env.HOME || os.homedir();
+        return path.replace("~", homeDir);
+    }
+    if (path === "~") {
+        return process.env.HOME || os.homedir();
+    }
+    return path;
+}
+/**
+ * Compare two path strings as filesystem-equivalent for cwd filtering.
+ *
+ * This is a string-only comparison: it normalizes separators and dot segments,
+ * ignores trailing separators, strips Windows namespace prefixes, and
+ * case-folds only when comparing as Windows. It does not resolve symlinks or
+ * check whether either path exists.
+ */
+export function areEquivalentPaths(left, right) {
+    const compareAsWindows = shouldCompareAsWindows(left, right);
+    return (normalizePathForComparison(left, compareAsWindows) ===
+        normalizePathForComparison(right, compareAsWindows));
+}
+export function createPathEquivalenceMatcher(target) {
+    const targetLooksWindows = looksLikeDefiniteWindowsPath(target);
+    const compareAsWindows = targetLooksWindows;
+    const normalizedTarget = normalizePathForComparison(target, compareAsWindows);
+    return (candidate) => {
+        const candidateCompareAsWindows = compareAsWindows || looksLikeDefiniteWindowsPath(candidate);
+        const comparableTarget = candidateCompareAsWindows === compareAsWindows
+            ? normalizedTarget
+            : normalizePathForComparison(target, candidateCompareAsWindows);
+        return normalizePathForComparison(candidate, candidateCompareAsWindows) === comparableTarget;
+    };
+}
+export function createRealpathAwarePathMatcher(target) {
+    const targetMatchers = collectPathVariants(target).map((variant) => createPathEquivalenceMatcher(variant));
+    return (candidate) => {
+        const candidateVariants = collectPathVariants(candidate);
+        return candidateVariants.some((variant) => targetMatchers.some((matches) => matches(variant)));
+    };
+}
+export function isPathInsideRoot(root, candidate) {
+    return getRelativePathInsideRoot(root, candidate) !== null;
+}
+export function normalizePathForIdentity(value) {
+    const canonicalPath = resolveRealpathVariants(value)[0] ?? value;
+    return normalizePathForComparison(canonicalPath, looksLikeDefiniteWindowsPath(canonicalPath));
+}
+/**
+ * Returns the candidate's relative suffix when it is inside root.
+ *
+ * The suffix is derived from the same lexical path pair used to prove
+ * containment. Callers that map an existing filesystem path into a new root
+ * must keep those two operations coupled.
+ */
+export function getRealpathAwareRelativePath(root, candidate) {
+    const rootVariants = collectPathVariants(root);
+    const candidateVariants = collectPathVariants(candidate);
+    for (const rootVariant of rootVariants) {
+        for (const candidateVariant of candidateVariants) {
+            const relativePath = getRelativePathInsideRoot(rootVariant, candidateVariant);
+            if (relativePath !== null)
+                return relativePath;
+        }
+    }
+    return null;
+}
+export function isRealpathInsideRoot(root, candidate) {
+    return getRealpathAwareRelativePath(root, candidate) !== null;
+}
+function getRelativePathInsideRoot(root, candidate) {
+    const compareAsWindows = shouldCompareAsWindows(root, candidate);
+    const platformPath = compareAsWindows ? nodePath.win32 : nodePath.posix;
+    const normalizedRoot = normalizePathForComparison(root, compareAsWindows);
+    const normalizedCandidate = normalizePathForComparison(candidate, compareAsWindows);
+    const comparableRelative = platformPath.relative(normalizedRoot, normalizedCandidate);
+    if (comparableRelative !== "" &&
+        (comparableRelative.startsWith("..") || platformPath.isAbsolute(comparableRelative))) {
+        return null;
+    }
+    const casePreservingRoot = normalizePathPreservingCase(root, compareAsWindows);
+    const casePreservingCandidate = normalizePathPreservingCase(candidate, compareAsWindows);
+    return platformPath.relative(casePreservingRoot, casePreservingCandidate);
+}
+function collectPathVariants(value) {
+    const variants = new Set([value]);
+    for (const realpath of resolveRealpathVariants(value)) {
+        variants.add(realpath);
+    }
+    return Array.from(variants);
+}
+function resolveRealpathVariants(value) {
+    const variants = [];
+    try {
+        variants.push(realpathSync.native(value));
+    }
+    catch {
+        // Path may not exist, or the platform may reject this link flavor.
+    }
+    try {
+        variants.push(realpathSync(value));
+    }
+    catch {
+        // Keep string-only comparison as the fallback.
+    }
+    return variants;
+}
+function shouldCompareAsWindows(left, right) {
+    return looksLikeDefiniteWindowsPath(left) || looksLikeDefiniteWindowsPath(right);
+}
+function looksLikeDefiniteWindowsPath(value) {
+    return (/^[a-zA-Z]:[\\/]/u.test(value) ||
+        /^[/\\]{2}\?[/\\]/u.test(value) ||
+        /^\\{2}[^/\\]+[/\\][^/\\]+/u.test(value));
+}
+function normalizePathForComparison(value, compareAsWindows) {
+    const normalized = normalizePathPreservingCase(value, compareAsWindows);
+    return compareAsWindows ? normalized.toLowerCase() : normalized;
+}
+function normalizePathPreservingCase(value, compareAsWindows) {
+    const platformPath = compareAsWindows ? nodePath.win32 : nodePath.posix;
+    const comparableValue = compareAsWindows ? stripWindowsNamespacePrefix(value) : value;
+    const platformNormalized = platformPath.normalize(comparableValue);
+    return stripTrailingSeparators(platformNormalized, platformPath.parse(platformNormalized).root, compareAsWindows);
+}
+function stripWindowsNamespacePrefix(value) {
+    const driveMatch = value.match(/^[/\\]{2}\?[/\\]([a-zA-Z]:)[/\\](.*)$/u);
+    const drivePrefix = driveMatch?.[1];
+    if (drivePrefix) {
+        return `${drivePrefix}\\${driveMatch[2] ?? ""}`;
+    }
+    const uncMatch = value.match(/^[/\\]{2}\?[/\\]UNC[/\\]([^/\\]+)[/\\]([^/\\]+)(?:[/\\](.*))?$/iu);
+    const uncServer = uncMatch?.[1];
+    const uncShare = uncMatch?.[2];
+    if (uncServer && uncShare) {
+        const uncRest = uncMatch[3];
+        return `\\\\${uncServer}\\${uncShare}${uncRest !== undefined ? `\\${uncRest}` : ""}`;
+    }
+    return value;
+}
+function stripTrailingSeparators(value, root, compareAsWindows) {
+    const separatorPattern = compareAsWindows ? /[\\/]/u : /\//u;
+    let result = value;
+    while (result.length > root.length && separatorPattern.test(result.at(-1) ?? "")) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+//# sourceMappingURL=path.js.map

package/dist/server/utils/project-custom-icon.d.ts

@@ -0,0 +1,40 @@
+import type { ProjectIconSource } from "@camerontaylor/paseo-protocol/messages";
+import type { PersistedProjectRecord, ProjectRegistry } from "../server/workspace-registry.js";
+import { type ProjectIcon } from "./project-icon.js";
+/**
+ * The only writer of custom project icons. The client owns image acquisition;
+ * this boundary accepts bytes, validates them, and replaces whatever was stored.
+ */
+export declare function setProjectCustomIcon(input: {
+    paseoHome: string;
+    projectId: string;
+    source: ProjectIconSource;
+    projects: ProjectRegistry;
+}): Promise<PersistedProjectRecord>;
+/** Resolves the icon a project renders with, whichever mode it is in. */
+export declare function readProjectIcon(input: {
+    paseoHome: string;
+    project: PersistedProjectRecord;
+}): Promise<ProjectIcon | null>;
+export interface ProjectIconSnapshot {
+    icon: ProjectIcon | null;
+    revision: string;
+}
+/** Keeps the icon bytes served by a session aligned with its advertised revision. */
+export declare class ProjectIconReader {
+    private readonly paseoHome;
+    private readonly snapshots;
+    constructor(paseoHome: string);
+    snapshot(project: PersistedProjectRecord): Promise<ProjectIconSnapshot>;
+    read(project: PersistedProjectRecord): Promise<ProjectIcon | null>;
+}
+/** Reads the effective icon and gives that exact result a stable identity. */
+export declare function readProjectIconSnapshot(input: {
+    paseoHome: string;
+    project: PersistedProjectRecord;
+}): Promise<ProjectIconSnapshot>;
+export declare function removeProjectCustomIcon(input: {
+    paseoHome: string;
+    projectId: string;
+}): Promise<void>;
+//# sourceMappingURL=project-custom-icon.d.ts.map

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

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { writeFileAtomic } from "../server/atomic-file.js";
+import { getImageDimensions, getProjectIcon } from "./project-icon.js";
+const MAX_ICON_BYTES = 512 * 1024;
+const ICON_TOO_LARGE_ERROR = "Icon must be 512 KB or smaller";
+// A save validates, writes bytes, and updates the registry. Two concurrent
+// saves for one project would interleave those steps.
+const inFlightSaves = new Map();
+/**
+ * The only writer of custom project icons. The client owns image acquisition;
+ * this boundary accepts bytes, validates them, and replaces whatever was stored.
+ */
+export async function setProjectCustomIcon(input) {
+    return serialize(input.projectId, async () => {
+        if (!(await input.projects.get(input.projectId)))
+            throw new Error("Project not found");
+        let customIconRevision = null;
+        if (input.source.type === "automatic") {
+            await removeProjectCustomIcon(input);
+        }
+        else {
+            const bytes = Buffer.from(input.source.data, "base64");
+            validateIcon(bytes);
+            await writeFileAtomic(cachePath(input.paseoHome, input.projectId), bytes);
+            customIconRevision = randomUUID();
+        }
+        const updated = await input.projects.update(input.projectId, (current) => ({
+            ...current,
+            customIconRevision,
+            updatedAt: new Date().toISOString(),
+        }));
+        if (!updated) {
+            // The project was removed mid-save, so its own cleanup missed these bytes.
+            await removeProjectCustomIcon(input);
+            throw new Error("Project not found");
+        }
+        return updated;
+    });
+}
+/** Resolves the icon a project renders with, whichever mode it is in. */
+export async function readProjectIcon(input) {
+    return (await readProjectIconSnapshot(input)).icon;
+}
+/** Keeps the icon bytes served by a session aligned with its advertised revision. */
+export class ProjectIconReader {
+    constructor(paseoHome) {
+        this.paseoHome = paseoHome;
+        this.snapshots = new Map();
+    }
+    async snapshot(project) {
+        const snapshot = await readProjectIconSnapshot({ paseoHome: this.paseoHome, project });
+        this.snapshots.set(project.projectId, snapshot);
+        return snapshot;
+    }
+    async read(project) {
+        return (this.snapshots.get(project.projectId) ?? (await this.snapshot(project))).icon;
+    }
+}
+/** Reads the effective icon and gives that exact result a stable identity. */
+export async function readProjectIconSnapshot(input) {
+    if (input.project.customIconRevision) {
+        let icon = null;
+        try {
+            icon = validateIcon(await readFile(cachePath(input.paseoHome, input.project.projectId)));
+        }
+        catch {
+            // A missing/corrupt custom icon is itself a cacheable result until the
+            // registry revision changes.
+        }
+        return {
+            icon,
+            revision: icon
+                ? iconRevision("custom", icon)
+                : `custom:none:${input.project.customIconRevision}`,
+        };
+    }
+    const icon = await getProjectIcon(input.project.rootPath);
+    if (!icon)
+        return { icon: null, revision: "automatic:none:v1" };
+    return { icon, revision: iconRevision("automatic", icon) };
+}
+function iconRevision(source, icon) {
+    const fingerprint = createHash("sha256")
+        .update(icon.mimeType)
+        .update("\0")
+        .update(icon.data)
+        .digest("hex");
+    return `${source}:${fingerprint}`;
+}
+export async function removeProjectCustomIcon(input) {
+    await rm(cachePath(input.paseoHome, input.projectId), { force: true });
+}
+async function serialize(projectId, save) {
+    const previous = inFlightSaves.get(projectId) ?? Promise.resolve();
+    const next = previous.catch(() => undefined).then(save);
+    inFlightSaves.set(projectId, next);
+    try {
+        return await next;
+    }
+    finally {
+        if (inFlightSaves.get(projectId) === next)
+            inFlightSaves.delete(projectId);
+    }
+}
+function cachePath(paseoHome, projectId) {
+    const key = createHash("sha256").update(projectId).digest("hex");
+    return join(paseoHome, "projects", "icons", `${key}.bin`);
+}
+function detectMimeType(buffer) {
+    if (buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return "image/png";
+    }
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff)
+        return "image/jpeg";
+    const header = buffer.toString("ascii", 0, 6);
+    if (header === "GIF87a" || header === "GIF89a")
+        return "image/gif";
+    if (buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WEBP") {
+        return "image/webp";
+    }
+    if (buffer.length >= 22 &&
+        buffer.readUInt16LE(0) === 0 &&
+        buffer.readUInt16LE(2) === 1 &&
+        buffer.readUInt16LE(4) > 0) {
+        return "image/x-icon";
+    }
+    return null;
+}
+function validateIcon(buffer) {
+    if (buffer.length === 0 || buffer.length > MAX_ICON_BYTES) {
+        throw new Error(ICON_TOO_LARGE_ERROR);
+    }
+    const mimeType = detectMimeType(buffer);
+    if (!mimeType)
+        throw new Error("Unsupported or invalid icon file");
+    const size = getImageDimensions(buffer, mimeType);
+    if (!size || size.width <= 0 || size.width !== size.height || size.width > 1024) {
+        throw new Error("Icon must be a square image up to 1024×1024");
+    }
+    return { data: buffer.toString("base64"), mimeType };
+}
+//# sourceMappingURL=project-custom-icon.js.map

package/dist/server/utils/project-icon.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare const ICON_PATTERNS: string[];
+/**
+ * Directories or directory paths to search first (in priority order).
+ */
+export declare const PRIORITY_DIRS: string[];
+/**
+ * Monorepo package directory patterns to scan (e.g., packages/app, apps/web).
+ */
+export declare const MONOREPO_PACKAGE_DIRS: string[];
+/**
+ * Directories to ignore during search.
+ */
+export declare const IGNORED_DIRS: string[];
+export interface ProjectIcon {
+    data: string;
+    mimeType: string;
+}
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+export declare function getImageDimensions(buffer: Buffer, mimeType: string): ImageDimensions | 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 declare function extractIcoPngFrame(buffer: Buffer): Buffer | 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 declare function findProjectIcon(projectDir: string, maxDepth?: number): Promise<string | 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 declare function getProjectIcon(projectDir: string): Promise<ProjectIcon | null>;
+//# sourceMappingURL=project-icon.d.ts.map