parasor 0.1.0

package/server/fs/file-uploads.js

@@ -0,0 +1,214 @@
+import { open, realpath, stat } from "node:fs/promises";
+import { extname, isAbsolute, resolve, sep } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+export class InvalidUploadFilenameError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message ?? `invalid filename: ${reason}`);
+        this.reason = reason;
+        this.name = "InvalidUploadFilenameError";
+    }
+}
+export class InvalidUploadTargetError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message ?? `invalid target: ${reason}`);
+        this.reason = reason;
+        this.name = "InvalidUploadTargetError";
+    }
+}
+export class UploadConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`conflict: ${conflicts.join(", ")}`);
+        this.conflicts = [...conflicts];
+        this.name = "UploadConflictError";
+    }
+}
+/**
+ * Same character/length policy as `fs/drops.ts#sanitizeFilename`. The
+ * difference: drops always live under `{root}/.parasor/drops/`, whereas
+ * uploads target an arbitrary subdir. Both protect against `..` segments
+ * and control characters at the filename layer; the realpath fence below
+ * protects the directory layer.
+ */
+export function sanitizeUploadFilename(input) {
+    const nfc = input.normalize("NFC");
+    if (nfc === "" || nfc === "." || nfc === "..") {
+        throw new InvalidUploadFilenameError("path-traversal");
+    }
+    if (/(^|[\\/])\.\.([\\/]|$)/.test(nfc)) {
+        throw new InvalidUploadFilenameError("path-traversal");
+    }
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: upload filenames intentionally rewrite C0/DEL bytes.
+    const replaced = nfc.replace(/[\\/\x00-\x1f\x7f 　]/g, "_");
+    if (replaced === "." || replaced === "..") {
+        throw new InvalidUploadFilenameError("path-traversal");
+    }
+    if (replaced.length <= 255)
+        return replaced;
+    const ext = extname(replaced);
+    const base = replaced.slice(0, 255 - ext.length);
+    return base + ext;
+}
+function splitBasenameExt(name) {
+    const ext = extname(name);
+    return { base: ext ? name.slice(0, -ext.length) : name, ext };
+}
+const MAX_SUFFIX_ATTEMPTS = 1000;
+/**
+ * Resolve `relative` against `projectRoot` and prove the result is an
+ * existing directory inside the project. Returns the canonicalized
+ * (realpath-ed) absolute path; the caller writes into it.
+ *
+ * `relative` is the value submitted by the client via the `path` query
+ * parameter. An empty string (or `.`) means "the project root itself".
+ */
+export async function resolveTargetDir(projectRoot, relative) {
+    if (isAbsolute(relative)) {
+        throw new InvalidUploadTargetError("path-traversal");
+    }
+    const candidate = resolve(projectRoot, relative);
+    // Lexical pre-check: a `..` segment can escape even before the directory
+    // exists. Surface that as `path-traversal` instead of `missing`, so the
+    // client can distinguish "you tried to write outside the project" from
+    // "the requested folder was deleted under you".
+    if (candidate !== projectRoot && !candidate.startsWith(projectRoot + sep)) {
+        throw new InvalidUploadTargetError("path-traversal");
+    }
+    let realRoot;
+    let realCandidate;
+    try {
+        realRoot = await realpath(projectRoot);
+    }
+    catch {
+        throw new InvalidUploadTargetError("missing");
+    }
+    try {
+        realCandidate = await realpath(candidate);
+    }
+    catch (err) {
+        if (isNodeErrorWithCode(err, "ENOENT")) {
+            throw new InvalidUploadTargetError("missing");
+        }
+        throw err;
+    }
+    // Defence in depth: even if both lexical paths land inside the project
+    // root, a symlink under the project may point outside. Compare canonical
+    // paths to catch `<project>/escape -> /tmp/elsewhere` redirects.
+    if (realCandidate !== realRoot && !realCandidate.startsWith(realRoot + sep)) {
+        throw new InvalidUploadTargetError("path-traversal");
+    }
+    let st;
+    try {
+        st = await stat(realCandidate);
+    }
+    catch {
+        throw new InvalidUploadTargetError("missing");
+    }
+    if (!st.isDirectory()) {
+        throw new InvalidUploadTargetError("not-a-dir");
+    }
+    return realCandidate;
+}
+/**
+ * Persist `inputs` into `targetDir` (already validated by
+ * `resolveTargetDir`) and return a result entry per input describing
+ * what happened on disk.
+ *
+ * `disposition` decides conflict semantics:
+ * - `replace`   -- overwrite existing files in place via atomic rename
+ * - `keep-both` -- write next to the existing file with `-2`, `-3`, ...
+ * - `skip`      -- preflight all collisions; if any exist, throw
+ *                 `UploadConflictError` and write nothing
+ *
+ * `targetDir` must be the canonical (realpath-ed) directory; this
+ * function asserts every claim path lives under it as a defence-in-depth
+ * fence behind `resolveTargetDir`.
+ */
+export async function saveUploads(targetDir, inputs, disposition, deps = {}) {
+    if (inputs.length === 0)
+        return [];
+    const openFn = deps.openForTest ?? open;
+    if (disposition === "skip") {
+        const conflicts = [];
+        for (const input of inputs) {
+            const sanitized = sanitizeUploadFilename(input.filename);
+            const candidate = resolve(targetDir, sanitized);
+            if (!candidate.startsWith(targetDir + sep)) {
+                throw new InvalidUploadFilenameError("path-traversal");
+            }
+            try {
+                await stat(candidate);
+                conflicts.push(sanitized);
+            }
+            catch (err) {
+                if (!isNodeErrorWithCode(err, "ENOENT"))
+                    throw err;
+            }
+        }
+        if (conflicts.length > 0) {
+            throw new UploadConflictError(conflicts);
+        }
+    }
+    const results = [];
+    for (const input of inputs) {
+        const sanitized = sanitizeUploadFilename(input.filename);
+        const { base, ext } = splitBasenameExt(sanitized);
+        let finalName = sanitized;
+        let target = resolve(targetDir, finalName);
+        if (!target.startsWith(targetDir + sep)) {
+            throw new InvalidUploadFilenameError("path-traversal", `refusing to write outside ${targetDir}`);
+        }
+        let status;
+        if (disposition === "replace") {
+            // writeFileAtomic uses a temp + rename so we either overwrite
+            // atomically or leave the original untouched. No O_EXCL claim
+            // because we explicitly intend to replace.
+            await writeFileAtomic(target, Buffer.from(input.bytes));
+            status = "written";
+        }
+        else {
+            // keep-both (default): claim with O_EXCL, retry with -2, -3, ...
+            let attempt = 2;
+            let claimed = false;
+            let renamed = false;
+            while (!claimed) {
+                if (!target.startsWith(targetDir + sep)) {
+                    throw new InvalidUploadFilenameError("path-traversal", `refusing to write outside ${targetDir}`);
+                }
+                try {
+                    const fh = await openFn(target, "wx");
+                    await fh.close();
+                    claimed = true;
+                }
+                catch (err) {
+                    if (!isNodeErrorWithCode(err, "EEXIST"))
+                        throw err;
+                    if (attempt > MAX_SUFFIX_ATTEMPTS) {
+                        throw new Error(`saveUploads: exhausted ${MAX_SUFFIX_ATTEMPTS} collision slots for ${sanitized}`);
+                    }
+                    finalName = `${base}-${attempt}${ext}`;
+                    target = resolve(targetDir, finalName);
+                    attempt += 1;
+                    renamed = true;
+                }
+            }
+            await writeFileAtomic(target, Buffer.from(input.bytes));
+            status = renamed ? "renamed" : "written";
+        }
+        results.push({
+            originalName: input.filename,
+            status,
+            finalName,
+            finalPath: target,
+        });
+    }
+    return results;
+}
+function isNodeErrorWithCode(err, code) {
+    return (err instanceof Error &&
+        "code" in err &&
+        err.code === code);
+}
+//# sourceMappingURL=file-uploads.js.map

package/server/fs/file-uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-uploads.js","sourceRoot":"","sources":["../../src/fs/file-uploads.ts"],"names":[],"mappings":"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"}

package/server/fs/file-watcher.d.ts

@@ -0,0 +1,22 @@
+export type FileChangeEvent = "create" | "update" | "delete";
+type FileChangeCallback = (event: FileChangeEvent, relPath: string) => void;
+type GitignoreChangeCallback = () => void;
+type GitRefChangeCallback = () => void;
+type IsIgnoredCallback = (relPath: string, isDir: boolean) => boolean;
+export declare class FileWatcher {
+    private subscription;
+    private readonly root;
+    private readonly onChange;
+    private readonly onGitignoreChange;
+    private readonly onGitRefChange;
+    private readonly isIgnored;
+    private debounceTimers;
+    private gitRefTimer;
+    private gitignoreTimer;
+    constructor(root: string, onChange: FileChangeCallback, onGitignoreChange?: GitignoreChangeCallback, onGitRefChange?: GitRefChangeCallback, isIgnored?: IsIgnoredCallback);
+    start(): Promise<void>;
+    private handleEvent;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=file-watcher.d.ts.map

package/server/fs/file-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-watcher.d.ts","sourceRoot":"","sources":["../../src/fs/file-watcher.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC7D,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAC5E,KAAK,uBAAuB,GAAG,MAAM,IAAI,CAAC;AAC1C,KAAK,oBAAoB,GAAG,MAAM,IAAI,CAAC;AACvC,KAAK,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAOtE,qBAAa,WAAW;IACtB,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,cAAc,CAAoD;IAC1E,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,cAAc,CAA8C;gBAGlE,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,kBAAkB,EAC5B,iBAAiB,CAAC,EAAE,uBAAuB,EAC3C,cAAc,CAAC,EAAE,oBAAoB,EACrC,SAAS,CAAC,EAAE,iBAAiB;IASzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,OAAO,CAAC,WAAW;IAmDb,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB5B"}

package/server/fs/file-watcher.js

@@ -0,0 +1,105 @@
+import { realpathSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { subscribe } from "@parcel/watcher";
+const FILE_IGNORED = new Set([".DS_Store", "Thumbs.db"]);
+const GIT_REF_PATHS = /^\.git\/(HEAD|index|refs\/)/;
+const DEBOUNCE_MS = 300;
+const GIT_REF_DEBOUNCE_MS = 500;
+export class FileWatcher {
+    subscription = null;
+    root;
+    onChange;
+    onGitignoreChange;
+    onGitRefChange;
+    isIgnored;
+    debounceTimers = new Map();
+    gitRefTimer = null;
+    gitignoreTimer = null;
+    constructor(root, onChange, onGitignoreChange, onGitRefChange, isIgnored) {
+        this.root = realpathSync(root);
+        this.onChange = onChange;
+        this.onGitignoreChange = onGitignoreChange ?? (() => { });
+        this.onGitRefChange = onGitRefChange ?? (() => { });
+        this.isIgnored = isIgnored ?? (() => false);
+    }
+    async start() {
+        try {
+            this.subscription = await subscribe(this.root, (err, events) => {
+                if (err)
+                    return;
+                for (const event of events) {
+                    this.handleEvent(event.type, event.path);
+                }
+            }, { ignore: [join(this.root, "node_modules")] });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`File watching disabled for ${this.root}: ${message}`);
+            this.subscription = null;
+        }
+    }
+    handleEvent(type, absPath) {
+        const relPath = relative(this.root, absPath);
+        const name = relPath.split(sep).pop() ?? "";
+        if (FILE_IGNORED.has(name))
+            return;
+        const posixRel = sep === "/" ? relPath : relPath.split(sep).join("/");
+        if (GIT_REF_PATHS.test(posixRel)) {
+            if (!this.gitRefTimer) {
+                this.gitRefTimer = setTimeout(() => {
+                    this.gitRefTimer = null;
+                    this.onGitRefChange();
+                }, GIT_REF_DEBOUNCE_MS);
+            }
+            return;
+        }
+        if (posixRel.startsWith(".git/") || posixRel === ".git")
+            return;
+        if (posixRel === ".gitignore" && (type === "create" || type === "update")) {
+            if (this.gitignoreTimer)
+                clearTimeout(this.gitignoreTimer);
+            this.gitignoreTimer = setTimeout(() => {
+                this.gitignoreTimer = null;
+                this.onGitignoreChange();
+            }, DEBOUNCE_MS);
+        }
+        if (posixRel !== ".gitignore") {
+            let isDir = false;
+            try {
+                isDir = statSync(absPath).isDirectory();
+            }
+            catch {
+                // path may no longer exist (delete event) -- treat as file
+            }
+            if (this.isIgnored(posixRel, isDir))
+                return;
+        }
+        const key = `${type}:${posixRel}`;
+        const existing = this.debounceTimers.get(key);
+        if (existing)
+            clearTimeout(existing);
+        this.debounceTimers.set(key, setTimeout(() => {
+            this.debounceTimers.delete(key);
+            this.onChange(type, posixRel);
+        }, DEBOUNCE_MS));
+    }
+    async stop() {
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        if (this.gitRefTimer) {
+            clearTimeout(this.gitRefTimer);
+            this.gitRefTimer = null;
+        }
+        if (this.gitignoreTimer) {
+            clearTimeout(this.gitignoreTimer);
+            this.gitignoreTimer = null;
+        }
+        if (this.subscription) {
+            await this.subscription.unsubscribe();
+            this.subscription = null;
+        }
+    }
+}
+//# sourceMappingURL=file-watcher.js.map

package/server/fs/file-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-watcher.js","sourceRoot":"","sources":["../../src/fs/file-watcher.ts"],"names":[],"mappings":"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"}

package/server/fs/git-watcher.d.ts

@@ -0,0 +1,76 @@
+import type { GitState } from "@parasor/shared";
+/**
+ * Parse `git status --porcelain` output into a map of relative paths to status codes.
+ * Format per line: "XY path" where X=index status, Y=worktree status.
+ * Returns the most relevant single status character per file.
+ */
+export declare function parseGitPorcelain(raw: string): Record<string, string>;
+export interface GitStatusV2Counts {
+    /** Commits ahead of upstream. `undefined` when no upstream tracking. */
+    ahead?: number;
+    /** Commits behind upstream. `undefined` when no upstream tracking. */
+    behind?: number;
+    /** Tracked changes + untracked entries (rename pairs counted once). */
+    dirtyCount: number;
+}
+/**
+ * Parse `git status --porcelain=v2 -b` output into ahead/behind/dirtyCount.
+ *
+ * v2 line shapes (per `git-status(1)`):
+ *   `# branch.ab +N -M`           upstream tracking header (omitted when no upstream)
+ *   `1 XY ...`                    ordinary changed entry
+ *   `2 XY ...`                    rename/copy entry
+ *   `u XY ...`                    unmerged entry
+ *   `? <path>`                    untracked
+ *   `! <path>`                    ignored (excluded from dirtyCount)
+ *
+ * `dirtyCount` includes 1/2/u entries plus `?` untracked. Ignored `!` is
+ * deliberately excluded so the sidebar counter matches what the user sees as
+ * actionable change.
+ */
+export declare function parseGitStatusV2(raw: string): GitStatusV2Counts;
+export interface GitStatusV2Snapshot {
+    branch: string;
+    ahead?: number;
+    behind?: number;
+    dirtyCount: number;
+    fileStatuses: Record<string, string>;
+}
+/**
+ * Parse `git status --porcelain=v2 -b -z` output into both the file-status
+ * map (used by the filetree diff badges) and the ahead/behind/dirtyCount
+ * summary (used by WorktreeTabBar). One pass replaces the earlier
+ * v1+v2 dual call so the watcher can refresh the live counters on every
+ * tick without an extra `git status` round-trip.
+ *
+ * v2 entry shapes (`git-status(1)` `--porcelain=v2`):
+ *   `1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>`        ordinary entry
+ *   `2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path>\t<orig>`  rename
+ *   `u <XY> ...`                                            unmerged
+ *   `? <path>`                                              untracked
+ *   `! <path>`                                              ignored (skipped)
+ *
+ * `-z` switches to NUL-delimited records and disables the legacy
+ * shell-quoted path encoding, so paths with spaces / unicode arrive verbatim
+ * without us having to decode escape sequences.
+ */
+export declare function parseGitStatusV2WithFiles(raw: string): GitStatusV2Snapshot;
+export declare class GitWatcher {
+    private cache;
+    check(worktreePath: string): Promise<GitState | null>;
+    checkAndDiff(projectId: string, worktreePath: string): Promise<{
+        state: GitState | null;
+        changed: boolean;
+    }>;
+    getCached(projectId: string, worktreePath: string): GitState | null;
+    /**
+     * Snapshot of every cached state grouped by project. Outer key = projectId,
+     * inner key = worktreePath. Hydration payload consumes this shape directly.
+     */
+    getAllCached(): Record<string, Record<string, GitState | null>>;
+    /** Clear all worktree entries belonging to a project. */
+    clearProject(projectId: string): void;
+    /** Clear a single worktree entry. */
+    clearWorktree(projectId: string, worktreePath: string): void;
+}
+//# sourceMappingURL=git-watcher.d.ts.map

package/server/fs/git-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-watcher.d.ts","sourceRoot":"","sources":["../../src/fs/git-watcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AA4DhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBrE;AAED,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAsB/D;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAkE1E;AAuBD,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAsC;IAE7C,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA6CrD,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IA+BxD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAInE;;;OAGG;IACH,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC;IAc/D,yDAAyD;IACzD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAOrC,qCAAqC;IACrC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;CAG7D"}